Hyperstruck
How it works

Obligations

Claims about something someone owes, usually by a date. How they are opened, how your agent sees them, and how to list, add, close and move them.

In short

An obligation is a claim that someone owes something, usually by a date. It stays open until a person, an API key or a later document says it was done or dropped. A due date passing never closes it; the obligation is shown as overdue instead.

What an obligation is

When a document or a finished task says someone will do something, such as send a quote, reply to a notice or deliver a part, Hyperstruck records it as an obligation. It is filed under the entity it concerns, like any claim, and adds three things:

PartWhat it holds
What is owedThe commitment, in the source's own words
Who owes itThe party the source names, when it names one
Due dateWhen it is due, if the source says

Open, done or dropped

stateMeaningHow your agent reads it
openStill owed"Open since 9 October 2026, due 6 November 2026: …"
open, past its due dateStill owed, and late"…, due 6 November 2026, overdue: …"
doneMet"Done on 4 November 2026: …"
endedDropped, so nothing is owed now"Dropped on 4 November 2026: …"

Overdue is measured against the moment you read: now, or the past date you asked about.

Where obligations come from

  • Your documents. Anything you send through the Documents API or distill is read for commitments along with every other claim.
  • Your agents' finished work. When your agent reports a finished task, its goal, steps and final message are read too, so an agent that ends with "I'll confirm the volumes by Friday" leaves an open obligation of its own.
  • People and API keys. Add one directly.

On distill, write commitments into an item's content. A request that carries a separate obligations list is refused with 422.

Who owes it

When the source names who owes the obligation, that party is recorded as its holder, and reads return it as holder: its entity id, name, type and category. A person or API key can set or change the holder when closing or changing an obligation. Once a holder is recorded, your agent's text says "owed by Brightway Haulage", and you can list everything one party owes with owner.

You can also record who it is owed to, with recipient_entity_id. Reads do not return the recipient.

How your agent sees obligations

Obligations reach your agent the same way as every other claim:

  • Before each task. Resolve includes the open obligations on the entities the task names. It does not pick obligations by due date, so one due tomorrow on an entity the task does not mention is not included.
  • By searching. Claims search with "kind": "obligation", "state": "open" lists them.
  • By listing. List obligations is the complete list. Use it whenever an agent must see everything outstanding.

List obligations

Every open obligation due before 7 November:

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-07T00:00:00Z"
ParameterMeaning
kind=obligationOnly obligations
stateopen, done or ended
due_before, due_afterDue before this time, or at or after it, with a time zone offset
duedated for obligations with a due date, none for those without
order=dueSoonest due first. due_before and due_after imply it
ownerObligations this entity is recorded as owing
entityObligations filed under this entity
as_ofWhat was open at an earlier time

The response counts how many lines match in total, and how many of the dated ones are past due in overdue. Paging and errors are as for List claims. An entity's dossier also lists the newest 25 open obligations filed under it, in owed.

Add an obligation

Send POST /agents/{agent_id}/statements on an attribute whose kind is obligation, without replaces. To find an attribute_id, list the attributes with kind=obligation.

curl -X POST "https://api.hyperstruck.com/agents/<AGENT_ID>/statements" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee",
    "entity_id": "f403c2d1-cbc4-403d-9c50-32191ff6640a",
    "attribute_id": "6faa2be9-1559-4dee-b265-2d59871d528b",
    "value": { "type": "text", "text": "Revised rate card for the Northern route" },
    "due_at": "2026-11-14T17:00:00+11:00",
    "holder_entity_id": "e2a97c35-1f4d-4b80-8c6a-3d5b7f9e1a04",
    "note": "Agreed on the account call."
  }'

The new obligation is open. The response gives the new statement_id and the line's item.

Close or change an obligation

Send POST /statements with replaces set to the open obligation's current.id. Anything you leave out carries over.

ToSend
Mark it done"mode": "done"
Drop it"mode": "dropped"
Move the due date"due_at": "2026-11-13T17:00:00Z"
Record who owes it"holder_entity_id": "<entity id>"
Record who it is owed to"recipient_entity_id": "<entity id>"
{
  "request_id": "ffffffff-ffff-4fff-8fff-ffffffffffff",
  "replaces": "cdb4f0b6-7b3f-489c-80cb-b2a56d39f2f4",
  "mode": "done",
  "note": "Response received by email on 4 November."
}

Only the obligation you name closes; others filed under the same entity stay open. mode, due_at, holder_entity_id and recipient_entity_id are refused on an attribute that is not an obligation. Retries, conflicts and errors work as for every write.

A later document can close an obligation too, but only when it reports that very item done in full, and comes from someone who may speak for it: whoever owes it, whoever asked for it, any source that names the item and says who did it, or a record with no author, such as a status field, that names the item. An email that says Brightway Haulage sent its response to the arbitration notice on 4 November marks it done. A plan, someone else's offer to help, or a report of part of the work leaves it open. A question, or an ask put to anyone, closes on its asker, on a direct reply that names it, or on a direct reply in its thread saying the replier did it, when the message it answers asks nothing else.

Reinforce and decline do not close obligations. A body that carries obligation_outcomes is refused with 422:

{
  "detail": {
    "code": "field_retired",
    "message": "obligations are claims now: report a met obligation with POST /agents/{agent_id}/statements (correct)",
    "field": "obligation_outcomes"
  }
}