{ "openapi": "3.1.0", "info": { "title": "Korely API", "version": "1.0.9", "description": "The Korely memory API. Typed bi-temporal facts, an entity graph, and hybrid retrieval, in a managed EU cloud. Authenticate every request with a `kor_live_` key in the `Authorization: Bearer` header." }, "servers": [ { "url": "https://api.korely.ai", "description": "EU (Helsinki)" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/memories": { "post": { "tags": [ "v1" ], "summary": "Add Memory", "description": "Store a memory for an end user (`user_id`), an agent (`agent_id`) or a\nrun (`run_id`).\n\nThe call returns once the memory is stored. Its typed facts are extracted\nby a model after that, so the reply says `status: processing` with\n`facts: []`; a server run with `WRITE_ASYNC=false` extracts before\nanswering and returns the facts inline. Poll `GET /v1/events` or read the\nmemory again to see them.\n\n`timestamp` is when the events happened, not when you send them: the\nfacts take it as `valid_from`, so reads with `as_of` answer about the\nright date. An unreadable one is a 422, never a silent \"now\".", "operationId": "add_memory_v1_memories_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "X-Korely-Client", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The tool writing, e.g. claude-code: kept on the memory as `client`. Not a namespace and not counted in the agent cap.", "title": "X-Korely-Client" }, "description": "The tool writing, e.g. claude-code: kept on the memory as `client`. Not a namespace and not counted in the agent cap." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddBody" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryWithFacts" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's writes of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at`, a top-up or a bigger plan). And `agent_cap_exceeded`: a new `agent_id` past the plan's named agents (`limit`, `used`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`. Or `unavailable`: the server holds as many request bodies as it reads at once; retry after `Retry-After` (5 s). Nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "`payload_too_large`: the body is larger than 2,097,152 bytes, the most this route takes. Refused before it is read; nothing was done. Also a body that holds more JSON strings (36,930), values (72,433) or characters (342,092) than lawful items of its size can, whose text decodes to more than it weighs and more than 4,077,000 bytes, or that would take more than 8,388,608 bytes once decoded: refused before it is decoded; nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "408": { "description": "`request_timeout`: the body did not arrive whole within 30 s. Nothing was done; send it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "400": { "description": "`bad_request`: the body is not well formed. A JSON body not in UTF-8 (RFC 8259) is refused before it is decoded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "get": { "tags": [ "v1" ], "summary": "List Memories", "description": "The memories of this key's project, newest first, a page at a time\n(`limit`, `offset`); `total` counts them all. Narrow it with `user_id`,\n`agent_id` and `run_id`. Forgotten memories are not listed.\n\nEach memory's `status` says whether its facts are ready; the facts are on\n`GET /v1/memories/{memory_id}` and `GET /v1/facts`.", "operationId": "list_memories_v1_memories_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Filter to one end user.", "title": "User Id" }, "description": "Filter to one end user." }, { "name": "agent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to one agent namespace.", "title": "Agent Id" }, "description": "Filter to one agent namespace." }, { "name": "run_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Filter to one run/session.", "title": "Run Id" }, "description": "Filter to one run/session." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 9223372036854775807, "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "exclude_sessions", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Leave out the work sessions (memories written with `kind: session`, what a coding assistant's hooks save), for a read that wants what was said and decided. Default false: everything.", "default": false, "title": "Exclude Sessions" }, "description": "Leave out the work sessions (memories written with `kind: session`, what a coding assistant's hooks save), for a read that wants what was said and decided. Default false: everything." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryList" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/memories/{memory_id}": { "patch": { "tags": [ "v1" ], "summary": "Update Memory", "description": "Replace a memory's text.\n\nIts facts are extracted again from the new text and go through the same\ncontradiction check as a new write: a value that changed supersedes the\nfact the old text stated, which stays in history (`as_of` before the edit\nstill returns it). Like a new write, the reply says `processing` with\n`facts: []` until the extraction has run. The text the memory already\nhas, once extracted, is not an edit: nothing is written, extracted or\nclosed, and the reply is the memory as it is.\n\n`expected_updated_at` makes the edit conditional on the version you read:\n409 `stale_write`, and nothing changes, when the memory moved since; 422\nwhen it is not an instant (an empty string included).", "operationId": "update_memory_v1_memories__memory_id__patch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "memory_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Memory Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBody" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryWithFacts" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's writes of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at`, a top-up or a bigger plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`. Or `unavailable`: the server holds as many request bodies as it reads at once; retry after `Retry-After` (5 s). Nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`not_found`: nothing with that id is reachable with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "`stale_write`: `expected_updated_at` does not match the current record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "`payload_too_large`: the body is larger than 2,097,152 bytes, the most this route takes. Refused before it is read; nothing was done. Also a body that holds more JSON strings (36,930), values (72,433) or characters (342,092) than lawful items of its size can, whose text decodes to more than it weighs and more than 4,077,000 bytes, or that would take more than 8,388,608 bytes once decoded: refused before it is decoded; nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "408": { "description": "`request_timeout`: the body did not arrive whole within 30 s. Nothing was done; send it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "400": { "description": "`bad_request`: the body is not well formed. A JSON body not in UTF-8 (RFC 8259) is refused before it is decoded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "v1" ], "summary": "Delete Memory", "description": "Forget one memory, or erase it with `erase=true`.\n\nForgetting drops the memory out of every read and ends the facts it\nstated, which stay in history, closed. The row, with its text and vector,\nstays in the database, and no call brings the memory back.\n\n`erase=true` deletes it for good: the row, its text and vector, the\nfacts only it stated, its item in a `/v1/batch` payload, and the aliases\nand vocabulary examples its facts alone taught. A memory forgotten\nearlier is erased the same way (a forget answers 404 for it). Either way\nan audit row keeps the counts, never the content. On a Self-hosted\ninstall, `restore.sh` makes the erasure again after a restore of a backup\ntaken before it (`manage erasures-export` before and `erasures-replay`\nafter); a restore done another way does not. To erase everything of one\nend user, use `DELETE /v1/users/{end_user}/memories`.", "operationId": "delete_memory_v1_memories__memory_id__delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "memory_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Memory Id" } }, { "name": "erase", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Erase it for good: the row, its text, observation and vector, and the facts it alone stated go from the database, with its item in a /v1/batch payload and what its facts taught the project's vocabulary and aliases. A memory forgotten earlier can be erased too. Without it the memory is forgotten: it drops out of every read, its facts stop being true, and the row stays.", "default": false, "title": "Erase" }, "description": "Erase it for good: the row, its text, observation and vector, and the facts it alone stated go from the database, with its item in a /v1/batch payload and what its facts taught the project's vocabulary and aliases. A memory forgotten earlier can be erased too. Without it the memory is forgotten: it drops out of every read, its facts stop being true, and the row stays." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Delete Memory V1 Memories Memory Id Delete" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`not_found`: nothing with that id is reachable with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "get": { "tags": [ "v1" ], "summary": "Get Memory", "description": "One memory, with the facts it asserts that are true now. The ones a\nlater fact superseded are its history: GET /v1/memories/{id}/history.", "operationId": "get_memory_v1_memories__memory_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "memory_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Memory Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryWithFacts" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`not_found`: nothing with that id is reachable with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/users/{end_user}/memories": { "delete": { "tags": [ "v1" ], "summary": "Delete User Memories", "description": "ERASE everything about one end user in one call: every memory and fact.\n\nPhysical deletion, not a flag: after this call the content is gone from the\ndatabase and cannot be read back by any parameter, `include_invalidated`\nincluded. Unrecoverable by design, because that is what erasure means.\n\n`end_user` is the `user_id` exactly as written, percent-encoded as one path\nsegment (`acme/42` is `acme%2F42`). Any stored id is accepted here,\nincluding one written before new ids were required to be a single segment.\n\nThe response counts rows physically deleted: `memories_deleted` and\n`facts_deleted` (until 0.1.42 also under their first names,\n`memories_forgotten` and `facts_invalidated`, removed in 0.2.0).\n\nThe audit row survives, carrying counts and a keyed pseudonym of your\n`end_user_id`, none of the erased content, so you can evidence the erasure\nto your own regulator: `GET /v1/audit?user_id=` finds it. The\nrest of the access trail takes the pseudonym too, a webhook already\ndelivered takes the pseudonym, and the cost rows of the model calls never\nname an end user.\n\nWithin the key's project: the same id in another project of the account\nstays there (it may be another customer's person). To erase it in every\nproject at once, the account's administrator calls\n`DELETE /admin/users/{end_user}/memories`.\n\nFor a single memory, `DELETE /v1/memories/{memory_id}` forgets it (out of\nevery read, the row kept, and no call brings it back) or, with\n`erase=true`, erases it.", "operationId": "delete_user_memories_v1_users__end_user__memories_delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "end_user", "in": "path", "required": true, "schema": { "type": "string", "title": "End User" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserErasureResponse" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/memories/search": { "post": { "tags": [ "v1" ], "summary": "Search Memories", "description": "The memories closest in meaning to `query`, best first.\n\n`score` is the cosine similarity of the vectors and `snippet` the first\n280 characters of the memory. Narrow it with `user_id`, `agent_id`,\n`run_id` and the `metadata` stored at write time; `min_score` leaves out\nthe weak matches. A forgotten memory is never returned.\n\n503 `search_unavailable` when the query could not be embedded (see the\n503 below): that is not an empty result, retry. A search that could not\nrun takes no query of the month.", "operationId": "search_memories_v1_memories_search_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchBody" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "`search_unavailable`: the query could not be embedded, so semantic search could not run. Either the embedding provider did not answer, or, with the local embedder, the search waited 20 s for one of its account's 4 places there, per process (its searches, its contexts and the vectors of its writes share them, over REST and MCP; a search past them waits its turn), or 20 s more for its turn there. Not an empty result; retry after `Retry-After`. It takes no query of the month. `service_paused`: the service itself does not call the models now (a spending stop or a provider brake), which a retry within the hour cannot change; `Retry-After` says how long to wait. Nothing was written. Not `model_unavailable`, which is a model that did not answer this request. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`. Or `unavailable`: the server holds as many request bodies as it reads at once; retry after `Retry-After` (5 s). Nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "`payload_too_large`: the body is larger than 2,097,152 bytes, the most this route takes. Refused before it is read; nothing was done. Also a body that holds more JSON strings (36,930), values (72,433) or characters (342,092) than lawful items of its size can, whose text decodes to more than it weighs and more than 4,077,000 bytes, or that would take more than 8,388,608 bytes once decoded: refused before it is decoded; nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "408": { "description": "`request_timeout`: the body did not arrive whole within 30 s. Nothing was done; send it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "400": { "description": "`bad_request`: the body is not well formed. A JSON body not in UTF-8 (RFC 8259) is refused before it is decoded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/events": { "get": { "tags": [ "v1" ], "summary": "List Events", "description": "Which writes have finished being processed.\n\nA write returns as soon as the memory is stored, then fact extraction runs\nbehind it. Without this endpoint a developer polls blind: they cannot tell\n\"extraction has not finished\" from \"there was nothing to extract\", which is\nthe first confusing thing anyone hits when building on us.\n\n`events` are the newest writes, newest first; `status` filters them before\n`limit` is applied, so `?status=error` returns the most recent errors\nhowever many ready writes came after them.\n\n`processing` in the response is how many writes of this key's project (of\n`user_id`, when given) are still in flight, counted over all of them, so a\nbatch import can wait on one number instead of walking every id. It ignores\n`status` and `limit`.\n\nNo webhook announces that a write's extraction finished: `memory.created`\nis sent when the memory is stored, before its facts, and\n`GET /admin/webhooks/events` lists the events there are. Waiting for the\nfacts is polling this, or reading the memory again.", "operationId": "list_events_v1_events_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Filter to one end user.", "title": "User Id" }, "description": "Filter to one end user." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(processing|ready|error)$" }, { "type": "null" } ], "description": "Filter to one processing state.", "title": "Status" }, "description": "Filter to one processing state." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsResponse" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/memories/{memory_id}/history": { "get": { "tags": [ "v1" ], "summary": "Memory History", "description": "The lifecycle timeline of one memory: created / updated / deleted, plus\nevery typed fact extracted from it (with the moment it was learned and, if\nsuperseded, invalidated). Richer than a plain add/update/delete log: it\nshows what the memory *taught* the store over time.", "operationId": "memory_history_v1_memories__memory_id__history_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "memory_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Memory Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryHistory" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`not_found`: nothing with that id is reachable with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/users": { "get": { "tags": [ "v1" ], "summary": "List Users", "description": "List the developer's end users (the distinct ``user_id`` namespaces that\nhold memories or facts), with per-user memory + fact counts and last-active\ntime. Both stores are read (memories AND direct fact writes), so a\nfact-only end user is still visible. The default (null) namespace is omitted.", "operationId": "list_users_v1_users_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to one agent namespace.", "title": "Agent Id" }, "description": "Filter to one agent namespace." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 9223372036854775807, "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersResponse" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/agents/{agent_id}": { "delete": { "tags": [ "v1" ], "summary": "Delete Agent Namespace", "description": "Hard-delete an agent namespace: purge every memory + fact written under this\n``agent_id``, so a typo or throwaway ``agent_id`` stops appearing in\n``GET /v1/agents``. Soft-forgetting its data is not enough for that: the\nlisting counts any row carrying the namespace, forgotten ones included.\nReturns the purge counts + an audit id. 404 if the namespace was never used\nin this project.\n\n``agent_id`` is percent-encoded as one path segment (``a/b`` is ``a%2Fb``);\nany stored id is accepted, including one written before new ids were\nrequired to be a single segment.", "operationId": "delete_agent_namespace_v1_agents__agent_id__delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Delete Agent Namespace V1 Agents Agent Id Delete" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`not_found`: nothing with that id is reachable with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/agents": { "get": { "tags": [ "v1" ], "summary": "List Agents", "description": "List the agent namespaces this developer has written under (the distinct\nnon-null ``agent_id`` values), each with its active memory + fact counts and\nlast-active time, plus ``cap``, the most agent names a write may bring in\n(0 when nothing caps them, as on an install of one's own), and ``used``,\nhow many of them the cap counts.\n\nThe namespace set counts memories AND direct fact writes, including\nsoft-deleted / invalidated rows; the per-agent ``memories``/``facts`` counts\nreflect only active items, so an agent whose data was all forgotten still\nappears, with zero counts, until ``DELETE /v1/agents/{agent_id}`` purges it.\nThe default (null) namespace is never counted, and omitted.", "operationId": "list_agents_v1_agents_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 9223372036854775807, "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentsResponse" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/facts": { "get": { "tags": [ "v1" ], "summary": "List Facts", "description": "The typed facts, a page at a time, filtered by end user, agent,\nsubject (`subject`), either side (`entity`) and relation (`predicate`,\n`predicate_family`). A database read: no model is asked.\n\nBy default the facts true now. `as_of` gives the facts true at a date,\n`known_as_of` the facts as the store knew them at a moment, and\n`include_invalidated=true` adds the facts that ended, each with its\n`invalid_at` and the `invalidated_by` that closed it.", "operationId": "list_facts_v1_facts_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Filter to one end user.", "title": "User Id" }, "description": "Filter to one end user." }, { "name": "agent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" } }, { "name": "subject", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Match the subject side.", "title": "Subject" }, "description": "Match the subject side." }, { "name": "entity", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Match subject OR object side.", "title": "Entity" }, "description": "Match subject OR object side." }, { "name": "predicate", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Predicate" } }, { "name": "predicate_family", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to one family: one of `preferences`, `people`, `places`, `work`, `ownership`, `health`, `financial`, `events`, `identity`, `other` (case and surrounding spaces ignored). A name that is not a family matches no fact: an empty result, not an error. An empty value is no filter; one made only of spaces is no family, and matches no fact. A name longer than 200 characters, or with a NUL byte, is refused as an invalid request (a 422 on REST), as every name a read of the facts narrows on.", "title": "Predicate Family" }, "description": "Filter to one family: one of `preferences`, `people`, `places`, `work`, `ownership`, `health`, `financial`, `events`, `identity`, `other` (case and surrounding spaces ignored). A name that is not a family matches no fact: an empty result, not an error. An empty value is no filter; one made only of spaces is no family, and matches no fact. A name longer than 200 characters, or with a NUL byte, is refused as an invalid request (a 422 on REST), as every name a read of the facts narrows on." }, { "name": "include_invalidated", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Invalidated" } }, { "name": "as_of", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO date/datetime: point-in-time validity, from 0001-01-02 to 9999-12-30, in UTC; outside it, or unreadable, a 422.", "title": "As Of" }, "description": "ISO date/datetime: point-in-time validity, from 0001-01-02 to 9999-12-30, in UTC; outside it, or unreadable, a 422." }, { "name": "known_as_of", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO date/datetime: the facts as the store knew them then: learned by then, with the ends learned by then, true at `as_of` (default: that same moment). A move made in September and told in October: `as_of` September returns the new address, `known_as_of` September the old one. A moment from 0001-01-02 to 9999-12-30, in UTC; outside it, or unreadable, a 422.", "title": "Known As Of" }, "description": "ISO date/datetime: the facts as the store knew them then: learned by then, with the ends learned by then, true at `as_of` (default: that same moment). A move made in September and told in October: `as_of` September returns the new address, `known_as_of` September the old one. A moment from 0001-01-02 to 9999-12-30, in UTC; outside it, or unreadable, a 422." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 9223372036854775807, "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "exclude_sessions", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Leave out the facts only work sessions state (memories written with `kind: session`, what a coding assistant's hooks save). Default false.", "default": false, "title": "Exclude Sessions" }, "description": "Leave out the facts only work sessions state (memories written with `kind: session`, what a coding assistant's hooks save). Default false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactsResponse" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "tags": [ "v1" ], "summary": "Create Fact", "description": "Write a fact directly: a subject, a relation and an object, with no\nmemory behind it and no extraction.\n\nIt is not a write without a model. With a model key configured, the\nrelation goes through the store's vocabulary (a model may be asked whether\na new relation is one already known, and whether it holds one value at a\ntime), and a `current` fact goes through the contradiction check: when\nopen facts of the same subject could conflict with it, a model judges\nthem and may close one, named in `invalidated`. The fact's words reach\nthat model's provider and the calls are billed as any other. When one of\nthose models gives no usable answer nothing is written: 503\n`model_unavailable`, retry.\n\nWith no model key, no model is asked and no judge closes anything. A\n`past` fact closes the open fact it restates either way.\n\nTo end a fact yourself, with the date it stopped being true, use\n`POST /v1/facts/{fact_id}/forget`, which asks no model.", "operationId": "create_fact_v1_facts_post", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactBody" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactWriteResponse" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's writes of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at`, a top-up or a bigger plan). And `agent_cap_exceeded`: a new `agent_id` past the plan's named agents (`limit`, `used`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "`model_unavailable`: a model the write needs (the one that resolves relations, or the contradiction check) gave no usable answer. Nothing was written; retry. A new fact whose own embedding fails is written anyway, and its vector is computed later by the worker. `service_paused`: the service itself does not call the models now (a spending stop or a provider brake), which a retry within the hour cannot change; `Retry-After` says how long to wait. Nothing was written. Not `model_unavailable`, which is a model that did not answer this request. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`. Or `unavailable`: the server holds as many request bodies as it reads at once; retry after `Retry-After` (5 s). Nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "`payload_too_large`: the body is larger than 2,097,152 bytes, the most this route takes. Refused before it is read; nothing was done. Also a body that holds more JSON strings (36,930), values (72,433) or characters (342,092) than lawful items of its size can, whose text decodes to more than it weighs and more than 4,077,000 bytes, or that would take more than 8,388,608 bytes once decoded: refused before it is decoded; nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "408": { "description": "`request_timeout`: the body did not arrive whole within 30 s. Nothing was done; send it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "400": { "description": "`bad_request`: the body is not well formed. A JSON body not in UTF-8 (RFC 8259) is refused before it is decoded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/facts/{fact_id}/forget": { "post": { "tags": [ "v1" ], "summary": "Forget Fact", "description": "Close a fact: it stops being current, and stays in history.\n\nThe half of the contract that was missing. Facts could be read and written\nover `/v1` and only closed from the dashboard, so an agent could assert\nwhat it had learned and never retract it. Everything it got wrong stayed\ntrue forever unless a model happened to notice the contradiction.\n\nWith this, an agent that knows a fact is finished says so, and nothing has\nto infer it. This call asks no model. Writing a fact is another matter:\n`POST /v1/facts` asks the model for the vocabulary and the contradiction\ncheck whenever a model key is configured, and that judge may close an\nearlier fact on its own. Only an install with no model key writes facts\nwith no model.\n\n`at` is the date it stopped being true, not the date you noticed. Reading\n`as_of` a date before it still returns the fact, which is the whole point of\nkeeping history instead of deleting rows.\n\nIdempotent: forgetting a fact that is already closed changes nothing and\nsays so.", "operationId": "forget_fact_v1_facts__fact_id__forget_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "fact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Fact Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ForgetBody" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgetResponse" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`. Or `unavailable`: the server holds as many request bodies as it reads at once; retry after `Retry-After` (5 s). Nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`not_found`: nothing with that id is reachable with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "`payload_too_large`: the body is larger than 2,097,152 bytes, the most this route takes. Refused before it is read; nothing was done. Also a body that holds more JSON strings (36,930), values (72,433) or characters (342,092) than lawful items of its size can, whose text decodes to more than it weighs and more than 4,077,000 bytes, or that would take more than 8,388,608 bytes once decoded: refused before it is decoded; nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "408": { "description": "`request_timeout`: the body did not arrive whole within 30 s. Nothing was done; send it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "400": { "description": "`bad_request`: the body is not well formed. A JSON body not in UTF-8 (RFC 8259) is refused before it is decoded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/facts/{fact_id}": { "patch": { "tags": [ "v1" ], "summary": "Correct Fact", "description": "Supersede a fact with a corrected one. Both stay readable.\n\nNot a mutation: the old row keeps its dates and gains an `invalidated_by`\npointing at the new one, so `as_of` before the correction still returns what\nyou believed then. A store that edits a row in place cannot answer \"what did\nwe think in June\", and answering that is the product.", "operationId": "correct_fact_v1_facts__fact_id__patch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "fact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Fact Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorrectBody" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactWriteResponse" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's writes of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at`, a top-up or a bigger plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "`model_unavailable`: a model the write needs (the one that resolves relations, or the contradiction check) gave no usable answer. Nothing was written; retry. A new fact whose own embedding fails is written anyway, and its vector is computed later by the worker. `service_paused`: the service itself does not call the models now (a spending stop or a provider brake), which a retry within the hour cannot change; `Retry-After` says how long to wait. Nothing was written. Not `model_unavailable`, which is a model that did not answer this request. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`. Or `unavailable`: the server holds as many request bodies as it reads at once; retry after `Retry-After` (5 s). Nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`not_found`: nothing with that id is reachable with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "`fact_not_current`: the fact is history (superseded, forgotten or ended); `current_fact_id` is the fact in force to correct instead, null when nothing took the fact's place, and the message says the same in words.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "`payload_too_large`: the body is larger than 2,097,152 bytes, the most this route takes. Refused before it is read; nothing was done. Also a body that holds more JSON strings (36,930), values (72,433) or characters (342,092) than lawful items of its size can, whose text decodes to more than it weighs and more than 4,077,000 bytes, or that would take more than 8,388,608 bytes once decoded: refused before it is decoded; nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "408": { "description": "`request_timeout`: the body did not arrive whole within 30 s. Nothing was done; send it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "400": { "description": "`bad_request`: the body is not well formed. A JSON body not in UTF-8 (RFC 8259) is refused before it is decoded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/users/{end_user}/names": { "post": { "tags": [ "v1" ], "summary": "Declare Name", "description": "Declare that this end user is also called `name`.\n\nThe store never merges two names of a person by itself: two people can\nshare a name, and a merge it guessed wrong would close one person's facts\nwith another's. This is the declaration that does it. From now on a fact\nwritten about `name` in this end user's memory is a fact about the end\nuser, and the facts already written about `name` are read so at once\n(their written words stay as they were). It is the alias the dashboard\nmakes (`POST /admin/aliases`), for the key's project and this end user.\n\n`end_user` is the `user_id` exactly as written, percent-encoded as one\npath segment. Declaring the same name again answers the same. 409 when\n`name` is already declared for somebody else in this memory, 422 when it\nis not a name.\n\nThere is no undo here: `DELETE /admin/aliases/{id}` removes the alias,\nand the facts take back the names their words give; two open facts it\nmerged stay one, and a plan it closed stays closed.", "operationId": "declare_name_v1_users__end_user__names_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "end_user", "in": "path", "required": true, "schema": { "type": "string", "title": "End User" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NameBody" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NameResponse" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's writes of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at`, a top-up or a bigger plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`. Or `unavailable`: the server holds as many request bodies as it reads at once; retry after `Retry-After` (5 s). Nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "`conflict`: the name is already declared for somebody else in this end user's memory (the same name declared again for the same end user answers 201, as the first time); `too_many_names`: the account has declared the most names it may have.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "`payload_too_large`: the body is larger than 2,097,152 bytes, the most this route takes. Refused before it is read; nothing was done. Also a body that holds more JSON strings (36,930), values (72,433) or characters (342,092) than lawful items of its size can, whose text decodes to more than it weighs and more than 4,077,000 bytes, or that would take more than 8,388,608 bytes once decoded: refused before it is decoded; nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "408": { "description": "`request_timeout`: the body did not arrive whole within 30 s. Nothing was done; send it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "400": { "description": "`bad_request`: the body is not well formed. A JSON body not in UTF-8 (RFC 8259) is refused before it is decoded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/profile": { "get": { "tags": [ "v1" ], "summary": "Get Profile", "description": "The assembled profile of one end user: the active typed facts known about\nthem, ``self``-facts first, grouped by predicate family. Deterministic (no\nmodel call). ``user_id`` is required: a profile is per-end-user (this is\nwhat distinguishes it from the flat ``GET /v1/facts`` list). ``as_of`` gives\nthe point-in-time profile (\"what was true on 2026-03-01\"), ``known_as_of``\nthe profile as the store knew it then (\"what we knew on 2026-03-01\").", "operationId": "get_profile_v1_profile_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "End user to build the profile for.", "title": "User Id" }, "description": "End user to build the profile for." }, { "name": "agent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to one agent namespace.", "title": "Agent Id" }, "description": "Filter to one agent namespace." }, { "name": "as_of", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO date/datetime: the profile as it was on that date, from 0001-01-02 to 9999-12-30, in UTC; outside it, or unreadable, a 422.", "title": "As Of" }, "description": "ISO date/datetime: the profile as it was on that date, from 0001-01-02 to 9999-12-30, in UTC; outside it, or unreadable, a 422." }, { "name": "known_as_of", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO date/datetime: the facts as the store knew them then: learned by then, with the ends learned by then, true at `as_of` (default: that same moment). A move made in September and told in October: `as_of` September returns the new address, `known_as_of` September the old one. A moment from 0001-01-02 to 9999-12-30, in UTC; outside it, or unreadable, a 422.", "title": "Known As Of" }, "description": "ISO date/datetime: the facts as the store knew them then: learned by then, with the ends learned by then, true at `as_of` (default: that same moment). A move made in September and told in October: `as_of` September returns the new address, `known_as_of` September the old one. A moment from 0001-01-02 to 9999-12-30, in UTC; outside it, or unreadable, a 422." }, { "name": "exclude_sessions", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Leave out the facts only work sessions state (memories written with `kind: session`, what a coding assistant's hooks save). Default false.", "default": false, "title": "Exclude Sessions" }, "description": "Leave out the facts only work sessions state (memories written with `kind: session`, what a coding assistant's hooks save). Default false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/context": { "get": { "tags": [ "v1" ], "summary": "Get Context", "description": "A block for the prompt: what the store knows about the end user, and\nthe facts and memories most relevant to `query`, as Markdown within\n`token_budget` tokens.\n\nNo text is generated: retrieval and layout, the question only embedded to\nrank. `context` is\nthe whole block; `stable` (the same from one call to the next) and\n`volatile` (this question's part) are its two halves, for a model\nprovider's prompt cache. `degraded` is true when part of it could not be\nretrieved, `degraded_parts` says which, and the block then ends with a\nnote saying so to the model.", "operationId": "get_context_v1_context_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 2000, "title": "Query" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "End user to build context for.", "title": "User Id" }, "description": "End user to build context for." }, { "name": "agent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "One agent's namespace: its facts and its memories only, as every other read with an agent_id.", "title": "Agent Id" }, "description": "One agent's namespace: its facts and its memories only, as every other read with an agent_id." }, { "name": "token_budget", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 8000, "minimum": 50, "description": "Tokens the block may take, 50 to 8000. Default 800; we recommend 4000 for an agent that answers questions about the past. A larger budget lets more facts and memories into the block (above 2000 tokens, more memories, ordered so that near duplicates do not crowd it), and is a larger prompt: keep it low where latency matters, as in a voice agent.", "default": 800, "title": "Token Budget" }, "description": "Tokens the block may take, 50 to 8000. Default 800; we recommend 4000 for an agent that answers questions about the past. A larger budget lets more facts and memories into the block (above 2000 tokens, more memories, ordered so that near duplicates do not crowd it), and is a larger prompt: keep it low where latency matters, as in a voice agent." }, { "name": "known_as_of", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO date/datetime: the block as the store could have built it then: the facts it had learned by then, true then as it knew them, and the memories it had received by then. Rebuilt with today's ranking; a memory edited since shows today's text, one deleted since stays out.", "title": "Known As Of" }, "description": "ISO date/datetime: the block as the store could have built it then: the facts it had learned by then, true then as it knew them, and the memories it had received by then. Rebuilt with today's ranking; a memory edited since shows today's text, one deleted since stays out." }, { "name": "exclude_sessions", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Leave out the work sessions (memories written with `kind: session`, what a coding assistant's hooks save) and the facts only they state, for a block about what was said and decided. Default false: everything.", "default": false, "title": "Exclude Sessions" }, "description": "Leave out the work sessions (memories written with `kind: session`, what a coding assistant's hooks save) and the facts only they state, for a block about what was said and decided. Default false: everything." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextResponse" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/batch": { "post": { "tags": [ "v1" ], "summary": "Create Batch", "description": "Import up to 500 memories in one call.\n\nEvery row is checked as a single write is (its content, metadata,\n`timestamp`, `user_id`, `agent_id` and `run_id`) before anything is queued: a bad row is refused\nwith its index in the message, and nothing is imported. Then the job is queued and the\ncall answers 202 with its `job_` id. The worker writes the rows, which get\ntheir facts as any write does; `GET /v1/batch/{job_id}` says how far it is.\nIf the key is revoked, expires or is moved to another project before the\nworker is done, the rows not yet imported are not: each is a failed row\nwith its reason in `errors`, and the job completes.", "operationId": "create_batch_v1_batch_post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "X-Korely-Client", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The tool importing: kept on every imported memory as `client`.", "title": "X-Korely-Client" }, "description": "The tool importing: kept on every imported memory as `client`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchBody" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchAccepted" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's writes of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at`, a top-up or a bigger plan). And `agent_cap_exceeded`: a new `agent_id` past the plan's named agents (`limit`, `used`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`. Or `unavailable`: the server holds as many request bodies as it reads at once; retry after `Retry-After` (5 s). Nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "`payload_too_large`: the body is larger than 78,245,152 bytes, the most this route takes with a key that may write (2,097,152 without one). Refused before it is read; nothing was done. Also a body under 78,245,152 bytes that holds more JSON strings (1,382,024), values (2,747,524) or characters (13,119,024) than the most items can, or whose text decodes to more than it weighs and more than 78,245,152 bytes: read whole, refused before it is decoded; nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "408": { "description": "`request_timeout`: the body did not arrive whole within 30 s. A body past 2,097,152 bytes has 120 s from being let in. Nothing was done; send it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "400": { "description": "`bad_request`: the body is not well formed. A JSON body not in UTF-8 (RFC 8259) is refused before it is decoded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/batch/{job_id}": { "get": { "tags": [ "v1" ], "summary": "Get Batch", "description": "Where an import stands: its `status`, how many rows were `received`,\n`imported` and `failed`, and the `errors` of the rows that failed. A job\nof another project is a 404, and so, for a key confined to some end\nusers, is a job another key queued.", "operationId": "get_batch_v1_batch__job_id__get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchStatus" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`not_found`: nothing with that id is reachable with this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/ping": { "get": { "tags": [ "v1" ], "summary": "Ping", "description": "Check a key before pointing an agent at it: 200 with its `scopes`, the\n`processing_region` where a model reads its memories (null when that\nregion has no model to write with) and `region`, a label the operator set\nwith REGION (`eu` when not set), which the service cannot check: not a\nstatement of where the data is. Or 401. No scope is needed. It counts\nagainst the request ceiling like every other call: past it, 429 with\n`Retry-After`.", "operationId": "ping_v1_ping_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Ping V1 Ping Get" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/audit": { "get": { "tags": [ "v1" ], "summary": "List Audit", "description": "The events this key's project produced, newest first.\n\nScoped to the caller's own account AND project by the key, like\neverything else here; a key confined to some end users reads their\nevents only. Each row carries the project its call was made in. The\noperator's screen (/admin/audit) reads the whole account.", "operationId": "list_audit_v1_audit_get", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Only events touching this end user.", "title": "User Id" }, "description": "Only events touching this end user." }, { "name": "action", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32 }, { "type": "null" } ], "title": "Action" } }, { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "description": "ISO date (2026-06-01, midnight) or datetime; no offset is UTC. Inclusive.", "title": "Since" }, "description": "ISO date (2026-06-01, midnight) or datetime; no offset is UTC. Inclusive." }, { "name": "until", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "description": "ISO date (2026-06-01, midnight) or datetime; no offset is UTC. Inclusive.", "title": "Until" }, "description": "ISO date (2026-06-01, midnight) or datetime; no offset is UTC. Inclusive." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 9223372036854775807, "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditPage" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/agents/init": { "post": { "tags": [ "account" ], "summary": "Create an account and its first key, without a login", "description": "Create an account with no login, its Default project and a key that\ndoes not expire, in one call and with no key: 201 with the key, shown\nthis once, the plan's monthly numbers and the Terms that creating the\naccount accepts. The account is on the free plan; signing in to the\ndashboard with this key adopts it, and from there it can buy a plan.\n`processing_region` picks where the models that write its memories run.\n403 `signup_disabled` while sign-ups are closed; 429\n`signup_rate_limited` past the day's new accounts, of every network or\nof the caller's.", "operationId": "init_agent_v1_agents_init_post", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InitBody" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "413": { "description": "`payload_too_large`: the body is larger than 2,097,152 bytes, the most this route takes. Refused before it is read; nothing was done. Also a body that holds more JSON strings (36,930), values (72,433) or characters (342,092) than lawful items of its size can, whose text decodes to more than it weighs and more than 4,077,000 bytes, or that would take more than 8,388,608 bytes once decoded: refused before it is decoded; nothing was done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "408": { "description": "`request_timeout`: the body did not arrive whole within 30 s. Nothing was done; send it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "400": { "description": "`bad_request`: the body is not well formed. A JSON body not in UTF-8 (RFC 8259) is refused before it is decoded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "`unavailable`: the server holds as many request bodies as it reads at once; retry after `Retry-After` (5 s). Nothing was done. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [] } }, "/v1/account": { "delete": { "tags": [ "account" ], "summary": "Delete the account of this key (accounts made with POST /v1/agents/init)", "description": "Delete, for good, the account this key belongs to: every key, project,\nmemory and fact, and its subscription at Polar if it has one. Only for an\naccount made with POST /v1/agents/init that nobody signs in to; 409\n`account_has_login` for one with a login, which closes from the\ndashboard. 400 `confirmation_required` without `?confirm=true`. The\nreply counts the rows removed per table. Needs the `admin` scope: the key\n`POST /v1/agents/init` returns holds it, and a key made later without it,\nor confined to some end users, answers 403 `forbidden` (since 1.0.5).", "operationId": "delete_account_v1_account_delete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "confirm", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Must be true: the account, its keys and every memory are deleted for good.", "default": false, "title": "Confirm" }, "description": "Must be true: the account, its keys and every memory are deleted for good." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeleted" } } } }, "401": { "description": "`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`forbidden`: the key lacks the scope this operation needs; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the server failed on this request; `message` holds no detail of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "400": { "description": "`confirmation_required`: `?confirm=true` is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "`account_has_login`: the account has a login; close it from the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "schemas": { "AccountDeleted": { "properties": { "deleted": { "type": "boolean", "title": "Deleted", "default": true }, "removed": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Removed" } }, "type": "object", "title": "AccountDeleted" }, "AddBody": { "properties": { "content": { "type": "string", "maxLength": 16000, "minLength": 1, "title": "Content" }, "user_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "User Id", "description": "The end user this memory belongs to. 1 to 255 characters, no '/', no control characters, and not '.' or '..': the id names a namespace that DELETE /v1/users//memories and DELETE /v1/agents/ address as one URL path segment." }, "agent_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Agent Id", "description": "Agent namespace. 1 to 255 characters, no '/', no control characters, and not '.' or '..': the id names a namespace that DELETE /v1/users//memories and DELETE /v1/agents/ address as one URL path segment." }, "run_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Run Id" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "kind": { "type": "string", "enum": [ "note", "session" ], "title": "Kind", "description": "What the text is: `note` (the default), what somebody said or decided; `session`, the log of a work session (what a coding assistant's hooks save). A read may leave the sessions out, their facts with them (`exclude_sessions`).", "default": "note" }, "timestamp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timestamp", "description": "ISO date/datetime the memory's events occurred (defaults to now). Facts extracted inherit it as valid_from, so `as_of` point-in-time queries reflect when things were true, not when they were ingested. A moment from 0001-01-02 to 9999-12-30, in UTC; outside it, or unreadable, a 422." } }, "additionalProperties": false, "type": "object", "required": [ "content" ], "title": "AddBody" }, "AgentScope": { "properties": { "agent_id": { "type": "string", "title": "Agent Id" }, "memories": { "type": "integer", "title": "Memories" }, "facts": { "type": "integer", "title": "Facts" }, "last_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Active" } }, "type": "object", "required": [ "agent_id", "memories", "facts", "last_active" ], "title": "AgentScope" }, "AgentsResponse": { "properties": { "agents": { "items": { "$ref": "#/components/schemas/AgentScope" }, "type": "array", "title": "Agents" }, "total": { "type": "integer", "title": "Total" }, "cap": { "type": "integer", "title": "Cap", "description": "The most agent names a write may bring in: 0 when nothing caps them, as on an install of one's own. A write under a new name past it is refused." }, "used": { "type": "integer", "title": "Used", "description": "The agent names `cap` counts, over the set it caps (the whole account where a plan caps them); with no ceiling, the names this key sees, which `total` counts." } }, "type": "object", "required": [ "agents", "total", "cap", "used" ], "title": "AgentsResponse" }, "ApiError": { "properties": { "detail": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ErrorCode" }, { "items": { "$ref": "#/components/schemas/ValidationIssue" }, "type": "array" } ], "title": "Detail", "description": "As this install has always sent it: a sentence; or `{code, message}` where the endpoint names the reason; or, on a 422 from validation, the list of fields that failed." }, "code": { "type": "string", "title": "Code", "description": "Stable, machine-readable reason, the same names as the hosted API: `invalid_key`, `forbidden`, `not_found`, `stale_write`, `invalid_request`, `rate_limit_exceeded`, `search_unavailable`, `model_unavailable`, `service_paused`, `internal_error`... When `detail` is `{code, message}` it is that code. Branch on this, never on `message`.", "examples": [ "not_found" ] }, "message": { "type": "string", "title": "Message", "description": "What went wrong, for a person to read: the sentence, the message of `detail`, or the first field that failed validation. Wording may change." }, "current_fact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Fact Id", "description": "`fact_not_current`: the fact in force to correct instead, null when nothing took the fact's place. Absent on every other refusal." } }, "type": "object", "required": [ "detail", "code", "message" ], "title": "ApiError", "description": "The body of every answer that is not a success, whatever the status." }, "AuditPage": { "properties": { "events": { "items": { "$ref": "#/components/schemas/AuditRow" }, "type": "array", "title": "Events" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "events", "total" ], "title": "AuditPage" }, "AuditRead": { "properties": { "memories": { "items": { "type": "string" }, "type": "array", "title": "Memories", "description": "Public ids of the memories the call returned, at most 100." }, "facts": { "items": { "type": "string" }, "type": "array", "title": "Facts", "description": "Public ids of the facts the call returned, at most 100." } }, "type": "object", "title": "AuditRead" }, "AuditRow": { "properties": { "ts": { "type": "string", "format": "date-time", "title": "Ts" }, "actor": { "type": "string", "title": "Actor", "description": "Who acted: `rest`, a key over REST, or an admin key on /admin; `mcp`, a key over MCP; `dashboard`, an operator signed in to the dashboard; `manage`, the command line (`manage`); `worker`, the background worker; `oauth`, an app connected over OAuth: its key made, renewed or revoked; `install`, a change to what is the whole install's, filed in every account's trail." }, "action": { "type": "string", "title": "Action", "description": "read | write | fact_write | fact_invalidate | erase | key_create | key_revoke | key_change | tenant_create | setting_change | login | logout" }, "result": { "type": "string", "title": "Result", "description": "ok | error. `error`: the call was refused or could not be served, and `meta.code` says why with the token the call answered (`forbidden`, `not_found`, `quota_exceeded`, `search_unavailable`, ...), never a sentence." }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "The end user the event touched. After their erasure, a keyed pseudonym (`erased:...`): ask with their id and it is found." }, "target_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Id", "description": "The memory or fact acted on, by public id." }, "meta": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Meta", "description": "Counts and labels, never content. A read says how many memories and facts it returned (memories_read, facts_read)." }, "ip": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ip" }, "read": { "anyOf": [ { "$ref": "#/components/schemas/AuditRead" }, { "type": "null" } ], "description": "For reads: what the call returned, by id. With as_of on /v1/facts it rebuilds what the agent knew at that moment." } }, "type": "object", "required": [ "ts", "actor", "action", "result" ], "title": "AuditRow" }, "BatchAccepted": { "properties": { "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "title": "Status", "description": "pending (queued, no worker on it yet), processing (being imported now), completed (every item tried: `imported` and `failed` are final) or failed (stopped on an error of the worker, tried again from where it stopped until its attempts are used, so it may still become completed). The POST answers the stored value, as the GET does." }, "received": { "type": "integer", "title": "Received" } }, "type": "object", "required": [ "id", "status", "received" ], "title": "BatchAccepted" }, "BatchBody": { "properties": { "memories": { "items": { "$ref": "#/components/schemas/BatchMemory" }, "type": "array", "maxItems": 500, "minItems": 1, "title": "Memories" } }, "additionalProperties": false, "type": "object", "required": [ "memories" ], "title": "BatchBody" }, "BatchMemory": { "properties": { "content": { "type": "string", "maxLength": 16000, "minLength": 1, "title": "Content" }, "user_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "User Id", "description": "The end user this memory belongs to. 1 to 255 characters, no '/', no control characters, and not '.' or '..': the id names a namespace that DELETE /v1/users//memories and DELETE /v1/agents/ address as one URL path segment." }, "agent_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Agent Id", "description": "Agent namespace. 1 to 255 characters, no '/', no control characters, and not '.' or '..': the id names a namespace that DELETE /v1/users//memories and DELETE /v1/agents/ address as one URL path segment." }, "run_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Run Id" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "kind": { "type": "string", "enum": [ "note", "session" ], "title": "Kind", "description": "What the text is: `note` (the default), what somebody said or decided; `session`, the log of a work session (what a coding assistant's hooks save). A read may leave the sessions out, their facts with them (`exclude_sessions`).", "default": "note" }, "timestamp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timestamp", "description": "ISO date/datetime the memory's events occurred (defaults to the time the item is imported). Facts extracted inherit it as valid_from, exactly as on POST /v1/memories, and an unreadable one refuses the batch (422) rather than being replaced by the import time, as does one outside the moments that can be stored (from 0001-01-02 to 9999-12-30, in UTC)." } }, "additionalProperties": false, "type": "object", "required": [ "content" ], "title": "BatchMemory" }, "BatchStatus": { "properties": { "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "title": "Status", "description": "pending (queued, no worker on it yet), processing (being imported now), completed (every item tried: `imported` and `failed` are final) or failed (stopped on an error of the worker, tried again from where it stopped until its attempts are used, so it may still become completed). The POST answers the stored value, as the GET does." }, "received": { "type": "integer", "title": "Received" }, "imported": { "type": "integer", "title": "Imported" }, "failed": { "type": "integer", "title": "Failed" }, "errors": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Errors" } }, "type": "object", "required": [ "id", "status", "received", "imported", "failed", "errors" ], "title": "BatchStatus" }, "ContextResponse": { "properties": { "context": { "type": "string", "title": "Context" }, "tokens": { "type": "integer", "title": "Tokens" }, "sources": { "items": { "type": "string" }, "type": "array", "title": "Sources" }, "degraded": { "type": "boolean", "title": "Degraded", "default": false }, "degraded_parts": { "items": { "type": "string" }, "type": "array", "title": "Degraded Parts" }, "stable": { "type": "string", "title": "Stable", "description": "The head of `context` that does not depend on the question: the reader note, the same text from one call to the next. Put it in your system prompt, where the model provider's prompt cache can reuse it.", "default": "" }, "volatile": { "type": "string", "title": "Volatile", "description": "The rest of `context`: the facts and the memories for this question and, when part of the retrieval failed, a closing NOTE. Put it in the turn.", "default": "" }, "stable_hash": { "type": "string", "title": "Stable Hash", "description": "SHA-256 (hex) of `stable`. The same value means the same prefix, so a cached system prompt is still valid.", "default": "" } }, "type": "object", "required": [ "context", "tokens", "sources" ], "title": "ContextResponse" }, "CorrectBody": { "properties": { "subject": { "anyOf": [ { "type": "string", "maxLength": 200, "minLength": 1 }, { "type": "null" } ], "title": "Subject" }, "predicate": { "anyOf": [ { "type": "string", "maxLength": 200, "minLength": 1 }, { "type": "null" } ], "title": "Predicate" }, "object": { "anyOf": [ { "type": "string", "maxLength": 500, "minLength": 1 }, { "type": "null" } ], "title": "Object" } }, "additionalProperties": false, "type": "object", "title": "CorrectBody", "description": "Superseding a fact with corrected values. At least one field." }, "ErrorCode": { "properties": { "code": { "type": "string", "title": "Code", "description": "Stable, machine-readable reason, e.g. `not_found`, `stale_write`, `invalid_request`, `search_unavailable`. Branch on this, never on `message`.", "examples": [ "not_found" ] }, "message": { "type": "string", "title": "Message", "description": "What went wrong, for a person to read. Wording may change." } }, "type": "object", "required": [ "code", "message" ], "title": "ErrorCode", "description": "A refusal with a stable reason." }, "EventsResponse": { "properties": { "events": { "items": { "$ref": "#/components/schemas/MemoryEvent" }, "type": "array", "title": "Events" }, "processing": { "type": "integer", "title": "Processing", "description": "Writes of this key's project (of `user_id`, when given) still in flight, counted over all of them. Independent of `status` and `limit`." } }, "type": "object", "required": [ "events", "processing" ], "title": "EventsResponse" }, "Fact": { "properties": { "id": { "type": "string", "title": "Id", "description": "The fact's `fct_` id." }, "subject": { "type": "string", "title": "Subject", "description": "The subject as it was written." }, "subject_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject Type", "description": "What the subject is, as the write that stored the fact gave it: extraction gives one of `concept`, `event`, `organization`, `person`, `place`, `product`, `unknown`; a POST /v1/facts may have sent any type of up to 20 characters. A write that restates a fact already true keeps the type the fact was first stored with. `self` (lower case, matched exactly): GET /v1/profile counts a fact so typed as one about the end user and lists it first. The context block of GET /v1/context does not read the type: it tells the end user by the subject." }, "predicate": { "type": "string", "title": "Predicate", "description": "The relation, canonical: `lives_in`." }, "predicate_raw": { "type": "string", "title": "Predicate Raw", "description": "The relation as it was extracted." }, "object": { "type": "string", "title": "Object", "description": "The object as it was written." }, "object_is_literal": { "type": "boolean", "title": "Object Is Literal", "description": "True for a value (a date, an amount), false for an entity." }, "predicate_family": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Predicate Family", "description": "The relation's family: one of `preferences`, `people`, `places`, `work`, `ownership`, `health`, `financial`, `events`, `identity`, `other`." }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Confidence" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "The end user the fact belongs to." }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id", "description": "The agent namespace it was written under." }, "valid_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Valid From", "description": "When it became true in the world: an ISO date/datetime from 0001-01-02 to 9999-12-30, in UTC; outside it, or unreadable, a 422." }, "invalid_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invalid At", "description": "When it stopped being true. Null while it holds, and, read with `known_as_of`, while the store had not learned the end yet." }, "invalidated_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invalidated By", "description": "The `fct_` id of the fact that closed it." }, "source_memory_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Memory Id", "description": "The memory it was extracted from." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "When the store learned the fact." }, "closed_known_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Closed Known At", "description": "When the store learned the fact had ended. Null while it is open." }, "subject_canonical": { "type": "string", "title": "Subject Canonical", "description": "The subject's current name, after its aliases and its object link." }, "object_canonical": { "type": "string", "title": "Object Canonical", "description": "The object's current name, after its aliases and its object link." }, "subject_link_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject Link Id", "description": "The object link that shows the subject under `subject_canonical`: two names of one thing the writer judged the same (memory_core 6.1.0, off by default). Null when none does." }, "object_link_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Object Link Id", "description": "The same, for the object." }, "tense": { "type": "string", "title": "Tense", "description": "What the text said: current, past or planned." }, "last_confirmed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Confirmed At", "description": "The last time a memory said it again." }, "observation_count": { "type": "integer", "title": "Observation Count", "description": "How many memories said it." }, "source_memory_ids": { "items": { "type": "string" }, "type": "array", "title": "Source Memory Ids", "description": "Every memory that said it." } }, "additionalProperties": true, "type": "object", "required": [ "id", "subject", "predicate", "predicate_raw", "object", "object_is_literal", "subject_canonical", "object_canonical", "tense", "observation_count", "source_memory_ids" ], "title": "Fact", "description": "A fact as a read answers it. A field added in a later release still\npasses (`extra` is allowed)." }, "FactBody": { "properties": { "subject": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Subject" }, "predicate": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Predicate" }, "object": { "type": "string", "maxLength": 500, "minLength": 1, "title": "Object" }, "user_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "User Id", "description": "End user this fact is about. 1 to 255 characters, no '/', no control characters, and not '.' or '..': the id names a namespace that DELETE /v1/users//memories and DELETE /v1/agents/ address as one URL path segment." }, "agent_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Agent Id", "description": "Agent namespace. 1 to 255 characters, no '/', no control characters, and not '.' or '..': the id names a namespace that DELETE /v1/users//memories and DELETE /v1/agents/ address as one URL path segment." }, "run_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Run Id" }, "subject_type": { "type": "string", "maxLength": 20, "title": "Subject Type", "description": "What the subject is: any type of up to 20 characters, stored as sent on a new fact (an empty one as `unknown`). A write that restates a fact already true keeps the type the fact was first stored with, and POST answers that fact's id. Extraction gives one of `concept`, `event`, `organization`, `person`, `place`, `product`, `unknown`. `self` (lower case, matched exactly): GET /v1/profile counts a fact so typed as one about the end user and lists it first, as it does a fact whose subject is the end user's id. The context block of GET /v1/context does not read the type: it tells the end user by the subject.", "default": "unknown" }, "object_is_literal": { "type": "boolean", "title": "Object Is Literal", "default": false }, "confidence": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Confidence", "default": 0.9 }, "valid_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Valid From" }, "tense": { "type": "string", "enum": [ "current", "past", "planned" ], "title": "Tense", "description": "current | past | planned. A past fact closes the open fact it restates.", "default": "current" } }, "additionalProperties": false, "type": "object", "required": [ "subject", "predicate", "object" ], "title": "FactBody" }, "FactWriteResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "subject": { "type": "string", "title": "Subject" }, "predicate": { "type": "string", "title": "Predicate" }, "object": { "type": "string", "title": "Object" }, "predicate_family": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Predicate Family", "description": "The relation's family: one of `preferences`, `people`, `places`, `work`, `ownership`, `health`, `financial`, `events`, `identity`, `other`." }, "valid_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Valid From" }, "invalidated": { "items": { "type": "string" }, "type": "array", "title": "Invalidated", "default": [] }, "tense": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tense", "default": "current" }, "invalid_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invalid At" }, "observation_count": { "type": "integer", "title": "Observation Count", "default": 1 }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" } }, "type": "object", "required": [ "id", "subject", "predicate", "object" ], "title": "FactWriteResponse", "description": "The write shape of POST /v1/facts (and the facts[] inline on a memory\nwrite): the new fact + the ids it superseded." }, "FactsResponse": { "properties": { "facts": { "items": { "$ref": "#/components/schemas/Fact" }, "type": "array", "title": "Facts" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "facts", "total" ], "title": "FactsResponse" }, "ForgetBody": { "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At", "description": "ISO date/datetime it STOPPED being true. Defaults to now. This is the date of the change, not the date you noticed it: set it to when the world changed and `as_of` before that still returns the fact. Equal to the fact's `valid_from` it retracts the fact (true at no moment, kept in the history); earlier is a 422. With no `at`, a fact dated ahead ends at its own start, never before it." } }, "additionalProperties": false, "type": "object", "title": "ForgetBody", "description": "Closing a fact. Everything optional: the common case is a bare POST." }, "ForgetResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "title": "Status" }, "invalid_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invalid At" }, "audit_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audit Id" } }, "type": "object", "required": [ "id", "status" ], "title": "ForgetResponse" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HistoryEvent": { "properties": { "event": { "type": "string", "title": "Event" }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At" }, "fact": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fact" }, "fact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fact Id" } }, "type": "object", "required": [ "event", "at" ], "title": "HistoryEvent" }, "InitBody": { "properties": { "agent_caller": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Agent Caller", "description": "Who is signing up, e.g. 'claude-code'. A free-form label, kept for your reference." }, "processing_region": { "anyOf": [ { "type": "string", "enum": [ "eu", "global" ] }, { "type": "null" } ], "title": "Processing Region", "description": "Where the models that write your memories run, for the account's Default project: 'global' (the default) or 'eu' (a provider in the European Union). Where the data is stored does not change with it (`region`). Changeable later per project." } }, "type": "object", "title": "InitBody" }, "InitResult": { "properties": { "api_key": { "type": "string", "title": "Api Key" }, "tier": { "type": "string", "title": "Tier" }, "region": { "type": "string", "title": "Region", "description": "Where the data is stored." }, "processing_region": { "type": "string", "title": "Processing Region", "description": "Where the models that write the Default project's memories run: global, or eu (a provider in the European Union)." }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes" }, "quotas": { "additionalProperties": true, "type": "object", "title": "Quotas" }, "terms_url": { "type": "string", "title": "Terms Url", "description": "The Terms of Service. Creating the account accepts them, for whoever operates the agent and holds the key." }, "privacy_url": { "type": "string", "title": "Privacy Url", "description": "The Privacy Policy." } }, "type": "object", "required": [ "api_key", "tier", "region", "processing_region", "scopes", "quotas", "terms_url", "privacy_url" ], "title": "InitResult" }, "Memory": { "properties": { "id": { "type": "string", "title": "Id" }, "content": { "type": "string", "title": "Content" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "client": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client", "description": "The tool that wrote it: the X-Korely-Client header of the write, or the name an MCP client gave when it connected. A label, not a namespace: no read is scoped by it and the agent cap does not count it." }, "kind": { "type": "string", "title": "Kind", "description": "`note`, or `session` for the log of a work session (`kind` of the write).", "default": "note" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" }, "status": { "type": "string", "title": "Status", "description": "Whether this memory's typed facts are queryable yet: 'processing', 'ready', or 'error'. Extraction runs after the write returns, so a read taken immediately can legitimately find no facts. Poll GET /v1/events or read the memory again: no webhook says that extraction finished (`memory.created` is sent when the memory is stored, before its facts).", "default": "processing" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "id", "content", "user_id", "agent_id", "run_id", "metadata", "created_at", "updated_at" ], "title": "Memory" }, "MemoryEvent": { "properties": { "memory_id": { "type": "string", "title": "Memory Id" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "status": { "type": "string", "title": "Status" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "memory_id", "user_id", "agent_id", "status", "created_at" ], "title": "MemoryEvent" }, "MemoryHistory": { "properties": { "id": { "type": "string", "title": "Id" }, "events": { "items": { "$ref": "#/components/schemas/HistoryEvent" }, "type": "array", "title": "Events" } }, "type": "object", "required": [ "id", "events" ], "title": "MemoryHistory" }, "MemoryList": { "properties": { "memories": { "items": { "$ref": "#/components/schemas/Memory" }, "type": "array", "title": "Memories" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "memories", "total" ], "title": "MemoryList" }, "MemoryWithFacts": { "properties": { "id": { "type": "string", "title": "Id" }, "content": { "type": "string", "title": "Content" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "client": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client", "description": "The tool that wrote it: the X-Korely-Client header of the write, or the name an MCP client gave when it connected. A label, not a namespace: no read is scoped by it and the agent cap does not count it." }, "kind": { "type": "string", "title": "Kind", "description": "`note`, or `session` for the log of a work session (`kind` of the write).", "default": "note" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" }, "status": { "type": "string", "title": "Status", "description": "Whether this memory's typed facts are queryable yet: 'processing', 'ready', or 'error'. Extraction runs after the write returns, so a read taken immediately can legitimately find no facts. Poll GET /v1/events or read the memory again: no webhook says that extraction finished (`memory.created` is sent when the memory is stored, before its facts).", "default": "processing" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" }, "facts": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Facts", "default": [] } }, "type": "object", "required": [ "id", "content", "user_id", "agent_id", "run_id", "metadata", "created_at", "updated_at" ], "title": "MemoryWithFacts" }, "NameBody": { "properties": { "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name", "description": "Another name of the end user, as the memories write it: a full name (\"Maria Rossi\") for the id `maria`." }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id", "description": "The agent namespace whose memory the name is declared in; none for the end user's own memory." } }, "additionalProperties": false, "type": "object", "required": [ "name" ], "title": "NameBody" }, "NameResponse": { "properties": { "user_id": { "type": "string", "title": "User Id" }, "name": { "type": "string", "title": "Name" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "since": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Since" } }, "type": "object", "required": [ "user_id", "name" ], "title": "NameResponse" }, "ProfileResponse": { "properties": { "user_id": { "type": "string", "title": "User Id" }, "as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "As Of" }, "known_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Known As Of" }, "facts": { "items": { "$ref": "#/components/schemas/Fact" }, "type": "array", "title": "Facts" }, "by_family": { "additionalProperties": { "items": { "$ref": "#/components/schemas/Fact" }, "type": "array" }, "type": "object", "title": "By Family" }, "total": { "type": "integer", "title": "Total" }, "truncated": { "type": "boolean", "title": "Truncated" } }, "type": "object", "required": [ "user_id", "as_of", "facts", "by_family", "total", "truncated" ], "title": "ProfileResponse" }, "SearchBody": { "properties": { "query": { "type": "string", "maxLength": 2000, "minLength": 1, "title": "Query" }, "user_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "User Id" }, "agent_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Agent Id" }, "run_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Run Id", "description": "Scope to one run/session." }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Filter on the metadata you stored at write time, e.g. {\"tier\": \"pro\"}. Keys are ANDed. A value matches the stored value compared as text (true, false and numbers as JSON writes them, so \"5\" matches 5), a number also matches an equal number (5 and 5.0), and null matches a stored null. Strings, numbers, booleans and null only: an object or an array is a 422. At most 32 keys and 8,192 bytes, what stored metadata may hold: past either it is a 422." }, "limit": { "type": "integer", "maximum": 50.0, "minimum": 1.0, "title": "Limit", "default": 15 }, "exclude_sessions": { "type": "boolean", "title": "Exclude Sessions", "description": "Leave out the work sessions (memories written with `kind: session`, what a coding assistant's hooks save), for a read that wants what was said and decided. Default false: everything.", "default": false }, "min_score": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Min Score", "description": "Leave out the memories whose `score` is below this, 0 to 1 (a cosine similarity, compared as the response shows it). Absent: no floor, every nearest memory comes back. Fewer than `limit` results can come back, none when nothing in the store is that close. A higher floor drops more of the weak matches and, past some value, true ones too: the right value depends on your texts and on the embedding model." } }, "additionalProperties": false, "type": "object", "required": [ "query" ], "title": "SearchBody" }, "SearchResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/SearchResult" }, "type": "array", "title": "Results" } }, "type": "object", "required": [ "results" ], "title": "SearchResponse" }, "SearchResult": { "properties": { "id": { "type": "string", "title": "Id" }, "score": { "type": "number", "title": "Score" }, "snippet": { "type": "string", "title": "Snippet" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" } }, "type": "object", "required": [ "id", "score", "snippet", "user_id", "agent_id", "metadata" ], "title": "SearchResult" }, "UpdateBody": { "properties": { "content": { "type": "string", "maxLength": 16000, "minLength": 1, "title": "Content" }, "expected_updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Updated At", "description": "Optimistic concurrency: the `updated_at` you read (`created_at` while `updated_at` is null), sent back as the API returned it. The edit is written only if the memory is still at that version, to the microsecond, when it is written; otherwise 409 `stale_write` and nothing changes. A value that is not an ISO 8601 instant, the empty string included, is a 422 and nothing changes; leave the field out for an edit without the check." } }, "additionalProperties": false, "type": "object", "required": [ "content" ], "title": "UpdateBody" }, "UserErasureResponse": { "properties": { "user_id": { "type": "string", "title": "User Id", "description": "The end user that was erased." }, "memories_deleted": { "type": "integer", "title": "Memories Deleted", "description": "Memories physically deleted." }, "facts_deleted": { "type": "integer", "title": "Facts Deleted", "description": "Facts physically deleted." }, "erasure": { "type": "string", "title": "Erasure", "description": "Always `permanent`." }, "audit_id": { "type": "string", "title": "Audit Id", "description": "The `aud_` id of the audit row, which keeps the counts and a keyed pseudonym of your end user id, never the erased content." } }, "type": "object", "required": [ "user_id", "memories_deleted", "facts_deleted", "erasure", "audit_id" ], "title": "UserErasureResponse", "description": "DELETE /v1/users/{end_user}/memories: what was physically deleted.\nField order is the order on the wire." }, "UserScope": { "properties": { "user_id": { "type": "string", "title": "User Id" }, "memories": { "type": "integer", "title": "Memories" }, "facts": { "type": "integer", "title": "Facts" }, "last_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Active" } }, "type": "object", "required": [ "user_id", "memories", "facts", "last_active" ], "title": "UserScope" }, "UsersResponse": { "properties": { "users": { "items": { "$ref": "#/components/schemas/UserScope" }, "type": "array", "title": "Users" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "users", "total" ], "title": "UsersResponse" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "ValidationIssue": { "properties": { "type": { "type": "string", "title": "Type", "description": "What kind of failure, e.g. `missing`, `extra_forbidden`, `string_too_long`, `invalid_namespace_id`." }, "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Loc", "description": "Where: `body`, `query` or `path`, then the field, e.g. [\"body\", \"memories\", 0, \"user_id\"]." }, "msg": { "type": "string", "title": "Msg", "description": "What is wrong with it, for a person to read." }, "ctx": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Ctx", "description": "The limit that was crossed, when there is one." } }, "type": "object", "required": [ "type", "loc", "msg" ], "title": "ValidationIssue", "description": "One field that failed validation. The value sent is never echoed back." } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your kor_live_ API key." } } } }