Claims API

Before you start

Every route is under https://api.hyperstruck.com/agents/{agent_id}, where agent_id is the agent's UUID, and takes Authorization: Bearer <API_KEY>. Each needs one of these scopes:

claims:correct and claims:curate are never passed on to a run your agent starts. Access control covers how scopes are granted.

A write also needs curate access to the agent. Contributors and stewards of its home space have it, and so do its managers, org admins and write keys that reach its home space. A write to a claim also needs the right to write into the claim's space.

Some decisions are for a person, not an API key: merging or splitting entities, adding a name, folding attributes together, changing an attribute's nature, and removing protection. An API key that tries gets 403 person_required.

Protected values are withheld

Every read on this page hides the values of protected attributes, such as a bank account number, wherever they appear: in a claim's value and statement, in the text written for your model, and in document passages. A value with four or more digits reads by its last four, Ends 5560; a shorter one reads Withheld. Ids and cursors are never changed.

The response to a write is not a read, and shows the values in full.

To see the values on a read, add reveal=true to the query. Only a caller holding claims:curate who may also change the agent may ask. Anyone else gets 403 curate_required.

Read claims

To ask a question in words, such as "Who looks after the Kestrel Foods account?", use Claims search. The routes below read claims by entity, by date or by state.

List claims

GET /agents/{agent_id}/claims lists the agent's claims, one item per line. With no parameters you get every line, a page at a time; the parameters narrow it.

Times need a time zone offset (2026-11-01T00:00:00Z); a time without one is a 422. An entity or owner that is not held, or that you cannot read, is a 404. An entity with no claims gives "items": [].

The response carries items, total (how many lines the filter matches across every page) and cursor, which is null on the last page. A read of dated obligations also carries overdue, how many of them are past due. A cursor works only with the order and filters it was handed out under; with any other it is 422 invalid_cursor.

curl -G "https://api.hyperstruck.com/agents/<AGENT_ID>/claims" \
  -H "Authorization: Bearer <API_KEY>" \
  --data-urlencode "kind=obligation" \
  --data-urlencode "state=open" \
  --data-urlencode "due_before=2026-11-01T00:00:00Z"

Every field of an item is described in The claim item.

Find or list entities

GET /agents/{agent_id}/entities?q=okoye finds the entities whose name or other names match q (1 to 200 characters), best match first. limit is 1 to 50, default 10.

{
  "items": [
    { "id": "22222222-2222-4222-8222-222222222222", "name": "Dr Imani Okoye", "type": "person", "category": "person", "affiliation": null }
  ]
}

type is one of person, organisation, location, project, asset, register_item and agreement. category is the word your documents use for it, such as "patient" or "shipment". affiliation is the entity's newest relation, which helps tell two people with the same name apart, or null.

Leave out q and the route lists every entity the agent holds a live claim about: people, organizations, places, projects and records first, then every other type, each group with the most recently changed first. Narrow it with type, repeated for several. Each entity then also carries details (its live claims that are not obligations), owed (its open obligations), overdue (how many of those are past due) and latest (the attribute and date of its newest change). The response adds total for the type you asked for, type_counts for every type, and a cursor. A cursor from a different type filter is 422 invalid_cursor.

Read an entity's dossier

GET /agents/{agent_id}/entities/{entity_id}/dossier returns everything held about one entity.

aliases, fields, relations, owed and possible_duplicates come on the first page only.

To see more than 25 obligations, list them with GET /claims?entity=<entity_id>&kind=obligation.

detail, here and in Claims search, sets how much each line carries:

Read what changed

GET /agents/{agent_id}/entities/{entity_id}/changes?since=2026-10-01T00:00:00Z lists every detail of the entity that changed between since and until (default: now), newest first. Each item gives the line, the claim it held before (from) and the claim it holds after (to). from is null for a new detail, and to is null for one that ended.

The response also carries text, the changes written out for your model:

2 changes on Dr Imani Okoye since 1 October 2026.
Clinic days changed on 3 November 2026. Before: From next week Dr Imani Okoye runs her clinics on Tuesday and Thursday mornings. Now: From 3 November Dr Okoye's clinics move to Wednesdays.
Task is new on 20 October 2026: Dr Imani Okoye is to send the referral letter to the patient by 30 October 2026.

