Obligations API

Record an obligation

POST /agents/{agent_id}/obligations writes one obligation exactly as you state it.

curl -X POST "https://api.hyperstruck.com/agents/11111111-1111-4111-8111-111111111111/obligations" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "statement": "Send the signed carrier agreement to Harlow Freight",
    "owed_by": { "role": "account_manager" },
    "owed_to": { "entity": "Harlow Freight" },
    "due": { "at": "2026-10-09T00:00:00+11:00", "tz": "Australia/Sydney", "precision": "date" }
  }'

{
  "id": "66666666-6666-4666-8666-666666666666",
  "outcome": "written",
  "evicted_id": null,
  "reason": null
}

The response is always 202. Read outcome to learn what happened, because a refusal is reported there and not as an error status.

An unknown field is refused with a 422 that names it. A misspelled statment never produces a row missing its statement.

One further value, evicted_then_written, is in the contract and never returned by this route. It applies to obligations read from notes.

Parties

A party is a role, a name, or both.

Dates

due.at must carry an offset. A value such as 2026-10-09T00:00:00 is refused with a 422, never assumed to be UTC.

due.tz is the zone the due was stated in. Omitted, it falls back to the request's timezone, then the agent's own zone, then UTC. The obligation records which with due_tz_basis, and a value of defaulted means nothing was stated and the day may be wrong.

List obligations

GET /agents/{agent_id}/obligations returns an agent's obligations, open and closed.

curl -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/agents/11111111-1111-4111-8111-111111111111/obligations?status=open&limit=25"

Every filter combines with every other. The response is { "items": [...], "next_cursor": "..." }, and next_cursor is null on the last page.

review_reasons is filled only when you ask with needs_review=true. On any other read it is empty, which says nothing either way about the obligation.

Read one obligation

GET /agents/{agent_id}/obligations/{obligation_id} returns one obligation. Pass timezone to choose the zone due_local is rendered in.

{
  "id": "66666666-6666-4666-8666-666666666666",
  "agent_id": "11111111-1111-4111-8111-111111111111",
  "kind": "commitment",
  "statement": "Send the signed carrier agreement to Harlow Freight",
  "owed_by_role": "account_manager",
  "owed_by_entity_id": null,
  "owed_by_name": null,
  "owed_to_role": null,
  "owed_to_entity_id": "77777777-7777-4777-8777-777777777777",
  "owed_to_name": "Harlow Freight",
  "not_before": "2026-10-06T13:00:00Z",
  "due_at": "2026-10-09T13:00:00Z",
  "due_local": "2026-10-09",
  "due_tz": "Australia/Sydney",
  "due_tz_basis": "caller",
  "due_precision": "date",
  "lead_days": 3,
  "provenance_class": "user_directed",
  "status": "open",
  "kept_basis": null,
  "dropped_reason": null,
  "expired_reason": null,
  "superseded_by": null,
  "expires_at": "2026-10-23T13:00:00Z",
  "committed_at": "2026-10-01T01:47:16.322767Z",
  "closed_at": null,
  "version": 1,
  "note": null,
  "participants": [],
  "review_reasons": []
}

The example is shortened. The fields that matter most:

note.state says what you are looking at:

Close an obligation

POST /agents/{agent_id}/obligations/{obligation_id}/close ends an obligation as kept or dropped. It returns 200 with the obligation.

curl -X POST "https://api.hyperstruck.com/agents/11111111-1111-4111-8111-111111111111/obligations/66666666-6666-4666-8666-666666666666/close" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "kept", "kept_basis": "reported", "note": "Sent by email" }'

Only not_an_obligation counts against the source the obligation came from. The other three reasons judge the commitment, not the source.

Sending the same close twice is safe: the second returns 200 with the obligation and changes nothing. A close that contradicts the state already held, or a stale expected_version, is a 409 that tells you the current version:

{ "detail": { "message": "obligation is at version 2, not 1", "current_version": 2 } }

Cancel a record

POST .../{obligation_id}/cancel withdraws a record that should never have existed, such as a test write or a bad import. It takes an optional expected_version, and an empty body {} is valid. A note is accepted and not kept.

Cancel makes no judgment about the commitment. It does not count against any source, and the same obligation can be recorded again straight away, where a drop blocks an identical write for 30 days. When the source was wrong, close with not_an_obligation instead.

Cancelling an obligation that is already cancelled returns 200 and changes nothing. Cancelling one that closed any other way is a 409.

Move the due

POST .../{obligation_id}/reschedule changes the due and keeps the obligation's id. The body is { "due": { ... } } with the same due object as a write, plus an optional expected_version. The window and the expiry move with it.

If another open obligation already sits on the new day for the same party and action, the request is a 409. Close one of the two to resolve it.

Replace an obligation

POST .../{obligation_id}/supersede closes an obligation as superseded and writes its successor, linked, in one step.

{
  "successor": {
    "statement": "Send the signed carrier agreement and the rate card to Harlow Freight",
    "owed_by": { "role": "account_manager" },
    "owed_to": { "entity": "Harlow Freight" },
    "due": { "at": "2026-10-16T00:00:00+11:00", "tz": "Australia/Sydney", "precision": "date" }
  }
}

successor takes the same fields as a write. The 200 body is the successor, which is the open obligation you now care about. The original comes back from a read with "status": "superseded" and superseded_by set. Nothing changes unless the successor lands: one that collides with another open obligation, or repeats one dropped in the last 30 days, is a 409, and the original stays open.

Close obligations from the loop

An agent that acted on what resolve offered does not need one call per obligation. Two fields on the learning loop carry it.

Resolve returns the block and the ids:

Reinforce closes what the turn resolved. Send up to 50 entries in obligation_outcomes:

{
  "obligation_outcomes": [
    { "id": "66666666-6666-4666-8666-666666666666", "outcome": "kept", "kept_basis": "reported" }
  ]
}

Each entry takes id, outcome, kept_basis or dropped_reason, and an optional note, with the same rules as close. The response answers each one in obligation_closures, in the order you sent them:

One stale id never costs the run its reinforcement: it is answered not_offered and the rest proceed.

Send typed obligations with a note

A Distill evidence item can carry obligations you already know, in an obligations array with the same fields as a write. They are recorded as you state them, with no model involved, up to 8 per item and 50 per request. A relative due such as "next Friday" is refused, so resolve it to a date before sending.

Count what is open

GET /agents/{agent_id}/obligations/open-count returns { "open_count": 2 }: the open, unexpired obligations this agent holds now.

GET /org/obligations/open-count returns the same count across the tenant beside the metered one:

Pass usage_date for a day other than today, in UTC.

Read source reliability

GET /agents/{agent_id}/obligation-credit reports, for each source obligations were read from, how often they turned out to be real. The lowest score comes first.

The score is a readout. Reading obligations from a source is not gated on it. Pass limit, 1 to 500, default 200.

List across every agent

GET /org/obligations takes the same filters as the agent-scoped list and returns obligations from every agent, each carrying its own agent_id. With needs_review=true it is the review queue for the whole tenant.

Two things differ. timezone defaults to UTC, because a page spans agents. And the response says when your access narrowed it:

A search this wide can time out. It then returns 504 with a message asking you to narrow it by status, a shorter q, or due_before.

Limits

Errors

A 422 comes in two shapes. A field that fails validation returns a list naming it:

{ "detail": [{ "type": "extra_forbidden", "loc": ["body", "statment"], "msg": "Extra inputs are not permitted" }] }

A value the shelf itself refuses, such as an unknown time zone or a malformed cursor, returns a string:

{ "detail": "unknown timezone 'Mars/Olympus'" }

Related pages