Claims search

What you get back

A search result has two halves that say the same thing:

• text is the claims written out as short dated lines, ready to pass to your model. It is built from the claims themselves, so it never says anything the claims do not, and it never decides which claim is right. Your model reads it and writes the reply.
• claims is the same claims as structured items, best match first. Each one carries its value, its dates, its state and its source, so you can show where a detail came from or resolve the citation back to the passage in the original document.

Searching costs nothing and writes nothing, so you can search as often as you like and retry without an idempotency key. Results are not stored: to see the latest, search again.

Search with a question

Send the question, and optionally how much detail each item should carry:

curl -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"question": "Where is the damage dispute on shipment HF-20418 up to?", "detail": "cited"}' \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/claims/search"

Request

Any other field is refused with 422, and so is a time without a time zone offset.

Protected values, such as a bank account number, are withheld from the text and the items: the result reads "Ends 8765" in their place. To see them, add ?reveal=true to the URL. Only a caller holding claims:curate who may also change the agent may ask; anyone else gets 403 curate_required. More on withheld values.

Kinds of result

What you send decides what kind of result comes back, and shape tells you which one you got:

Tap to enlarge

A set is the same list as GET /claims, one claim a line, and pages with cursor. A since result gives what GET /entities/{entity_id}/changes gives.

Response

Each item in claims also carries two scores. word_share is how much of the question's wording the claim shares, from 1 for the best match down to 0. cosine is how close the claim is to the question in meaning, or null when meaning was not compared.

Reading the text

When a point or as_of search finds claims, the text opens "What the account holds nearest this question:", then one line per entity and detail, with dates. The claims are the nearest the account holds, and may not answer the question: your model judges whether they do, and can quote the lines directly. When every claim was found by meaning alone (shares_no_word is true), a second line follows the opening one: "No claim shares a word with the question; these are the nearest by meaning."

When it finds nothing, the text opens with one of these lines instead:

Under the lead value, other claims on the same line follow. A claim shown beside the lead or as its history also gives its opening words in its label field, such as "Also on record, 21 October 2026". The lead value, obligation lines and "Both stand" have no label.

When two sources give different values and neither replaces the other, the newest leads and the other follows as "Also on record", so your model sees both instead of one side.

What to check in every result

• degraded is set. The search matched by wording only, and every cosine is null. embedding_unavailable means the question could not be compared by meaning this time; vectors_loading means the agent's claims are not ready to compare by meaning yet. If the wording matched nothing either, claims is empty and text says so. Search again for a full result.
• more_matched is above 0. More claims matched than the result could include. Narrow the question, name an entity, or list them with GET /claims.
• A line in text has no item. A point or as_of result holds up to 20 items, but text can name a few more claims as one-line entries. To cite one of those, look it up with GET /claims.
• You sent since without naming an entity. You get the best-matching claims instead, and the text ends by asking you to name an entity.
• You sent since with a filter. You get the whole set, and the text ends by saying since did not narrow it.

limit applies to a set or since result, and cursor to a set result. Both are ignored otherwise. A since result that holds less than changed ends by saying so and pointing at the list to read the rest.

From an MCP client

The Hyperstruck MCP server has a search_claims tool that takes the same fields, plus agent_id. It is free and writes nothing. The server replaces secrets and personal details in the question with placeholders before sending it (which details), so the same question can find different claims through MCP than through the API.

Limits

Errors

Related pages