REST API reference
The REST API is at https://api.<trial host>/. It takes the same bearer tokens as the MCP server,
issued for the REST audience. Each operation below lists the scope it needs, its parameters, its
request body and the responses it can return.
This page is generated from a snapshot of the service's OpenAPI document, and a test fails if the
two differ. Operations an administrator uses from the console, such as schema changes, exports and
deletion, are not listed here.
The service's OpenAPI document leaves some response bodies untyped, among them POST /context and the
/memory operations. For their fields, see the matching tool in the MCP tool reference:
assemble_context, record_memory, supersede_memory, recall_memory and get_memory_history return the same
shapes.
POST /documents
Upload a document, or a new revision of one by externalId
- Scope
- kg:write
- Request body
application/json: string
Parameters| Name | In | Required | Type |
|---|
title | query | no | string |
externalId | query | no | string |
KG-Contract-Version | header | no | 1 | 2 | 3 |
KG-Confirmation | header | no | string |
Responses| Status | Meaning |
|---|
| 200 | Content unchanged; nothing created |
| 202 | Revision stored and job queued |
| 400 | The body is not a valid upload request |
| 401 | Missing or invalid credentials |
| 403 | The caller lacks the route's scope |
| 409 | Another upload for this externalId is still processing |
| 413 | The body or the normalized text is over its limit |
| 415 | The media type or content encoding is not accepted |
| 422 | CONFIRMATION_INVALID: the token is unknown, expired, another principal's or tenant's, or for a different request; nothing changed. |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 428 | The operation needs confirmation; nothing changed. Resend the identical request with KG-Confirmation set to token before expiresAt. |
| 429 | A tenant or identity cap would be exceeded; nothing was stored |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
GET /documents
List the tenant's documents
- Scope
- kg:read
Parameters| Name | In | Required | Type |
|---|
limit | query | no | string |
cursor | query | no | string |
count | query | no | string |
contains | query | no | string |
prefix | query | no | string |
state | query | no | string |
order | query | no | string |
Responses| Status | Meaning |
|---|
| 200 | One page of documents, each with its newest revision's state, failure reason, media type and size (latestRevision); with count=true, the list's total, exact up to 10,000 (total, totalExact) |
| 400 | limit, cursor, count, contains, prefix, state or order is invalid, or the cursor belongs to another search, filter or order |
| 401 | Missing or invalid credentials |
| 403 | The caller lacks the route's scope |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
GET /documents/{documentId}
A document and its retained revisions
- Scope
- kg:read
Parameters| Name | In | Required | Type |
|---|
documentId | path | yes | string |
Responses| Status | Meaning |
|---|
| 200 | The document |
| 401 | Missing or invalid credentials |
| 403 | The caller lacks the route's scope |
| 404 | No such document in this tenant |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
POST /documents/{documentId}/revisions
Upload a new revision of a document
- Scope
- kg:write
- Request body
application/json: string
Parameters| Name | In | Required | Type |
|---|
documentId | path | yes | string |
title | query | no | string |
externalId | query | no | string |
KG-Contract-Version | header | no | 1 | 2 | 3 |
KG-Confirmation | header | no | string |
Responses| Status | Meaning |
|---|
| 200 | Content unchanged; nothing created |
| 202 | Revision stored and job queued |
| 400 | The body is not a valid revision request |
| 401 | Missing or invalid credentials |
| 403 | The caller lacks the route's scope |
| 404 | No such document in this tenant |
| 409 | Another upload for this document is still processing |
| 413 | The body or the normalized text is over its limit |
| 415 | The media type or content encoding is not accepted |
| 422 | CONFIRMATION_INVALID: the token is unknown, expired, another principal's or tenant's, or for a different request; nothing changed. |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 428 | The operation needs confirmation; nothing changed. Resend the identical request with KG-Confirmation set to token before expiresAt. |
| 429 | A tenant or identity cap would be exceeded; nothing was stored |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
GET /documents/{documentId}/revisions/{revision}
A retained revision's metadata and one page of its passage map
- Scope
- kg:read
Parameters| Name | In | Required | Type |
|---|
documentId | path | yes | string |
revision | path | yes | string |
fromOrdinal | query | no | string |
limit | query | no | string |
Responses| Status | Meaning |
|---|
| 200 | The revision |
| 400 | fromOrdinal or limit is invalid |
| 401 | Missing or invalid credentials |
| 403 | The caller lacks the route's scope |
| 404 | No such document or revision in this tenant |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
GET /documents/{documentId}/revisions/{revision}/passages/{ordinal}
One passage of a retained revision, as a citation
- Scope
- kg:read
Parameters| Name | In | Required | Type |
|---|
documentId | path | yes | string |
revision | path | yes | string |
ordinal | path | yes | string |
Responses| Status | Meaning |
|---|
| 200 | The passage |
| 401 | Missing or invalid credentials |
| 403 | The caller lacks the route's scope |
| 404 | No such passage in this tenant |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
GET /documents/{documentId}/revisions/{revision}/original
The PDF or Word file a revision was uploaded as (026)
- Scope
- kg:read
Parameters| Name | In | Required | Type |
|---|
documentId | path | yes | string |
revision | path | yes | string |
Responses| Status | Meaning |
|---|
| 200 | The file, as an attachment |
| 401 | Missing or invalid credentials |
| 403 | The caller lacks the route's scope |
| 404 | No such document or revision, or the revision has no original |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
DELETE /documents/{documentId}
Delete a document, its revisions, passages and pending work
- Scope
- kg:write
Parameters| Name | In | Required | Type |
|---|
documentId | path | yes | string |
KG-Contract-Version | header | no | 1 | 2 | 3 |
KG-Confirmation | header | no | string |
Responses| Status | Meaning |
|---|
| 204 | Deleted |
| 401 | Missing or invalid credentials |
| 403 | The caller lacks the route's scope |
| 404 | No such document in this tenant |
| 422 | CONFIRMATION_INVALID: the token is unknown, expired, another principal's or tenant's, or for a different request; nothing changed. |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 428 | The operation needs confirmation; nothing changed. Resend the identical request with KG-Confirmation set to token before expiresAt. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
GET /document-jobs/{jobId}
A processing job's state and progress
- Scope
- kg:read
Parameters| Name | In | Required | Type |
|---|
jobId | path | yes | string |
Responses| Status | Meaning |
|---|
| 200 | The job |
| 401 | Missing or invalid credentials |
| 403 | The caller lacks the route's scope, or holds only kg:write and did not request this job |
| 404 | No such job in this tenant |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
GET /document-jobs/{jobId}/pages
A PDF job's pages: each one's state and failure reason (026)
- Scope
- kg:read
Parameters| Name | In | Required | Type |
|---|
jobId | path | yes | string |
state | query | no | string |
cursor | query | no | string |
Responses| Status | Meaning |
|---|
| 200 | At most 100 pages in page order |
| 400 | An unknown state or a cursor this API did not return |
| 401 | Missing or invalid credentials |
| 403 | The caller lacks the route's scope |
| 404 | No such job in this tenant |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
POST /document-jobs/{jobId}/cancel
Cancel a job before it commits
- Scope
- kg:write
Parameters| Name | In | Required | Type |
|---|
jobId | path | yes | string |
KG-Contract-Version | header | no | 1 | 2 | 3 |
Responses| Status | Meaning |
|---|
| 200 | The job, now cancelled |
| 401 | Missing or invalid credentials |
| 403 | The caller lacks the route's scope |
| 404 | No such job in this tenant |
| 409 | The job can no longer be cancelled |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
GET /schema
- Scope
- kg:read
Responses| Status | Meaning |
|---|
| 200 | OK |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
POST /entities/search
Ranked keyword, vector or hybrid search over the caller's entities
- Scope
- kg:read
- Request body
application/json: string
Responses| Status | Meaning |
|---|
| 200 | One page of ranked results |
| 400 | The body is not JSON or does not match SearchRequest's shape |
| 401 | Missing or invalid credentials |
| 403 | The caller lacks kg:read |
| 409 | Vector mode cannot run now; retry later or use keyword or hybrid mode |
| 413 | The serialized request exceeds 1 MiB |
| 422 | A request member breaks a rule; the body names it |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 429 | Rate limited or over quota, or the plan's monthly retrieval calls are spent (PLAN_LIMIT_REACHED, retryable at the next month) |
| 503 | Search capacity is in use (032 FR-007), or tenant storage cannot serve the search. A search refused by admission is answered at once, before any data connection is taken: the pre-admission ApiError with code SERVICE_BUSY, admitted false, retryAfterSeconds and the Retry-After header, the same for every tenant, and nothing was charged. Retrying before Retry-After is refused again. The other storage outcomes are StorageUnavailable's. |
| 504 | The search did not finish within 5 seconds; no partial page |
POST /entities/query
Query entities with structured criteria
- Scope
- kg:read
- Request body
application/json: object
Request fields| Field | Type | Required | Notes |
|---|
criteria | QueryExpression | no | |
cursor | string | no | |
pageSize | integer | no | |
sort | array of SortTerm | no | |
traversal | TraversalScope | no | |
types | array of string | no | |
Responses| Status | Meaning |
|---|
| 200 | Deterministic entity result page |
| 400 | Malformed JSON or expression shape |
| 401 | Missing or invalid API key |
| 404 | Missing traversal start entity |
| 413 | Query payload exceeds 1 MiB |
| 422 | Semantically invalid query or exhausted scope limit |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
| 504 | Five-second query deadline exceeded |
GET /entities/{entityId}
- Scope
- kg:read
Parameters| Name | In | Required | Type |
|---|
entityId | path | yes | string |
Responses| Status | Meaning |
|---|
| 200 | OK |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
GET /entities/{entityId}/relationships
- Scope
- kg:read
Parameters| Name | In | Required | Type |
|---|
entityId | path | yes | string |
direction | query | no | string |
Responses| Status | Meaning |
|---|
| 200 | OK |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
GET /entities/{entityId}/neighborhood
- Scope
- kg:read
Parameters| Name | In | Required | Type |
|---|
entityId | path | yes | string |
maxHops | query | no | integer |
direction | query | no | string |
relationshipTypes | query | no | array of string |
limit | query | no | integer |
Responses| Status | Meaning |
|---|
| 200 | OK |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
POST /context
Cited context for a question within a token budget
- Scope
- kg:read
- Request body
application/json: string
Parameters| Name | In | Required | Type |
|---|
KG-Contract-Version | header | no | 1 | 2 | 3 |
Responses| Status | Meaning |
|---|
| 200 | OK |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
POST /memory/entries
Record a claim attributed to the caller
- Scope
- kg:write
- Request body
application/json: string
Parameters| Name | In | Required | Type |
|---|
KG-Contract-Version | header | no | 1 | 2 | 3 |
Responses| Status | Meaning |
|---|
| 200 | OK |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
GET /memory/entries
Current entries, newest first, each with its attribution
- Scope
- kg:read
Parameters| Name | In | Required | Type |
|---|
pageSize | query | no | string |
cursor | query | no | string |
sourceChanged | query | no | string |
labels | query | no | array of string |
since | query | no | string |
author | query | no | string |
authorKind | query | no | string |
contains | query | no | string |
Responses| Status | Meaning |
|---|
| 200 | OK |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
GET /memory/authors
Who wrote the current entries, with how many each wrote
- Scope
- kg:read
Responses| Status | Meaning |
|---|
| 200 | OK |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
DELETE /memory/entries/{entryId}/reviews/mine
Withdraw the caller's own review of an entry
- Scope
- kg:write
Parameters| Name | In | Required | Type |
|---|
entryId | path | yes | string |
KG-Contract-Version | header | no | 1 | 2 | 3 |
Responses| Status | Meaning |
|---|
| 200 | OK |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
GET /memory/entries/{entryId}
One memory entry with its attribution and citations
- Scope
- kg:read
Parameters| Name | In | Required | Type |
|---|
entryId | path | yes | string |
Responses| Status | Meaning |
|---|
| 200 | OK |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
GET /memory/entries/{entryId}/history
The whole supersession chain, oldest first
- Scope
- kg:read
Parameters| Name | In | Required | Type |
|---|
entryId | path | yes | string |
Responses| Status | Meaning |
|---|
| 200 | OK |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
POST /memory/entries/{entryId}/supersessions
Store a corrected entry that supersedes this one
- Scope
- kg:write
- Request body
application/json: string
Parameters| Name | In | Required | Type |
|---|
entryId | path | yes | string |
KG-Contract-Version | header | no | 1 | 2 | 3 |
Responses| Status | Meaning |
|---|
| 200 | OK |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
DELETE /memory/entries/{entryId}
Delete a standalone entry and its links
- Scope
- kg:write
Parameters| Name | In | Required | Type |
|---|
entryId | path | yes | string |
KG-Contract-Version | header | no | 1 | 2 | 3 |
Responses| Status | Meaning |
|---|
| 200 | OK |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
POST /memory/recall
Entries ranked by relevance to a topic, optionally limited by subject
- Scope
- kg:read
- Request body
application/json: string
Parameters| Name | In | Required | Type |
|---|
KG-Contract-Version | header | no | 1 | 2 | 3 |
Responses| Status | Meaning |
|---|
| 200 | OK |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 503 | Tenant storage cannot serve the request. Before admission: the pre-admission ApiError, SERVICE_BUSY, nothing charged. After admission: AdmittedStorageError; with outcome unknown, a write may have committed and is never replayed. With the leadership lease on (040 T042), a pod that is not the leader during a release handover also answers a leader-only route this way, before admission, with retryAfterSeconds and Retry-After. |
GET /me/limits
The tenant's plan limits and usage
- Scope
- None: any enabled identity of the tenant
Responses| Status | Meaning |
|---|
| 200 | The plan and its limits |
| 400 | A query parameter was given |
| 401 | Missing, invalid or untrusted access token |
| 403 | Disabled or unregistered identity |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
GET /me/context-usage
What the tenant's agents were given, beside what is stored
- Scope
- kg:read
Responses| Status | Meaning |
|---|
| 200 | The tenant's context usage and stored size |
| 400 | A query parameter was given |
| 401 | Missing, invalid or untrusted access token |
| 403 | Disabled or unregistered identity, or no read scope |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
GET /me/usage
Inspect the current caller's applicable usage and limits
- Scope
- None: any enabled identity of the tenant
Responses| Status | Meaning |
|---|
| 200 | Coherent tenant aggregate and optional own-agent snapshot |
| 400 | Ambiguous credentials or malformed request; not admitted |
| 401 | Missing, invalid or untrusted access token |
| 403 | Disabled or unregistered identity |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 429 | Polling allowance exhausted; separate from the API allowances |
| 503 | Required registry dependency or instance capacity unavailable |
GET /model-usage
Read your tenant's model usage and embedding allowance
- Scope
- kg:read
Parameters| Name | In | Required | Type |
|---|
periods | query | no | integer |
Responses| Status | Meaning |
|---|
| 200 | Usage for the caller's tenant |
| 401 | Missing, invalid or untrusted access token |
| 403 | The credential lacks kg:read |
| 422 | `periods` out of range, or a parameter the route does not accept (self-correctable: `parameter`, `rule`, `allowed`) |
| 423 | TENANT_SUSPENDED (013): the caller's tenant is suspended for its deletion; only reading or cancelling the deletion and reading an existing export are available. |
| 429 | 006's per-identity limit; Retry-After is set |