Page with limit (1 to 200, default 50) and cursor, sending the same since and until with every page. A cursor from another read, or an until earlier than since, is a 422.

See where an entity's claims came from

GET /agents/{agent_id}/entities/{entity_id}/sources lists the documents that gave claims about the entity, newest first. The documents of one thread, such as a chat channel or an email thread, count as one source.

The response carries entries, total (sources), total_documents and cursor. limit is 1 to 200, default 50. A cursor from another entity is 422 invalid_cursor.

List what is left to decide

GET /agents/{agent_id}/to-decide lists everything waiting for a person in one place: conflicting lines, and pairs of entities that may be the same. Each entry has a kind: conflict, carrying the line's item in conflict, or duplicate, carrying both entities, the rule that raised it and a reason_sentence in duplicate.

The response carries entries, groups, total and cursor. A pair whose two sides have since been merged is left out.

List the documents that changed something

GET /agents/{agent_id}/claim-documents lists the documents that changed the agent's claims, newest first by the document's own date. A document that changed nothing is not listed. Each entry counts what it did, with the first three lines of each at full detail:

Narrow it with scope (an entity and its neighbors), raised_after or document (one document, by its id or your own doc_id). limit is 1 to 200, default 50.

List the claims a learning uses

A learning can mention a detail that comes from a claim, such as a customer's plan, so it stays right when the detail changes. GET /agents/{agent_id}/learnings/{learning_id}/claims lists each such detail, with the claim it first came from and what it shows now.

status keeps only the details whose claim is in that state. limit is 1 to 100, default 25, and the next page's token is next_cursor. When the claims cannot be read, the list still answers 200, with is_degraded: true and every detail unresolved; read it again. A cursor that is not this list's is 400 cursor_invalid.

The claim item

Every read returns the same item, one per line.

Each claim in current, beside and history carries:

A document's cite is exactly what POST /documents/citations:resolve takes, so you can turn it back into the passage's words. When the document has no version that can be cited, cite.passage carries only document_id and index, and cannot be resolved.

Every write

Every POST on this page takes a request_id: a UUID you make, in its 36-character form. It makes retrying safe.

• Retry with the same request_id and the same body and nothing is written twice. You get back the ids the first request wrote.
• Send the same request_id with a different body and you get 422 request_id_reused.
• A refused write leaves its request_id free to use again.
• Two people or keys sending the same request_id make two separate requests.

Leaving a field out is the same as sending null. An unknown field is a 422.

Every write is recorded as made by the person or key that sent it, by name. A note (up to 2,000 characters) is kept with it and shown wherever the decision is.

Settle a conflict

When two sources disagree, POST /agents/{agent_id}/verdicts says which claim stands, or that both do.

curl -X POST "https://api.hyperstruck.com/agents/<AGENT_ID>/verdicts" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
    "statement_id": "55555555-5555-4555-8555-555555555555",
    "outcome": "stands",
    "note": "Confirmed by the practice manager on the phone."
  }'

statement_id is a claim on the conflicting line: its current.id or a beside[].id.

The response gives verdict_ids and the item of every line the decision changed. Settling a payment route nobody has confirmed confirms it, even when it has no conflict: send its statement_id with stands. Any other claim with no conflict to settle is 409 nothing_to_settle. An API key may not settle a conflict on a protected attribute (403 person_required).

Correct or add a claim

POST /agents/{agent_id}/statements records what is true now.

To correct a claim, name it in replaces. Every field you leave out is carried over from it:

{
  "request_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
  "replaces": "44444444-4444-4444-8444-444444444444",
  "value": { "type": "text", "text": "Wednesday mornings" },
  "note": "Rota change announced at the staff meeting."
}

To add a claim, leave out replaces and send entity_id, attribute_id and value:

{
  "request_id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
  "entity_id": "22222222-2222-4222-8222-222222222222",
  "attribute_id": "88888888-8888-4888-8888-888888888888",
  "value": { "type": "text", "text": "Tuesday and Thursday mornings" },
  "as_of": "2026-10-27T00:00:00Z"
}

The attribute must already exist; list the attributes to find its id.

On a detail that holds one value, correcting a value claim ends every other live claim on the line. Any other correction, such as one to an obligation, a reading, or a detail that holds several values, ends only the claim it replaces. The response gives the statement_id that now stands and the line's item.

