API reference
Generated from docs/api/openapi.json, which is itself generated from
the Zod schemas that validate requests. It cannot drift from the running API.
Every request is authenticated. Send a tenant credential as
Authorization: Bearer tth_dev_…. Tenant, app and environment come from the key and
cannot be set by a request.
GET /v1/whoami
Returns the tenant, application and environment the presented key acts for. All three are derived from the credential and cannot be set by a request, so this is how an integrator confirms which scope a key reaches before writing anything with it, and the first call to make when a write returns not_found for a space that looks correct.
Responses
| Code | |
|---|
200 | The credential behind this request. |
401 | Missing, malformed, unknown, or revoked credential. |
429 | Rate limited. Retry after a short delay. |
POST /v1/anchors
Stores a new anchor as the root of its own version chain. Correct it later with PATCH rather than storing a second anchor.
Parameters
| Name | In | | |
|---|
Idempotency-Key | header | required | A caller-chosen key that makes this write safe to retry. Replaying the same key with the same body returns the original result; reusing it with a different body returns 409. |
Responses
| Code | |
|---|
201 | Stored. Not yet searchable. |
400 | Invalid request, missing Idempotency-Key, or content carrying a secret. |
403 | The grant does not permit writes. |
404 | Unknown space, subject, or refines target. |
409 | Idempotency key reused with a different payload. |
429 | Rate limited. Retry after a short delay. |
GET /v1/anchors/{id}
Returns a single anchor by id. Superseded versions remain readable as history; forgotten and deleted anchors return not_found.
Parameters
| Name | In | | |
|---|
id | path | required | |
space | query | required | |
Responses
| Code | |
|---|
200 | The anchor. |
403 | The grant does not permit reads. |
404 | No such anchor in this scope, or it has been forgotten or deleted. |
429 | Rate limited. Retry after a short delay. |
PATCH /v1/anchors/{id}
Supersedes the current version of a chain with a new one. Pass the version you believe is current as expectedVersion; a stale value returns 409 rather than forking the chain. History is preserved and remains readable.
Parameters
| Name | In | | |
|---|
id | path | required | |
Idempotency-Key | header | required | A caller-chosen key that makes this write safe to retry. Replaying the same key with the same body returns the original result; reusing it with a different body returns 409. |
Responses
| Code | |
|---|
200 | Corrected. The new version is current. |
400 | Invalid request, missing Idempotency-Key, or content carrying a secret. |
403 | The grant does not permit writes. |
404 | No such chain in this scope, or it has been deleted. |
409 | expectedVersion is stale, or the key was reused with a different payload. |
429 | Rate limited. Retry after a short delay. |
DELETE /v1/anchors/{id}
Requests physical removal of an anchor and every other version of its chain. Returns 202 with a deletion id: rows and markers are written synchronously, vectors are purged asynchronously. Poll GET /v1/deletions/{id}. A marker persists so a delayed job or a replay cannot recreate the data.
Parameters
| Name | In | | |
|---|
id | path | required | |
Idempotency-Key | header | required | A caller-chosen key that makes this write safe to retry. Replaying the same key with the same body returns the original result; reusing it with a different body returns 409. |
Responses
| Code | |
|---|
202 | Accepted. Cleanup is in progress. |
400 | Invalid request or missing Idempotency-Key. |
403 | The grant does not permit deletes. |
404 | No such anchor in this scope. |
429 | Rate limited. Retry after a short delay. |
POST /v1/anchors/{id}/forget
Excludes an anchor from recall while preserving its row. Requires the delete operation: hiding a fact is destructive from a reader's point of view, and a credential trusted to add facts is not automatically trusted to make them disappear. Use DELETE to request physical removal.
Parameters
| Name | In | | |
|---|
id | path | required | |
Idempotency-Key | header | required | A caller-chosen key that makes this write safe to retry. Replaying the same key with the same body returns the original result; reusing it with a different body returns 409. |
Responses
| Code | |
|---|
204 | Forgotten. No longer returned by reads or recall. |
400 | Invalid request or missing Idempotency-Key. |
403 | The grant does not permit deletes. |
404 | No such anchor in this scope. |
429 | Rate limited. Retry after a short delay. |
GET /v1/deletions/{id}
Reports which stages of a deletion have completed. Backup expiry is reported separately and is not part of this response.
Parameters
| Name | In | | |
|---|
id | path | required | |
space | query | required | |
Responses
| Code | |
|---|
200 | Deletion progress. |
403 | The grant does not permit deletes. |
404 | No such deletion in this scope. |
429 | Rate limited. Retry after a short delay. |
POST /v1/search
Ranked semantic search over the current anchors in one space. Superseded, forgotten and deleted anchors are never returned, and an anchor written moments ago may be missing until it is indexed -- check `degraded`. Use /v1/context instead when you want a budgeted answer to assemble into a prompt.
Responses
| Code | |
|---|
200 | Ranked matches. |
400 | Invalid request. |
403 | The grant does not permit reads. |
404 | Unknown space. |
429 | Rate limited. |
503 | Embeddings, the index or the database are unreachable. Nothing was returned on a guess. |
POST /v1/context
Returns the anchors worth putting in a prompt for this query, expanded one hop across `refines` edges and trimmed to `maxTokens`. Every neighbour is authorized exactly as a direct match is, so an edge never widens what you can see. `tokenCount` is measured by the estimator named in `tokenizer`, not by your model's tokenizer. `graphRevision` changes whenever anything in the space is written, corrected, forgotten or deleted. `degraded` is true when writes are still being indexed -- the results are valid, just possibly incomplete.
Responses
| Code | |
|---|
200 | Context within the requested budget. |
400 | Invalid request. |
403 | The grant does not permit reads. |
404 | Unknown space. |
429 | Rate limited. |
503 | Embeddings, the index or the database are unreachable. Nothing was returned on a guess. |