{ "openapi": "3.1.0", "info": { "title": "Korely Agents API", "version": "0.1.31", "description": "The Korely Agents 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", "operationId": "add_memory_v1_memories_post", "security": [ { "bearerAuth": [] } ], "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "get": { "tags": [ "v1" ], "summary": "List Memories", "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", "minimum": 0, "default": 0, "title": "Offset" } } ], "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/memories/{memory_id}": { "patch": { "tags": [ "v1" ], "summary": "Update Memory", "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "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" } } } } } }, "delete": { "tags": [ "v1" ], "summary": "Delete Memory", "operationId": "delete_memory_v1_memories__memory_id__delete", "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": { "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "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 every memory and fact for one end user (GDPR Art. 17).\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`. `memories_forgotten` and `facts_invalidated` carry the same\ntwo numbers under their original names and are deprecated: nothing was\nforgotten or invalidated, it was deleted. Read the new names.\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, the cost rows lose the\nend user, and a webhook already delivered takes the pseudonym.\n\nFor a reversible drop-from-reads on a single item, use\n`DELETE /v1/memories/{memory_id}` instead.", "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/memories/search": { "post": { "tags": [ "v1" ], "summary": "Search Memories", "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "`search_unavailable`: the embedding provider did not answer, so semantic search could not run. Not an empty result; retry.", "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\nPrefer the `fact_extracted` webhook when you can receive one. This is the\npull equivalent for local development, serverless, and scripts.", "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "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 \u2014 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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "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", "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "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 ``used``, how many namespaces there are, and ``cap``,\nwhich is 0: this install sets no ceiling on agent namespaces.\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", "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/facts": { "get": { "tags": [ "v1" ], "summary": "List Facts", "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" } ], "title": "Predicate Family" } }, { "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 \u2014 point-in-time validity.", "title": "As Of" }, "description": "ISO date/datetime \u2014 point-in-time validity." }, { "name": "known_as_of", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO date/datetime \u2014 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.", "title": "Known As Of" }, "description": "ISO date/datetime \u2014 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." }, { "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", "minimum": 0, "default": 0, "title": "Offset" } } ], "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "tags": [ "v1" ], "summary": "Create Fact", "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "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.", "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, contradiction detection becomes optional rather than load\nbearing: an agent that knows a fact is finished says so, and nothing has to\ninfer it. That is the configuration with no model in the write path at all.\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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "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/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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "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" } } } }, "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.", "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 \u2014 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 \u2014 the profile as it was on that date.", "title": "As Of" }, "description": "ISO date/datetime \u2014 the profile as it was on that date." }, { "name": "known_as_of", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO date/datetime \u2014 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.", "title": "Known As Of" }, "description": "ISO date/datetime \u2014 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." } ], "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/context": { "get": { "tags": [ "v1" ], "summary": "Get Context", "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. Default 800; we recommend 4000 for an agent that answers questions about the past (on 60 LongMemEval questions the memory holding the answer reached the block for 82% of them at 2000 tokens, 95% at 4000). A larger budget 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. Default 800; we recommend 4000 for an agent that answers questions about the past (on 60 LongMemEval questions the memory holding the answer reached the block for 82% of them at 2000 tokens, 95% at 4000). A larger budget 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 \u2014 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 \u2014 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." } ], "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/batch": { "post": { "tags": [ "v1" ], "summary": "Create Batch", "operationId": "create_batch_v1_batch_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchBody" } } }, "required": true }, "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/batch/{job_id}": { "get": { "tags": [ "v1" ], "summary": "Get Batch", "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "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", "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" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "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 tenant AND project by the key, like everything\nelse here: an audit trail readable across tenants would be the most\nsensitive endpoint in the service, and across projects it is the same\nendpoint one wall further in. Until 2026-09-28 it read the whole account,\nso a key confined to one project listed the end user ids, memory ids and\nactions of every other one, and could ask for them by `user_id`. Each row\nnow carries the project its call was made in. The operator's screen\n(/admin/requests) 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", "format": "date-time" }, { "type": "null" } ], "title": "Since" } }, { "name": "until", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Until" } }, { "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", "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` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`rate_limit_exceeded`: the per-minute rate limit set on this install (see `Retry-After`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "`internal_error`: the request failed on our side.", "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", "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" } } } } }, "security": [] } }, "/v1/account": { "delete": { "tags": [ "account" ], "summary": "Delete the account of this key (accounts made with POST /v1/agents/init)", "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" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "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" }, "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." } }, "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": "0: no ceiling on agent namespaces on this install." }, "used": { "type": "integer", "title": "Used" } }, "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`, `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": "rest | mcp | dashboard | manage | worker" }, "action": { "type": "string", "title": "Action", "description": "read | write | fact_write | fact_invalidate | erase | key_create | key_revoke | key_change | tenant_create | setting_change | login" }, "result": { "type": "string", "title": "Result", "description": "ok | denied | error" }, "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", "title": "Status" }, "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" }, "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." } }, "additionalProperties": false, "type": "object", "required": [ "content" ], "title": "BatchMemory" }, "BatchStatus": { "properties": { "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "title": "Status" }, "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: self, a person, an organization..." }, "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: `location`, `role`..." }, "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." }, "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." }, "object_canonical": { "type": "string", "title": "Object Canonical", "description": "The object's current name, after its aliases." }, "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 (services.facts.serialize_fact). Typed\nsince 0.1.27, so the OpenAPI document lists its fields: it was a free\nobject, and the site's spec could not show `closed_known_at` (A, 11 Oct\n2026). The answer is the same; a field added later still passes." }, "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", "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" }, "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." } }, "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": [ "global", "eu" ] }, { "type": "null" } ], "title": "Processing Region", "description": "Where the models that write your memories run, for the account's Default project: 'global' (Google Gemini, the default) or 'eu' (Scaleway, Paris). The data is stored in the EU either way (`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 (Google Gemini) or eu (Scaleway, Paris)." }, "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" }, "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 receive the fact_extracted webhook.", "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" }, "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 receive the fact_extracted webhook.", "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" }, "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." }, "limit": { "type": "integer", "maximum": 50.0, "minimum": 1.0, "title": "Limit", "default": 15 }, "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. 0.20 is the value measured on LongMemEval with the local EmbeddingGemma: no best evidence lost, and more than half of the searches with no answer in the store come back empty; the right value depends on your texts." } }, "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." } }, "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_forgotten": { "type": "integer", "title": "Memories Forgotten", "description": "Deprecated alias of `memories_deleted`, same value. The rows are physically deleted, not forgotten.", "deprecated": true }, "facts_invalidated": { "type": "integer", "title": "Facts Invalidated", "description": "Deprecated alias of `facts_deleted`, same value. The rows are physically deleted, not invalidated.", "deprecated": true }, "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_forgotten", "facts_invalidated", "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." } } } }