Documents API

Use the Documents API to register the text your agents learn from, so a claim or a learning can point at the exact passage it came from rather than at a filename you have to go and find. A document is stored once and cited many times: the passage lives on the document, never beside the claim, which is what lets an erasure remove the quote everywhere in one operation.

Every route here is scoped to one agent, and the document key is yours. You choose it, we keep it exactly as you sent it, and you use it again to fetch, cite or erase.

Choosing a document key

doc_id is your own identifier, and it may contain slashes: policies/refunds.md is what a real key looks like, and the repository content ingest mints {owner}/{repo}:{path}, one file to one document.

It is checked for shape and returned verbatim. It is never trimmed, collapsed or normalised, because the key is your identity for the document, and normalising it would silently make two of your documents one. Two keys differing only by whitespace are two different documents.

A key is refused with a 400 when it is empty or only whitespace, is longer than 512 bytes of UTF-8 (bytes, not characters, so a multibyte key is shorter than it looks), carries a control character, carries a backslash, starts with /, has an empty path segment, or has a . or .. segment. Those last five each land the bytes somewhere other than the document's own prefix on a store that resolves its keys as paths.

Submit a document version

PUT /agents/{agent_id}/documents/{doc_id} stores one submission and queues it for ingest.

The body is the raw document, not JSON. Two optional headers describe it.

curl -X PUT \
  -H "Authorization: Bearer <API_KEY>" \
  -H "X-Document-Filename: refunds.md" \
  -H "X-Document-Type: markdown" \
  --data-binary @refunds.md \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/documents/policies/refunds.md"

Required scope: agents:write

The response carries doc_id, version, state, enqueued and job_id. version is the sha256 of the bytes you sent, which is also the version's identity.

Refusals happen at the door, before anything is enqueued, so a rejected submission never burns a queue slot:

Concurrent submissions of one doc_id are safe without any coordination on your side. Writers and erasures of a single document serialise, and two callers sending identical bytes both receive the same version rather than one of them receiving an error for something neither did wrong.

Say which account the document is about

The form above stores the bytes and nothing else. To make a document reachable by an account, send it as multipart/form-data with a content part and a metadata part instead.

This is the step nothing else can do for you. Every other way of working out which account a document concerns has to read the prose, so a helpdesk ticket called ticket-8837.json whose contents are about a workbook reaches no account at all. Your connector already knows which account it is; record_context is where you say so. A document submitted without one is stored and ingested perfectly well, and then Answer API will not find it when somebody asks about that account.

curl -X PUT \
  -H "Authorization: Bearer <API_KEY>" \
  -F "content=@review-2026-09-15.md;type=text/plain" \
  -F 'metadata={"title": "Meridian Books quarterly account review, September",
                "occurred_at": "2026-09-15T02:00:00Z",
                "record_context": {
                  "concerns": [
                    {"scheme": "crm:account", "value": "meridian-books", "name": "Meridian Books"}
                  ]
                }};type=application/json' \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/documents/crm/meridian-books/review-2026-09-15"

Each entry in record_context.concerns is one container the document belongs to:

Fetch a document and its versions

GET /agents/{agent_id}/documents/{doc_id} returns the document, every raw version, and two separate state fields.

curl -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/documents/policies/refunds.md"

Required scope: agents:read

A doc_id with neither a job nor a version is a 404, so a typo is distinguishable from a submission still sitting in the queue.

An ordinary re-upload has relation of amends, which retires nothing: the earlier version stays citable, and a citation minted against it keeps resolving.

Resolve a citation

POST /agents/{agent_id}/documents/citations:resolve turns a six-member citation back into the text it points at.

curl -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "citation": {
      "doc_id": "policies/refunds.md",
      "text_sha256": "<VERSION_SHA256>",
      "segmenter_version": "<SEGMENTER_VERSION>",
      "unit_index": 12,
      "start": 0,
      "end": 184
    }
  }' \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/documents/citations:resolve"

Required scope: agents:read

All six members are required. Five of six is a span with no end, or an end with no document, and resolving one would mean inventing the missing member. unit_index, start and end are integers, not numeric strings: a numeric string is a second shape for the same pointer and is refused.

The citation is in the body rather than the path because a document key may contain slashes, so /{doc_id}/citations:resolve could never be told apart from a document whose key ends in citations:resolve. The POST verb is what disambiguates this route, which means a document actually named citations:resolve is still fetched, written and erased correctly.

Four outcomes, kept distinct because you act on each differently:

Erase a document

DELETE /agents/{agent_id}/documents/{doc_id} destroys the wrapped data keys first, so from that instant every copy they protect is unreadable whether or not the deletes that follow complete. It then returns a receipt naming what each scope actually reached.

curl -X DELETE \
  -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/documents/policies/refunds.md"

Required scope: agents:write

Any queued or running ingest for the document is cancelled inside the same transaction that authorised the erasure. A deletion request is the one operation that must never queue behind other work, and cancelling first means an in-flight ingest cannot write new encrypted units under a key that is about to be destroyed.

After an erasure, citations pointing at that document resolve with outcome erased rather than failing, and any resolved passage stops being returned. This is the whole reason the passage is stored once on the document rather than copied beside each claim: there is no second copy to outlive the deletion.

Related

• Answer API for the read that consumes what you declared here: a question about an account is answered from the documents whose concerns name it.
• Claims for what a claim is and how a cited value differs from an asserted one.
• Claims API for reviewing and governing what your agents believe.
• Distill documents for extracting learnings from a corpus, which is a different operation: distill reads a corpus and returns learnings, while this API registers text so it can be cited.