Documents
POST /api/v1/documents and GET /api/v1/documents — create, update and list documents.
POST upserts on (collection, doc_id) and returns both keys: doc_id is
the one you supplied, and id is the row primary key. Either can be used to read
the document back.
A document is only reachable from Documents · Search
when its write supplies data.summary (or data.description for skills). The
write response reports this as indexed — a document without it is stored and
readable by id, but never returned by search.
APIKeyHeaderX-API-Key<token>Idempotency-Key?string|nullapplication/json- body
tenant_id?Tenant IdTenant to operate on. Omit it and the tenant is resolved from the credential, which is what a tenant- or agent-scoped key already identifies — no prior /whoami call is needed. Supply it to act on a different tenant your credential may read (and for an admin key, which belongs to no single tenant, it is required).
""fleet_id?string|nullagent_id?|Agent recorded as the author of this version. Omit it and an agent-scoped credential supplies its own identity. Replaced on each upsert, since an upsert replaces the document.
collection*CollectionNamespace grouping related documents, e.g. 'runbooks'. Chosen by the caller; created on first write. Part of the upsert key.
1 <= length <= 200doc_id*Doc IdYour own stable id for this document within the collection. Together with 'collection' it is the upsert key: writing the same pair again REPLACES the stored document rather than adding one, which is what makes a retry safe. No server-generated default — minting an id would turn every write into a new row.
1 <= length <= 500data*The document itself, as a free-form JSON object. This is where the payload goes — there is no top-level 'content' or 'title' field on a document. Replaced wholesale on each upsert. data['summary'], when present, is the string that gets embedded and is the only thing POST /documents/search can match on.
force?ForcefalseSuccessful Response
application/json- response
indexed?boolean|nullid*Idtenant_id*Tenant Idfleet_id*string|nullcollection*Collectiondoc_id*Doc Iddata*created_at*|nullupdated_at*|nullagent_id?string|nullcurl -X POST 'https://example.com/api/v1/documents' \ -H 'Content-Type: application/json' \ -d '{ "collection": "string", "doc_id": "string", "data": {}}'{ "indexed": true, "id": "string", "tenant_id": "string", "fleet_id": "string", "collection": "string", "doc_id": "string", "data": {}, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "agent_id": "string"}APIKeyHeaderX-API-Key<token>tenant_id*Tenant Idcollection*Collectionfleet_id?string|nulllimit?Limit1 <= value <= 100050offset?Offset0 <= value0Successful Response
application/json- response
[index: integer]?curl -X GET 'https://example.com/api/v1/documents?tenant_id=string&collection=string'[ { "indexed": true, "id": "string", "tenant_id": "string", "fleet_id": "string", "collection": "string", "doc_id": "string", "data": {}, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "agent_id": "string" }]