A refusal names the field at fault. Common ones: a field that does not fit the attribute's kind, a replaced claim that has already ended (409 not_current, listing what holds now), or the entity's identity, which only fixing who is who changes.

On a protected attribute, an API key's correction to a value is held for a person to approve instead of being refused, as long as it is not dated earlier than the claim now standing on the line. Any other change an API key sends to a protected attribute is 403 person_required.

Fix who is who

When documents name the same person or company in different ways, or one name covers two different people, a signed-in person can fix it:

After a merge, the old id keeps working on every read and reads as the entity it merged into.

Attributes

An attribute is the name of a detail, such as "clinic days" or "support plan". Hyperstruck creates them as it reads; these routes let you tidy them.

List the attributes

GET /agents/{agent_id}/attributes lists every attribute in name order, including folded ones.

Each attribute carries id, name, kind, nature, protected, is_many_valued (whether it holds several values at once), and who folded it or set its nature, and when.

Fold one attribute into another

POST /attributes/{attribute_id}/fold with into says two names mean the same thing, such as "clinic days" and "clinic schedule". Their claims move onto into, and reads follow it. The two must be the same kind and both hold one value or both hold several, or the fold is 409 fold_refused with the reason.

Set an attribute's nature and protection

POST /attributes/{attribute_id}/nature takes nature and protected. Fields you leave out keep their value, and sending what the attribute already has changes nothing.

• nature is standing for a detail that holds until it changes, or reading for a measurement where each one keeps its own date.
• protected set to true means only a person can approve a change to its value. Protected details explains when to use it. An API key may set protected: true, and nothing else on this route; anything else it sends is 403 person_required. Setting protected: false on a protected attribute needs the right to change the agent (its home-space steward, a manager or an org admin); a person who may only curate gets 403 agent_write_required.

An attribute belongs to the whole agent, so these routes need write access to every space the agent keeps (403 all_spaces_required).

Erase an entity

POST /agents/{agent_id}/entities/{entity_id}/erasure, with no body, erases the entity, every claim about it, its other names and every decision about it. It works even while the agent's claims are still being rebuilt. The response is a receipt:

{
  "id": "99999999-9999-4999-8999-999999999999",
  "subject_kind": "entity",
  "subject_id": "22222222-2222-4222-8222-222222222222",
  "claims_erased": 14,
  "statements_erased": 11,
  "obligations_erased": 2,
  "relations_erased": 1,
  "verdicts_erased": 2,
  "aliases_erased": 1,
  "dossiers_rebuilt": 1,
  "claims_reopened": 0,
  "claims_reended": 0,
  "references_cleared": 3,
  "entities_unmerged": 0,
  "verdicts_written": 0,
  "insight_findings_deleted": 0,
  "residue": []
}

Most fields count what was removed: claims_erased is every claim, split into statements_erased, obligations_erased and relations_erased. These need a closer look:

Add ?dry_run=true to see the receipt the erasure would give without erasing anything. It needs the same access as the erasure itself.

Clear an agent's claims

DELETE /agents/{agent_id}/claims erases every claim the agent holds in one request.

{
  "wipe_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
  "agent_id": "3f0c1a52-8d4e-4b6a-9c1e-0a7d2b5e1f11",
  "entities_erased": 40,
  "claims_erased": 612,
  "attributes_removed": 31,
  "remaining_entities": 0,
  "has_residue": false,
  "request_ids": []
}

remaining_entities is always 0 and request_ids is always empty. The request accepts reason and ticket_ref, but neither is stored, so keep your own record of why you cleared it.

Limits

Too many reads at once answers 429 (or 503 when the whole server is busy) with code claim_reads_busy. Going over 60 a minute answers 429 with code claim_reads_rate_limited. Both carry retry_after_seconds in the body and the same number in a Retry-After header: for the per-minute limit, it is the seconds left in the minute.

Errors

A refused write carries {"detail": {"code": ..., "message": ..., "field": ...}}, where field names the part of the request at fault. Some refused reads carry a plain message in detail instead.

The claim store is still being rebuilt

An older agent may answer 409 claims_not_replayed on every claim read and write while its documents are read again into the current claim store. Once that finishes, it never answers it again. Agents created since never answer it, and erasure is never held back.

Related pages