{"openapi":"3.1.0","info":{"title":"HelixDB Integration Backend","version":"1.0.0"},"paths":{"/auth/login":{"post":{"tags":["Authentication"],"summary":"Login","operationId":"login_auth_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/refresh":{"post":{"tags":["Authentication"],"summary":"Refresh Token","description":"Rotate a refresh token into a new token pair.\n\nThe new pair reproduces the old identity exactly (org, user, session,\n`act` marker, originating key) — never more. Tokens exchanged from an API\nkey carry its id (`key_id`); that key must still exist, be active and\nbelong to the token's org, otherwise the chain is dead (revocation used\nto be ineffective here because every refresh minted a fresh 7-day token).\nRoles are the token's roles narrowed to the key's CURRENT scopes, so a\nrefresh can drop privileges but never add them.\n\nRefresh tokens without `key_id` (minted before key binding, or by the\nDEBUG-only /auth/login) are refused outside DEBUG: they cannot be tied to\na revocable credential. API-key clients re-exchange on 401.","operationId":"refresh_token_auth_refresh_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/verify":{"get":{"tags":["Authentication"],"summary":"Verify Token","operationId":"verify_token_auth_verify_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/auth/token-exchange":{"post":{"tags":["Authentication"],"summary":"Exchange Api Key","operationId":"exchange_api_key_auth_token_exchange_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenExchangeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/user-hash":{"get":{"tags":["Authentication"],"summary":"Get User Hash","description":"Return server-derived user hash for the effective user in this org.","operationId":"get_user_hash_auth_user_hash_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserHashResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/livez":{"get":{"tags":["Health"],"summary":"Liveness","description":"Liveness: the process is up and serving. Touches no dependency.\n\nThe proxy and container probes use this. Probing ``/health`` instead tied\nthe backend's availability to its slowest dependency: a slow engine made\nthe report outlast the probe timeout and Caddy took the only upstream out\nof rotation, failing every API call while the backend itself was fine.","operationId":"liveness_livez_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"tags":["Health"],"summary":"Health Check","description":"Public readiness status: healthy / degraded / unhealthy, nothing more.\n\nIt is unauthenticated, so it names no internal dependency and carries no\nerror text (QA N6); the per-dependency report is ``/admin/health``.\nDependencies are checked in parallel, each bounded.","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/":{"get":{"tags":["Health"],"summary":"Root","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/helixdb/health":{"get":{"tags":["HelixDB"],"summary":"Helixdb Health","description":"Health check for HelixDB only.\n\nThis intentionally avoids calling IntegrationBackend's `/health` which also\nchecks ingestion/planner (to prevent circular health dependencies).","operationId":"helixdb_health_helixdb_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/helixdb/query":{"post":{"tags":["HelixDB"],"summary":"Execute Query","description":"Execute dynamic HelixQL.\n\nOptional `scope` (\":\") stamps any writes the query performs\n(X-Scope-Id); mutating queries can't be distinguished here, so it is a\npass-through — the engine's own write gate (D-2) is authoritative. Must be\nwithin the caller's visible scopes (403 otherwise).","operationId":"execute_query_helixdb_query_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/helixdb/schema":{"get":{"tags":["HelixDB"],"summary":"Get Schema","operationId":"get_schema_helixdb_schema_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchemaResponse"}}}}},"security":[{"HTTPBearer":[]}]},"put":{"tags":["HelixDB"],"summary":"Update Schema","operationId":"update_schema_helixdb_schema_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSchemaRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/helixdb/introspect":{"get":{"tags":["HelixDB"],"summary":"Introspect Schema","operationId":"introspect_schema_helixdb_introspect_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/schema-json":{"get":{"tags":["HelixDB"],"summary":"Get Schema Json","operationId":"get_schema_json_schema_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/helixdb/etl/bulk":{"post":{"tags":["HelixDB","HelixDB ETL"],"summary":"Bulk Insert","description":"Bulk insert nodes/edges/vectors.\n\nOptional `scope` (\":\") is the write stamp for every inserted\nrecord; must be within the caller's visible scopes (403 otherwise).\nDefaults to user:.","operationId":"bulk_insert_helixdb_etl_bulk_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkInsertRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkInsertResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/helixdb/etl/ingest-kg":{"post":{"tags":["HelixDB","HelixDB ETL"],"summary":"Ingest Knowledge Graph","description":"Knowledge-graph ingestion.\n\nOptional `scope` (\":\") is the write stamp for the ingested\ngraph; must be within the caller's visible scopes (403 otherwise).\nDefaults to user:.","operationId":"ingest_knowledge_graph_helixdb_etl_ingest_kg_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestKGRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestKGResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/helixdb/etl/extract-kg":{"post":{"tags":["HelixDB","HelixDB ETL"],"summary":"Extract Knowledge Graph","description":"Extract and deduplicate knowledge graph from document chunks.\n\nThis is a pass-through to HelixDB's /etl/extract-kg endpoint.\nUseful for extracting entities/relationships without inserting.","operationId":"extract_knowledge_graph_helixdb_etl_extract_kg_post","requestBody":{"content":{"application/json":{"schema":{"type":"object","title":"Request"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/helixdb/etl/infer":{"post":{"tags":["HelixDB","HelixDB ETL"],"summary":"Infer Schema","description":"Infer schema from sample data.\n\nPass sample node/edge objects to get a recommended HelixQL schema.","operationId":"infer_schema_helixdb_etl_infer_post","requestBody":{"content":{"application/json":{"schema":{"type":"object","title":"Request"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/nlq/execute":{"post":{"tags":["NLQ"],"summary":"Nlq Execute","operationId":"nlq_execute_nlq_execute_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NLQExecuteRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NLQExecuteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/ingestion/document":{"post":{"tags":["Ingestion Pipeline"],"summary":"Ingest Document","operationId":"ingest_document_ingestion_document_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentIngestRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentIngestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/ingestion/episode":{"post":{"tags":["Ingestion Pipeline"],"summary":"Ingest Episode","description":"Store a conversation episode as remembered turns (tex.episodes.store).\n\nThe messages go through the SAME path as POST /ingestion/memory\n(conversations.remember): each message is a turn in the active tier\n(recallable at once) and a durable turn node, in one active-memory\nepisode that is later consolidated into an EPISODE_SUMMARY — which is\nwhat GET /episodes lists. It used to be forwarded to the ingestion\nservice's /ingest/episode, which stored it as a document: not recallable\nuntil that job ran, never an episode, never listed.\n\nRequest shape unchanged. Mapping onto turns:\n- ``content`` (or ``text``) -> turn text; ``role`` user/human -> user,\n assistant/ai/agent/bot/model -> assistant, any other role -> an\n assistant turn prefixed with the role (\"[system] ...\");\n- ``timestamp`` -> the turn's capture time (same contract as remember,\n natural language read in ``timezone``, default UTC); omitted -> the\n arrival time, +1 ms per message, so order and identity are kept;\n- the episode is ``episode_id``, else the session id sent, else a new id\n (returned as ``episode_id``);\n- ``scope``: legacy tenant dict or \":\", checked exactly as\n /ingestion/memory checks it.\n``metadata`` and ``options`` (preference extraction etc.) belonged to the\ndocument pipeline and are accepted but not used.","operationId":"ingest_episode_ingestion_episode_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EpisodeIngestRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EpisodeIngestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/ingestion/preference":{"post":{"tags":["Ingestion Pipeline"],"summary":"Ingest Preference","description":"Ingest explicit user preferences via the ingestion pipeline.\n\nOptional `scope` (\":\") is pre-checked against the caller's\nvisible scopes (403 with explanatory body otherwise) and forwarded to the\npipeline as ``write_scope``. The ingestion service stamps it on the\nengine write end to end: PreferenceIngestRequest.write_scope ->\n_process_preference_pipeline -> ingest_knowledge_graph(write_scope=...)\n-> the ``X-Scope-Id`` header of /etl/ingest-kg. Omitted: the default\npersonal stamp (``user:``).","operationId":"ingest_preference_ingestion_preference_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreferenceIngestRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreferenceIngestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/ingestion/status/{job_id}":{"get":{"tags":["Ingestion Pipeline"],"summary":"Get Job Status","operationId":"get_job_status_ingestion_status__job_id__get","security":[{"HTTPBearer":[]}],"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/JobStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/ingestion/jobs":{"get":{"tags":["Ingestion Pipeline"],"summary":"List Jobs","operationId":"list_jobs_ingestion_jobs_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id"}},{"name":"user_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"job_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Type"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/ingestion/batch":{"post":{"tags":["Ingestion Pipeline"],"summary":"Batch Ingest","description":"Batch ingest multiple documents (1–600) in a single request.\n\nEach document is submitted to the ingestion pipeline independently.\nReturns a batch_id and a list of job_ids for polling.","operationId":"batch_ingest_ingestion_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchIngestRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchIngestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/planner/plan":{"post":{"tags":["HelixQL Planner"],"summary":"Generate Query Plan","operationId":"generate_query_plan_planner_plan_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryPlanRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryPlanResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/planner/stats":{"get":{"tags":["HelixQL Planner"],"summary":"Get Planner Stats","operationId":"get_planner_stats_planner_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/search":{"post":{"tags":["Search"],"summary":"Semantic Search","description":"Semantic vector search over stored memories.\n\nEmbeds the query text, runs HNSW nearest-neighbour search, and returns\nranked text chunks with similarity scores. No planner LLM call.\n\nScoped to the current tenant (org_id + user_id).","operationId":"semantic_search_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/memories/episodes":{"get":{"tags":["Memories"],"summary":"List Episodes","description":"List the caller's consolidated conversation episodes.\n\nAn episode is its CURRENT ``EPISODE_SUMMARY`` (one per consolidated\nepisode window; superseded versions are skipped). Raw ``EPISODE_EVENT``\nnodes are turns, not episodes, and are never listed here (paging past the\nsummaries used to fall through to them). Episodes still in the active\ntier (not yet consolidated) are not listed yet. POST /ingestion/episode\n(episodes.store) stores its messages as remembered turns, so a stored\nepisode is listed here once it is consolidated.\n\nCost and ordering: one request is ONE engine page of ``limit`` summaries\nat ``offset`` — never a walk of the tenant's data (GET /nodes scans the\nshard per call). The engine can neither order nor filter by time, so\nresults come in engine order, and ``since`` filters WITHIN the page: a\npage may hold fewer than ``limit`` episodes while ``has_more`` (the\nengine returned a full page) is still true. Keep paging until\n``has_more`` is false. Global newest-first ordering and an engine-side\n``since`` need an engine query (label + owner + time range, sorted) —\nsee the Package D report.","operationId":"list_episodes_memories_episodes_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only episodes that ended at or after this time: ISO 8601 (e.g. 2026-01-01T09:30:00Z) or epoch seconds/milliseconds","title":"Since"},"description":"Only episodes that ended at or after this time: ISO 8601 (e.g. 2026-01-01T09:30:00Z) or epoch seconds/milliseconds"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EpisodeListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/memories/{memory_id}":{"get":{"tags":["Memories"],"summary":"Get Memory","description":"Retrieve a stored memory by its UUID.\n\nReturns the full memory object including content, type, metadata, and timestamps.","operationId":"get_memory_memories__memory_id__get","security":[{"HTTPBearer":[]}],"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/MemoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Memories"],"summary":"Delete Memory","description":"Delete a memory by id, from every store it lives in.\n\nGoes through the single deletion path (``deletion.delete_memory``): the\nactive-tier copy, the engine node and the vectors that name it, the\ncopies consolidation made of it, the deleted-memories ledger and its edit\nhistory. This route used to tombstone only the engine node, so the\nactive copy kept answering recall and consolidation could write the text\nback. Tombstones are hidden from every read path; bytes are reclaimed by\nthe sleep cycle, not here.","operationId":"delete_memory_memories__memory_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"memory_id","in":"path","required":true,"schema":{"type":"string","title":"Memory Id"}},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Accepted for compatibility: \":\", must be within the caller's visible scopes. The delete is made in the memory's own scope, read from the memory itself.","title":"Scope"},"description":"Accepted for compatibility: \":\", must be within the caller's visible scopes. The delete is made in the memory's own scope, read from the memory itself."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryDeleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["Memories"],"summary":"Update Memory","description":"Update a memory's content and/or metadata.\n\nIf content is changed, the HNSW vector is re-embedded automatically.\nMetadata is merged (not replaced) — only specified keys are updated.\n\nOptional `scope` (\":\") stamps the write; must be within the\ncaller's visible scopes (403 otherwise). Defaults to user:.","operationId":"update_memory_memories__memory_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"memory_id","in":"path","required":true,"schema":{"type":"string","title":"Memory Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/memories":{"get":{"tags":["Memories"],"summary":"List Memories","description":"List stored memories with pagination and optional type/label filters.\n\nScoped to the current tenant.","operationId":"list_memories_memories_get","security":[{"HTTPBearer":[]}],"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"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by type: document, episode, preference","title":"Type"},"description":"Filter by type: document, episode, preference"},{"name":"label","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by graph label","title":"Label"},"description":"Filter by graph label"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Memories"],"summary":"Delete Memories Bulk","description":"Erase a user's personal memories (GDPR/CCPA erasure) from every store.\n\nThe same erasure as the deletion API's ``user_scope`` target, and audited\nthe same way (a deletion request + receipt, purged after the retention\nwindow): every node in the user's personal scope (and their unstamped\nlegacy nodes), the vectors stamped with it in every namespace, their\npersonal active-tier fragments, turn index rows and edit history. This\nroute used to tombstone engine nodes only — the active copies kept\nanswering recall and inferences kept answering NLQ — and answered 500 on\nthe first node it could see but not delete. ``deleted_count`` is engine\nnodes tombstoned.","operationId":"delete_memories_bulk_memories_delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Target user_id to erase. If omitted, deletes the caller's own memories. Only admin/developer may erase other users.","title":"User Id"},"description":"Target user_id to erase. If omitted, deletes the caller's own memories. Only admin/developer may erase other users."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryBulkDeleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/users/profile":{"get":{"tags":["Users"],"summary":"Get User Profile","description":"Get the current user's synthesized profile.\n\nReturns a human-readable string suitable for LLM system-prompt injection,\nbuilt from stored preferences and recent episode summaries.\n\nv1 uses rule-based concatenation (no LLM call).","operationId":"get_user_profile_users_profile_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Profile format: text or json","default":"text","title":"Format"},"description":"Profile format: text or json"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfileResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/active-memory/ingest":{"post":{"tags":["active-memory"],"summary":"Ingest a memory fragment into the active episodic store","description":"Embed `body.text` and write the vector + text to the Cloudflare Active Memory\nWorker (KV for text, Durable Object for vector).\n\nThe fragment is keyed by `fragment_id` (idempotent upsert).\nIf `fragment_id` is not provided, a deterministic UUID is generated from\n(org_id, episode_id, text) so duplicate POSTs with the same text are idempotent.","operationId":"ingest_fragment_active_memory_ingest_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActiveFragmentIngestRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActiveFragmentIngestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/active-memory/retrieve":{"post":{"tags":["active-memory"],"summary":"Retrieve semantically similar fragments from active memory","description":"Embed `body.query_text`, then query the Cloudflare Worker for the top-k most\nsimilar fragments. The Worker performs cosine similarity over the Durable\nObject's SQLite vector store and hydrates fragment texts from Workers KV.\n\nIf `episode_id` is omitted, all open episodes for `agent_id` are searched.","operationId":"retrieve_active_active_memory_retrieve_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActiveEpisodeRetrieveRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActiveEpisodeRetrieveResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/active-memory/close-episode":{"post":{"tags":["active-memory"],"summary":"Explicitly close an active episode (triggers consolidation)","description":"Mark the episode as closed in the Durable Object.\n\nThe Worker's DO alarm handler will pick up the closed episode on the next\ndecay check and enqueue it for consolidation. Alternatively, the caller\ncan pass `reason=\"explicit\"` to signal an intentional close vs. timeout.","operationId":"close_episode_active_memory_close_episode_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloseActiveEpisodeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Close Episode Active Memory Close Episode Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/active-memory/ingest-batch":{"post":{"tags":["active-memory"],"summary":"Ingest Fragment Batch","description":"Batch-ingest: embed all texts in one API call, push to worker concurrently.","operationId":"ingest_fragment_batch_active_memory_ingest_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/_BatchIngestRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/_BatchIngestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/memory/retrieve":{"post":{"tags":["memory"],"summary":"Unified episodic memory retrieval — routes across active and passive tiers","description":"Embed ``body.query_text``, consult the Episode Registry, then query the\nappropriate backends in parallel:\n\n* **ACTIVE episodes** → ``POST /retrieve/active`` on the Cloudflare Worker.\n Returns per-fragment cosine hits + KV-hydrated text. Hits receive a\n +0.15 recency boost before ranking.\n\n* **PASSIVE episodes** → HelixDB ``EPISODE_SUMMARY`` nodes (GET /nodes, on\n the caller's scoped token), ranked by cosine similarity. Scored as-is.\n\nResults from both tiers are merged, sorted by final score descending, and\nthe top ``body.top_k`` hits are returned with a ``source`` annotation.\n\nEach tier is queried independently — a failure in one tier surfaces as a\nwarning log and the other tier's results are still returned.","operationId":"retrieve_unified_memory_retrieve_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryRetrieveRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryRetrieveResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/ingestion/memory":{"post":{"tags":["ingestion-memory"],"summary":"Unified dual-write ingest (active memory + HelixDB)","description":"Fan a list of conversational turns out to active memory + HelixDB.\n\n``scope`` accepts BOTH shapes (shared contract with the SDK):\n- legacy tenant dict {org_id, user_id, session_id} -> unchanged behavior;\n- hierarchical write-scope string \":\" -> validated against\n the caller's visible scopes (403 with explanatory body otherwise) and\n stamped on every HelixDB write (X-Scope-Id). org/user then come from\n the auth context; the session is the body's top-level session_id when\n given (the SDK sends it alongside a string scope), else the auth\n context's, else \"default-session\".","operationId":"post_ingestion_memory_ingestion_memory_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestMemoryRequest"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestMemoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/ingestion/memory/turns/{turn_id}":{"delete":{"tags":["ingestion-memory"],"summary":"Retire one remembered turn from both tiers","description":"Retire a single turn written by ``POST /ingestion/memory``.\n\n``turn_id`` is a ``turn_ids`` entry from the write that created it — the\nturn's content hash, from which its engine node id is derived. It is NOT\nthe active fragment id: that one is\n``sha256(scope|turn_id)`` and one-way, so only this direction works.\n\nBefore this route existed, the finest thing a caller could delete on this\npath was an entire scope or user: ``remember`` had no counterpart, and\nhanding a Turn node to the deletion service tombstoned the engine node\nwhile reporting the active tier ``not_located`` — the tier default recall\nactually reads. So a \"deleted\" turn kept being recalled.\n\nBoth tiers go through the ordinary deletion service, which means this gets\nthe same audit row (``deletion_requests``), the same soft/purge replay and\nthe same honest per-tier receipt as every other deletion. Soft mode only:\nerasing the bytes is a platform-admin purge, unchanged.","operationId":"forget_remembered_turn_ingestion_memory_turns__turn_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"turn_id","in":"path","required":true,"schema":{"type":"string","title":"Turn Id"}},{"name":"reason","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1024},{"type":"null"}],"title":"Reason"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForgetTurnResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/recall":{"post":{"tags":["recall"],"summary":"Verb-shaped agent retrieval — active or deep mode","operationId":"post_recall_recall_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecallRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecallResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/usage/today":{"get":{"tags":["usage"],"summary":"Get Today Usage","description":"Today's usage for the caller's org plus the active daily quota.\n\nThe dashboard 'projection' chart is built from this.","operationId":"get_today_usage_usage_today_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageQuotaStatus"}}}}},"security":[{"HTTPBearer":[]}]}},"/usage/summary":{"get":{"tags":["usage"],"summary":"Get Month Summary","description":"Calendar-month rollup of tokens_in / tokens_out for the caller's org.","operationId":"get_month_summary_usage_summary_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"month","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}$"},{"type":"null"}],"description":"YYYY-MM (UTC). Defaults to current calendar month.","title":"Month"},"description":"YYYY-MM (UTC). Defaults to current calendar month."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageWindow"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/signup":{"post":{"tags":["self-service"],"summary":"Create a fresh org and first API key (developer self-service)","description":"Open endpoint: anyone can create an org and get an API key.\n\nFor launch we keep this unauthenticated and unverified — abuse mitigation\nis via the per-org daily token quota (one bad actor only burns their own\nfree-tier budget). Email verification + GitHub OAuth come with the\ndashboard.","operationId":"signup_signup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/me":{"get":{"tags":["self-service"],"summary":"Current org + key summary","operationId":"get_me_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/me/api-keys":{"get":{"tags":["self-service"],"summary":"List this org's API keys (no plaintext)","operationId":"list_api_keys_me_api_keys_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"include_revoked","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Revoked"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/APIKeyOut"},"title":"Response List Api Keys Me Api Keys Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["self-service"],"summary":"Mint a new API key for this org (plaintext shown once)","operationId":"create_api_key_me_api_keys_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyMinted"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/me/api-keys/{key_id}":{"delete":{"tags":["self-service"],"summary":"Revoke an API key (cannot be undone)","operationId":"revoke_api_key_me_api_keys__key_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/me/settings":{"get":{"tags":["self-service"],"summary":"This org's settings","operationId":"get_org_settings_me_settings_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgSettingsOut"}}}}},"security":[{"HTTPBearer":[]}]},"patch":{"tags":["self-service"],"summary":"Update this org's settings","operationId":"patch_org_settings_me_settings_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgSettingsPatch"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgSettingsOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/me/deletions":{"post":{"tags":["deletion"],"summary":"Request a soft deletion of this org's data","operationId":"create_my_deletion_me_deletions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletionRequestIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/me/deletions/{request_id}":{"get":{"tags":["deletion"],"summary":"Fetch one deletion receipt","operationId":"get_my_deletion_me_deletions__request_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/me/scope-memberships":{"post":{"tags":["scope-membership"],"summary":"Grant a scope membership inside your own org (idempotent)","description":"Grant a team:/project: scope to a user in your organization. The org comes from the token. Idempotent: replaying an existing grant returns 200, and a different role on replay updates the stored role. The grant applies from that user's next request.","operationId":"grant_my_scope_membership_me_scope_memberships_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopeMembershipGrant"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopeMembershipMutationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["scope-membership"],"summary":"List your org's scope-membership grants","description":"List the explicit grants in your organization, optionally filtered by user and/or scope. Implicit user:/org: scopes are not rows and are not listed.","operationId":"list_my_scope_memberships_me_scope_memberships_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"user_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"}},{"name":"scope_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopeMembershipListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["scope-membership"],"summary":"Revoke a scope membership inside your own org","description":"Remove one grant from your organization. 404 when there is no such grant. The user's read-set narrows from their next request.","operationId":"revoke_my_scope_membership_me_scope_memberships_delete","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopeMembershipTarget"}}}},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"APIKeyCreateRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Name","description":"Human-readable label for the key"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"}},"type":"object","title":"APIKeyCreateRequest"},"APIKeyMinted":{"properties":{"key":{"$ref":"#/components/schemas/APIKeyOut"},"api_key":{"type":"string","title":"Api Key","description":"Full plaintext key — store this securely; shown once."}},"type":"object","required":["key","api_key"],"title":"APIKeyMinted","description":"Returned exactly once on creation. Includes the plaintext key."},"APIKeyOut":{"properties":{"id":{"type":"string","title":"Id"},"prefix":{"type":"string","title":"Prefix","description":"Literal prefix string, e.g. tex_live_"},"display_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Id","description":"First 8 random chars of the key body, for visual id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revoked At"}},"type":"object","required":["id","prefix","is_active","created_at"],"title":"APIKeyOut","description":"Public view of an API key. Never includes plaintext."},"ActiveEpisodeRetrieveRequest":{"properties":{"agent_id":{"type":"string","maxLength":256,"minLength":1,"title":"Agent Id","description":"Agent identifier"},"user_hash":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"User Hash","description":"Hashed user ID. If omitted, backend derives it from authenticated org_id + effective user scope."},"episode_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Episode Id","description":"Scope search to one episode; None = all open episodes for agent"},"scope_user_id":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"Scope User Id","description":"Optional effective user_id for agent/service tokens. If provided, user_hash must match server-derived hash for this user."},"query_text":{"type":"string","maxLength":4096,"minLength":1,"title":"Query Text","description":"Text to embed and search"},"top_k":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Top K","description":"Max hits to return","default":10},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope","description":"Optional scope \":\" to narrow the read to. Must be in the caller's visible scopes (403 otherwise); omitted = every visible scope."}},"type":"object","required":["agent_id","query_text"],"title":"ActiveEpisodeRetrieveRequest","description":"Retrieve semantically similar fragments from the active memory store."},"ActiveEpisodeRetrieveResponse":{"properties":{"hits":{"items":{"$ref":"#/components/schemas/ActiveRetrievalHitResponse"},"type":"array","title":"Hits"},"total_scanned":{"type":"integer","title":"Total Scanned"},"active_episodes_searched":{"type":"integer","title":"Active Episodes Searched"}},"type":"object","required":["total_scanned","active_episodes_searched"],"title":"ActiveEpisodeRetrieveResponse"},"ActiveFragmentIngestRequest":{"properties":{"agent_id":{"type":"string","maxLength":256,"minLength":1,"title":"Agent Id","description":"Agent identifier"},"user_hash":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"User Hash","description":"Hashed user ID (never raw PII). If omitted, backend derives it from authenticated org_id + user_id."},"episode_id":{"type":"string","maxLength":256,"minLength":1,"title":"Episode Id","description":"Logical episode/conversation ID"},"fragment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fragment Id","description":"Idempotency key; auto-generated UUID if omitted"},"text":{"type":"string","maxLength":4096,"minLength":1,"title":"Text","description":"Raw fragment text (1–4096 chars, not blank)"},"entities":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Entities","description":"Extracted entity strings"},"skip_enrichment":{"type":"boolean","title":"Skip Enrichment","description":"Skip LLM enrichment (entities/inference) for benchmark throughput runs","default":false},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms","description":"Fragment timestamp (ms since epoch); server time if omitted"},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata","description":"Opaque metadata forwarded to the vector store"},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope","description":"Optional explicit write scope \":\" (kinds: user/team/org/project). Must be within the caller's visible scopes; defaults to user:."},"inactivity_timeout_seconds":{"anyOf":[{"type":"integer","maximum":86400.0,"minimum":300.0},{"type":"null"}],"title":"Inactivity Timeout Seconds","description":"Idle time in seconds after which this active-memory episode is closed and consolidated into long-term memory. Stored on the episode (later writes without it keep it). Omitted: the org default, else 1800 (30 min). Bounds: 300-86400."}},"type":"object","required":["agent_id","episode_id","text"],"title":"ActiveFragmentIngestRequest","description":"Ingest a single memory fragment into the active (short-term) episodic store."},"ActiveFragmentIngestResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"fragment_id":{"type":"string","title":"Fragment Id"},"episode_id":{"type":"string","title":"Episode Id"}},"type":"object","required":["ok","fragment_id","episode_id"],"title":"ActiveFragmentIngestResponse"},"ActiveRetrievalHitResponse":{"properties":{"fragment_id":{"type":"string","title":"Fragment Id"},"score":{"type":"number","title":"Score"},"text":{"type":"string","title":"Text"},"timestamp_ms":{"type":"integer","title":"Timestamp Ms"},"entities":{"items":{"type":"string"},"type":"array","title":"Entities"},"agent_id":{"type":"string","title":"Agent Id"},"episode_id":{"type":"string","title":"Episode Id"},"scope_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope Id","description":"Scope stamp of the fragment"},"kind":{"type":"string","enum":["turn","observation"],"title":"Kind","description":"Fragment kind (\"turn\" when the worker does not report one)","default":"turn"},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","required":["fragment_id","score","text","timestamp_ms","agent_id","episode_id"],"title":"ActiveRetrievalHitResponse"},"AgentBinding":{"properties":{"label":{"type":"string","title":"Label","description":"Node label"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id","description":"Canonical ID"},"entity_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Name","description":"Entity name"}},"type":"object","required":["label"],"title":"AgentBinding","description":"Agent-friendly binding for intent matching result."},"BatchDocumentItem":{"properties":{"data":{"type":"string","minLength":1,"title":"Data","description":"Document text content"},"format":{"type":"string","title":"Format","description":"Content format: text, markdown, html","default":"text"},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata","description":"Document metadata"}},"type":"object","required":["data"],"title":"BatchDocumentItem","description":"A single document in a batch ingestion request."},"BatchIngestRequest":{"properties":{"documents":{"items":{"$ref":"#/components/schemas/BatchDocumentItem"},"type":"array","maxItems":600,"minItems":1,"title":"Documents","description":"Documents to ingest"},"options":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Options","description":"Ingestion options"}},"type":"object","required":["documents"],"title":"BatchIngestRequest","description":"Batch document ingestion request."},"BatchIngestResponse":{"properties":{"batch_id":{"type":"string","title":"Batch Id","description":"Batch tracking ID"},"jobs":{"items":{"type":"object"},"type":"array","title":"Jobs","description":"Per-document job info"},"total":{"type":"integer","title":"Total","description":"Total documents submitted","default":0}},"type":"object","required":["batch_id"],"title":"BatchIngestResponse","description":"Response from batch ingestion."},"BulkInsertRequest":{"properties":{"nodes":{"items":{"$ref":"#/components/schemas/NodeInsert"},"type":"array","title":"Nodes","description":"Nodes to insert"},"edges":{"items":{"$ref":"#/components/schemas/EdgeInsert"},"type":"array","title":"Edges","description":"Edges to insert"},"vectors":{"items":{"$ref":"#/components/schemas/VectorInsert"},"type":"array","title":"Vectors","description":"Vectors to insert"},"options":{"type":"object","title":"Options","description":"Insertion options"},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope","description":"Optional explicit write scope \":\" (kinds: user/team/org/project). Must be within the caller's visible scopes; defaults to user:."}},"type":"object","title":"BulkInsertRequest","description":"Bulk insert request."},"BulkInsertResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether insertion succeeded"},"nodes_inserted":{"type":"integer","title":"Nodes Inserted","description":"Number of nodes inserted","default":0},"edges_inserted":{"type":"integer","title":"Edges Inserted","description":"Number of edges inserted","default":0},"vectors_inserted":{"type":"integer","title":"Vectors Inserted","description":"Number of vectors inserted","default":0},"errors":{"items":{"type":"string"},"type":"array","title":"Errors","description":"Error messages"}},"type":"object","required":["success"],"title":"BulkInsertResponse","description":"Bulk insert response."},"CSPConfig":{"properties":{"use_csp":{"type":"boolean","title":"Use Csp","description":"Enable CSP-based matching with domain propagation","default":false},"vector_k":{"type":"integer","exclusiveMinimum":0.0,"title":"Vector K","description":"Results to fetch from vector search per constrained variable","default":10},"vector_k_multiplier":{"type":"integer","exclusiveMinimum":0.0,"title":"Vector K Multiplier","description":"Over-fetch multiplier for vector+fuzzy fusion","default":2},"propagation_budget_ms":{"type":"integer","exclusiveMinimum":0.0,"title":"Propagation Budget Ms","description":"Time budget for CSP propagation phase","default":100},"max_propagation_rounds":{"type":"integer","exclusiveMinimum":0.0,"title":"Max Propagation Rounds","description":"Maximum propagation rounds","default":50},"max_widening_attempts":{"type":"integer","minimum":0.0,"title":"Max Widening Attempts","description":"Maximum adaptive widening attempts","default":3},"widening_min_time_ms":{"type":"integer","exclusiveMinimum":0.0,"title":"Widening Min Time Ms","description":"Minimum remaining time to attempt widening","default":100},"include_diagnostics":{"type":"boolean","title":"Include Diagnostics","description":"Include detailed domain diagnostics in response","default":false},"edge_first":{"type":"boolean","title":"Edge First","description":"Enable edge-first CSP propagation (alias-aware, scan-budgeted)","default":false},"allow_path_recovery":{"type":"boolean","title":"Allow Path Recovery","description":"Allow bounded length-2 path recovery when direct edge support is absent","default":false}},"type":"object","title":"CSPConfig","description":"CSP (Constraint Satisfaction Problem) configuration for advanced matching."},"ChatMessage":{"properties":{"role":{"type":"string","title":"Role","description":"Message role"},"content":{"type":"string","maxLength":65536,"minLength":1,"title":"Content","description":"Message content (alias: text)"},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timestamp","description":"Message time: ISO 8601 (e.g. 2026-01-01T09:30:00Z) or epoch seconds/milliseconds, or natural language; default the arrival time"},"metadata":{"type":"object","title":"Metadata","description":"Message metadata (not stored)"}},"type":"object","required":["role","content"],"title":"ChatMessage","description":"Chat message."},"ChunkMetadata":{"properties":{"entities":{"$ref":"#/components/schemas/EntityMetadata","description":"Entity metadata"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename","description":"Source filename"},"filetype":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filetype","description":"File type"},"page_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Number","description":"Page number"}},"type":"object","required":["entities"],"title":"ChunkMetadata","description":"Document chunk metadata."},"CloseActiveEpisodeRequest":{"properties":{"agent_id":{"type":"string","maxLength":256,"minLength":1,"title":"Agent Id"},"user_hash":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"User Hash","description":"Hashed user ID. If omitted, backend derives it from authenticated org_id + effective user scope."},"scope_user_id":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"Scope User Id","description":"Optional effective user_id for agent/service tokens. If provided, user_hash must match server-derived hash for this user."},"episode_id":{"type":"string","maxLength":256,"minLength":1,"title":"Episode Id"},"reason":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Reason"}},"type":"object","required":["agent_id","episode_id"],"title":"CloseActiveEpisodeRequest"},"ConstraintFuzzyConfig":{"properties":{"constraint_candidates_k":{"type":"integer","exclusiveMinimum":0.0,"title":"Constraint Candidates K","description":"Top-K candidates per constrained variable"},"constraint_min_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Constraint Min Score","description":"Minimum weighted similarity score"},"w_jaro_winkler":{"type":"number","minimum":0.0,"title":"W Jaro Winkler","description":"Weight for Jaro-Winkler similarity"},"w_jaro":{"type":"number","minimum":0.0,"title":"W Jaro","description":"Weight for Jaro similarity"},"w_levenshtein":{"type":"number","minimum":0.0,"title":"W Levenshtein","description":"Weight for normalized Levenshtein similarity"},"w_contains":{"type":"number","minimum":0.0,"title":"W Contains","description":"Weight for containment (substring) similarity"},"vector_min_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Vector Min Score","description":"Cosine floor for vector-resolved constraints (below it the entity is not the constraint's referent)"},"vector_margin":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Vector Margin","description":"Keep only vector candidates within this distance of the best one"}},"type":"object","required":["constraint_candidates_k","constraint_min_score","w_jaro_winkler","w_jaro","w_levenshtein","w_contains"],"title":"ConstraintFuzzyConfig","description":"Request-provided fuzzy constraint configuration (no client defaults)."},"DeletionRequestIn":{"properties":{"target":{"$ref":"#/components/schemas/DeletionTargetIn"},"reason":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Reason"},"idempotency_key":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Idempotency Key","description":"Replaying the same key returns the first receipt instead of re-running"},"mode":{"type":"string","title":"Mode","description":"soft (default) | purge (platform admin only)","default":"soft"}},"type":"object","required":["target"],"title":"DeletionRequestIn"},"DeletionTargetIn":{"properties":{"kind":{"type":"string","title":"Kind","description":"memory (one node id) | user_scope (a user's personal scope) | scope (a canonical ':' scope id) | user (full removal of a user within the org)"},"value":{"type":"string","maxLength":512,"minLength":1,"title":"Value"},"owner_user_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Owner User Id","description":"REQUIRED for kind=memory: the user whose memory this is (its engine node and active-tier fragment are owned by that user). Ignored otherwise."}},"type":"object","required":["kind","value"],"title":"DeletionTargetIn"},"DocumentChunk":{"properties":{"element_id":{"type":"string","title":"Element Id","description":"Unique element identifier"},"text":{"type":"string","title":"Text","description":"Chunk text content"},"metadata":{"$ref":"#/components/schemas/ChunkMetadata","description":"Chunk metadata"}},"type":"object","required":["element_id","text","metadata"],"title":"DocumentChunk","description":"Document chunk for knowledge graph ingestion."},"DocumentIngestRequest":{"properties":{"data":{"type":"string","minLength":1,"title":"Data","description":"Document content"},"format":{"type":"string","title":"Format","description":"Content format","default":"text"},"scope":{"$ref":"#/components/schemas/Scope","description":"Hierarchical scope"},"metadata":{"anyOf":[{"$ref":"#/components/schemas/DocumentMetadata"},{"type":"null"}],"description":"Document metadata"},"options":{"anyOf":[{"$ref":"#/components/schemas/IngestionOptions"},{"type":"null"}],"description":"Ingestion options"}},"type":"object","required":["data","scope"],"title":"DocumentIngestRequest","description":"Document ingestion request."},"DocumentIngestResponse":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"Job identifier"},"document_id":{"type":"string","title":"Document Id","description":"Document identifier"},"status":{"type":"string","title":"Status","description":"Job status"},"estimated_time":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Estimated Time","description":"Estimated time in seconds"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Status message"}},"type":"object","required":["job_id","document_id","status"],"title":"DocumentIngestResponse","description":"Document ingestion response."},"DocumentMetadata":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Document title"},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"Document author"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Document source","default":"api"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Timestamp","description":"Document timestamp"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Tags"},"custom":{"type":"object","title":"Custom","description":"Custom metadata"}},"type":"object","title":"DocumentMetadata","description":"Document metadata."},"EdgeInsert":{"properties":{"label":{"type":"string","title":"Label","description":"Edge type/label"},"from":{"type":"string","title":"From","description":"Source node UUID"},"to":{"type":"string","title":"To","description":"Target node UUID"},"properties":{"type":"object","title":"Properties","description":"Edge properties"}},"type":"object","required":["label","from","to"],"title":"EdgeInsert","description":"Edge insertion model."},"EntityItem":{"properties":{"entity":{"type":"string","title":"Entity","description":"Entity name"},"type":{"type":"string","title":"Type","description":"Entity type"},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases","description":"Entity aliases"},"confidence":{"type":"string","title":"Confidence","description":"Confidence level"},"context":{"type":"string","title":"Context","description":"Entity context"}},"type":"object","required":["entity","type","confidence","context"],"title":"EntityItem","description":"Entity item from knowledge graph."},"EntityMetadata":{"properties":{"items":{"items":{"$ref":"#/components/schemas/EntityItem"},"type":"array","title":"Items","description":"Entities"},"relationships":{"items":{"$ref":"#/components/schemas/RelationshipItem"},"type":"array","title":"Relationships","description":"Relationships"},"inferred":{"items":{"type":"string"},"type":"array","title":"Inferred","description":"Inferred statements"}},"type":"object","title":"EntityMetadata","description":"Entity metadata."},"EpisodeIngestRequest":{"properties":{"episode_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Episode Id","description":"Episode identifier"},"messages":{"items":{"$ref":"#/components/schemas/ChatMessage"},"type":"array","maxItems":2000,"minItems":1,"title":"Messages","description":"Chat messages"},"scope":{"anyOf":[{"type":"string"},{"$ref":"#/components/schemas/Scope"}],"title":"Scope","description":"Tenant scope dict (legacy) OR hierarchical write-scope string \":\" (org/user then come from the auth context)"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Explicit session id, honored on the string-scope path (the SDK sends it alongside a string scope; the legacy dict carries its own)"},"metadata":{"anyOf":[{"$ref":"#/components/schemas/EpisodeMetadata"},{"type":"null"}],"description":"Episode metadata"},"options":{"anyOf":[{"$ref":"#/components/schemas/EpisodeOptions"},{"type":"null"}],"description":"Episode options"},"timezone":{"anyOf":[{"type":"string","maxLength":64,"description":"The caller's timezone (IANA name, e.g. Europe/Berlin, or +HH:MM) for natural-language turn timestamps such as \"yesterday 3pm\"; default UTC"},{"type":"null"}],"title":"Timezone"}},"type":"object","required":["messages","scope"],"title":"EpisodeIngestRequest","description":"Episode ingestion request."},"EpisodeIngestResponse":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"Per-call observability id (there is no background job)"},"episode_id":{"type":"string","title":"Episode Id","description":"The episode the messages were stored in: the request's episode_id, else its session id, else a new id. Store more messages under it to continue the episode."},"status":{"type":"string","title":"Status","description":"\"stored\": every message is recallable now"},"preferences_detected":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Preferences Detected","description":"Not computed (always null); kept for compatibility"},"estimated_time":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Estimated Time","description":"Not used (always null); kept for compatibility"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"What happened, in words"},"turn_ids":{"items":{"type":"string"},"type":"array","title":"Turn Ids","description":"Turn id of each stored message part; retire one with DELETE /ingestion/memory/turns/{turn_id}"},"active_fragment_ids":{"items":{"type":"string"},"type":"array","title":"Active Fragment Ids","description":"Active-tier fragment ids written"},"turn_times":{"items":{"$ref":"#/components/schemas/TurnTime"},"type":"array","title":"Turn Times","description":"Each message's resolved capture time"},"not_stored_forgotten":{"items":{"type":"string"},"type":"array","title":"Not Stored Forgotten","description":"turn_ids not stored because their owner had forgotten them"},"usage":{"anyOf":[{"$ref":"#/components/schemas/Usage"},{"type":"null"}],"description":"Tokens billed for this call"}},"type":"object","required":["job_id","episode_id","status"],"title":"EpisodeIngestResponse","description":"Episode ingestion response.\n\nAn episode is stored as remembered turns (POST /ingestion/memory), so the\nturn fields below are the same as ``IngestMemoryResponse``'s."},"EpisodeListResponse":{"properties":{"episodes":{"items":{"type":"object"},"type":"array","title":"Episodes"},"count":{"type":"integer","title":"Count","description":"Number of episodes returned","default":0},"next_offset":{"type":"integer","title":"Next Offset","description":"Offset for next page","default":0},"has_more":{"type":"boolean","title":"Has More","description":"Whether a further page exists","default":false}},"type":"object","title":"EpisodeListResponse","description":"Paginated list of conversation episodes."},"EpisodeMetadata":{"properties":{"agent_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Name","description":"Agent name"},"episode_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Episode Type","description":"Episode type"},"topics":{"items":{"type":"string"},"type":"array","title":"Topics","description":"Topics"},"custom":{"type":"object","title":"Custom","description":"Custom metadata"}},"type":"object","title":"EpisodeMetadata","description":"Episode metadata."},"EpisodeOptions":{"properties":{"extract_preferences":{"type":"boolean","title":"Extract Preferences","description":"Extract preferences","default":true},"temporal_tracking":{"type":"boolean","title":"Temporal Tracking","description":"Temporal tracking","default":true},"auto_create_schema":{"type":"boolean","title":"Auto Create Schema","description":"Auto-create schema","default":true},"generate_embeddings":{"type":"boolean","title":"Generate Embeddings","description":"Generate embeddings","default":true}},"type":"object","title":"EpisodeOptions","description":"Episode processing options."},"EvidenceItem":{"properties":{"kind":{"type":"string","title":"Kind","description":"Evidence kind (context/inference/edge_context)"},"text":{"type":"string","title":"Text","description":"Evidence text"}},"type":"object","required":["kind","text"],"title":"EvidenceItem","description":"Evidence item for intent match."},"ForgetTurnResponse":{"properties":{"turn_id":{"type":"string","title":"Turn Id","description":"The retired turn's id (as returned in turn_ids)"},"forgotten":{"type":"boolean","title":"Forgotten","description":"True only when no copy of the turn is still served: every stored item of it (split parts, observations, every scope) retired in both tiers, and no consolidated copy left. False means it may still answer recall somewhere — read residue, errors and the tier fields."},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id","description":"Audit row id in deletion_requests (GET /deletions/{id})"},"durable_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Durable Tier","description":"Per-tier outcome for HelixDB: ok | partial | error | not_found"},"active_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Active Tier","description":"Per-tier outcome for active memory: ok | skipped | not_located | error"},"active_tier_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Active Tier Note","description":"Why the active tier is not 'ok', when it is not"},"items_retired":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Items Retired","description":"Stored items of the turn this covered (parts + observations)"},"residue":{"items":{"type":"string"},"type":"array","title":"Residue","description":"Copies of the turn's text this does not remove: 'document_chunks' and 'knowledge_graph' once the turn has been consolidated (its episode summary IS rewritten without it). Deep recall can still return them."},"residue_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Residue Note"},"errors":{"items":{"type":"string"},"type":"array","title":"Errors","description":"What failed; the call is safe to repeat"}},"type":"object","required":["turn_id","forgotten"],"title":"ForgetTurnResponse","description":"Response for DELETE /ingestion/memory/turns/{turn_id}."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Overall status (healthy, degraded, unhealthy)"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"Check timestamp"},"version":{"type":"string","title":"Version","description":"API version","default":"1.0.0"},"services":{"items":{"$ref":"#/components/schemas/ServiceHealth"},"type":"array","title":"Services","description":"Service statuses"}},"type":"object","required":["status"],"title":"HealthResponse","description":"Overall system health response."},"InactivityBounds":{"properties":{"min_seconds":{"type":"integer","title":"Min Seconds","default":300},"max_seconds":{"type":"integer","title":"Max Seconds","default":86400}},"type":"object","title":"InactivityBounds"},"IngestKGOptions":{"properties":{"auto_create_schema":{"type":"boolean","title":"Auto Create Schema","description":"Auto-create schema","default":true},"generate_embeddings":{"type":"boolean","title":"Generate Embeddings","description":"Generate embeddings","default":true},"validate":{"type":"boolean","title":"Validate","description":"Validate entities","default":false},"store_chunks":{"type":"boolean","title":"Store Chunks","description":"Store original chunks","default":false}},"type":"object","title":"IngestKGOptions","description":"Knowledge graph ingestion options."},"IngestKGRequest":{"properties":{"chunks":{"items":{"$ref":"#/components/schemas/DocumentChunk"},"type":"array","title":"Chunks","description":"Document chunks"},"options":{"$ref":"#/components/schemas/IngestKGOptions","description":"Ingestion options"},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope","description":"Optional explicit write scope \":\" (kinds: user/team/org/project). Must be within the caller's visible scopes; defaults to user:."}},"type":"object","required":["chunks"],"title":"IngestKGRequest","description":"Knowledge graph ingestion request."},"IngestKGResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether ingestion succeeded"},"stats":{"$ref":"#/components/schemas/IngestStats","description":"Ingestion stats"},"errors":{"items":{"type":"string"},"type":"array","title":"Errors","description":"Error messages"}},"type":"object","required":["success"],"title":"IngestKGResponse","description":"Knowledge graph ingestion response."},"IngestMemoryOptions":{"properties":{"write_active":{"type":"boolean","title":"Write Active","description":"Write to active-memory worker","default":true},"write_passive":{"type":"boolean","title":"Write Passive","description":"Write to HelixDB (passive tier)","default":true},"ingest_mode":{"anyOf":[{"type":"string","enum":["sequential","batched"]},{"type":"null"}],"title":"Ingest Mode","description":"Internal: write path override (platform admin only; ignored otherwise)","x-internal":true}},"type":"object","title":"IngestMemoryOptions","description":"Toggles for the dual-write behaviour of /ingestion/memory."},"IngestMemoryRequest":{"properties":{"timezone":{"anyOf":[{"type":"string","maxLength":64,"description":"The caller's timezone (IANA name, e.g. Europe/Berlin, or +HH:MM) for natural-language turn timestamps such as \"yesterday 3pm\"; default UTC"},{"type":"null"}],"title":"Timezone"},"scope":{"anyOf":[{"type":"string"},{"$ref":"#/components/schemas/Scope"}],"title":"Scope","description":"Tenant scope dict (legacy) OR hierarchical write-scope string \":\" (org/user then come from the auth context)"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Explicit session id, honored on the string-scope path (the SDK sends it alongside a string scope; the legacy dict carries its own)"},"agent_id":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"Agent Id","description":"Agent identifier for the active-memory episode; falls back to default-agent if unset (same default as /recall)"},"turns":{"items":{"$ref":"#/components/schemas/IngestTurn"},"type":"array","maxItems":2000,"minItems":1,"title":"Turns","description":"At least one turn is required"},"supersedes":{"anyOf":[{"items":{"type":"string","pattern":"^[0-9a-f]{64}$"},"type":"array","maxItems":64},{"type":"null"}],"title":"Supersedes","description":"turn_ids this write CORRECTS. Each is retired once the new turns are durably stored, so a correction replaces the earlier text instead of sitting beside it. A turn id cannot be edited in place: its id is a hash of its own content, so a new version is always a new id, and this is what links them."},"options":{"anyOf":[{"$ref":"#/components/schemas/IngestMemoryOptions"},{"type":"null"}],"description":"Optional dual-write toggles"},"inactivity_timeout_seconds":{"anyOf":[{"type":"integer","maximum":86400.0,"minimum":300.0},{"type":"null"}],"title":"Inactivity Timeout Seconds","description":"Idle time in seconds after which this active-memory episode is closed and consolidated into long-term memory. Stored on the episode (later writes without it keep it). Omitted: the org default, else 1800 (30 min). Bounds: 300-86400."},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata","description":"Free-form caller metadata (currently unused)"}},"type":"object","required":["scope","turns"],"title":"IngestMemoryRequest","description":"Request body for POST /ingestion/memory."},"IngestMemoryResponse":{"properties":{"turn_times":{"items":{"$ref":"#/components/schemas/TurnTime"},"type":"array","title":"Turn Times","description":"Each turn's resolved capture time, in request order"},"job_id":{"type":"string","title":"Job Id","description":"Per-call observability id (uuid hex)"},"active_fragment_ids":{"items":{"type":"string"},"type":"array","title":"Active Fragment Ids","description":"Fragment ids written to active memory (turn first, then observations)"},"turn_ids":{"items":{"type":"string"},"type":"array","title":"Turn Ids","description":"Turn id (the item's content hash) of each stored item, parallel to active_fragment_ids. This is the handle for retiring a remembered turn (DELETE /ingestion/memory/turns/{turn_id}); the fragment id is a one-way hash of scope+turn id and cannot be converted back."},"not_stored_forgotten":{"items":{"type":"string"},"type":"array","title":"Not Stored Forgotten","description":"turn_ids in this request that were NOT stored because their owner had forgotten them (a resend of history, a retried batch). They are refused rather than brought back; remember new text to store it again."},"superseded":{"items":{"type":"string"},"type":"array","title":"Superseded","description":"turn_ids this write retired, from the request's `supersedes`"},"supersede_errors":{"items":{"type":"string"},"type":"array","title":"Supersede Errors","description":"Why a requested supersede did not complete. Non-empty means the OLD turn may still answer recall alongside the new one — the new turns are stored regardless, so this is never a reason to retry the whole write."},"passive_job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Passive Job Id","description":"Reserved for future async passive job tracking"},"usage":{"anyOf":[{"$ref":"#/components/schemas/Usage"},{"type":"null"}],"description":"Tokens billed for this call (always present in production)"}},"type":"object","required":["job_id"],"title":"IngestMemoryResponse","description":"Response for POST /ingestion/memory."},"IngestStats":{"properties":{"total_chunks_processed":{"type":"integer","title":"Total Chunks Processed","default":0},"raw_entities":{"type":"integer","title":"Raw Entities","default":0},"deduplicated_entities":{"type":"integer","title":"Deduplicated Entities","default":0},"entities_by_type":{"additionalProperties":{"type":"integer"},"type":"object","title":"Entities By Type"},"entities_inserted":{"type":"integer","title":"Entities Inserted","default":0},"entities_merged":{"type":"integer","title":"Entities Merged","default":0},"raw_relationships":{"type":"integer","title":"Raw Relationships","default":0},"resolved_relationships":{"type":"integer","title":"Resolved Relationships","default":0},"relationships_inserted":{"type":"integer","title":"Relationships Inserted","default":0},"vectors_inserted":{"type":"integer","title":"Vectors Inserted","default":0},"inferences_count":{"type":"integer","title":"Inferences Count","default":0},"inferences_attached":{"type":"integer","title":"Inferences Attached","default":0},"node_types_created":{"items":{"type":"string"},"type":"array","title":"Node Types Created"},"edge_types_created":{"items":{"type":"string"},"type":"array","title":"Edge Types Created"},"schema_created":{"type":"boolean","title":"Schema Created","default":false}},"type":"object","title":"IngestStats","description":"Knowledge graph ingestion statistics."},"IngestTurn":{"properties":{"text":{"type":"string","maxLength":65536,"minLength":1,"title":"Text","description":"Turn text content (not blank, at most 65,536 characters; split into fragments)"},"role":{"type":"string","enum":["user","assistant"],"title":"Role","description":"Speaker role"},"timestamp":{"type":"string","title":"Timestamp","description":"Capture time: ISO 8601 (e.g. 2026-01-01T09:30:00Z) or epoch seconds/milliseconds, or natural language (\"yesterday 3pm\", \"last Tuesday\", \"2 hours ago\") resolved against the request's arrival time in `timezone`; anything else is stored with the arrival time, marked uncertain"},"observations":{"items":{"type":"string","maxLength":3800,"minLength":1},"type":"array","maxItems":64,"title":"Observations","description":"Caller-supplied atomic facts to attach to this turn (each one fragment, at most 3800 characters)"}},"type":"object","required":["text","role","timestamp"],"title":"IngestTurn","description":"A single conversational turn for the unified /ingestion/memory endpoint."},"IngestionOptions":{"properties":{"auto_create_schema":{"type":"boolean","title":"Auto Create Schema","description":"Auto-create schema","default":true},"generate_embeddings":{"type":"boolean","title":"Generate Embeddings","description":"Generate embeddings","default":true},"validate":{"type":"boolean","title":"Validate","description":"Validate entities","default":false},"store_chunks":{"type":"boolean","title":"Store Chunks","description":"Store chunks","default":false}},"type":"object","title":"IngestionOptions","description":"Ingestion options."},"IntentGraph":{"properties":{"root":{"$ref":"#/components/schemas/TypedVariable","description":"Root variable representing the query starting point"},"goals":{"items":{"$ref":"#/components/schemas/TypedVariable"},"type":"array","title":"Goals","description":"Goal variables representing desired result entities"},"required_relations":{"items":{"$ref":"#/components/schemas/RelationHole"},"type":"array","title":"Required Relations","description":"Abstract relations between variables (relation holes)"}},"type":"object","required":["root","goals"],"title":"IntentGraph","description":"IntentGraph: abstract representation of user query intent.\n\nBased on HydraPlanner paper Section 6 (End-to-End Example).\nThis is the output of the IntentGraphBuilder stage."},"IntentMatch":{"properties":{"bindings":{"additionalProperties":{"$ref":"#/components/schemas/AgentBinding"},"type":"object","title":"Bindings","description":"Variable to binding mapping"},"documents":{"items":{"$ref":"#/components/schemas/AgentBinding"},"type":"array","title":"Documents","description":"Connected document nodes"},"evidence":{"items":{"$ref":"#/components/schemas/EvidenceItem"},"type":"array","title":"Evidence","description":"Evidence items"},"match_key":{"type":"string","title":"Match Key","description":"Stable identifier for deduplication"},"raw_bindings":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Raw Bindings","description":"Raw binding data (full mode only)"},"raw_documents":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Raw Documents","description":"Raw document data (full mode only)"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score","description":"Match confidence in [0, 1]: the weakest constrained binding's resolution score (exact name 1.0, else vector/fuzzy similarity). Matches arrive best first."}},"type":"object","required":["bindings","match_key"],"title":"IntentMatch","description":"Single intent match result."},"IntentMatchOptions":{"properties":{"max_matches":{"type":"integer","exclusiveMinimum":0.0,"title":"Max Matches","description":"Maximum matches to return"},"max_expansions":{"type":"integer","exclusiveMinimum":0.0,"title":"Max Expansions","description":"Maximum expansions"},"timeout_ms":{"type":"integer","exclusiveMinimum":0.0,"title":"Timeout Ms","description":"Timeout in milliseconds"},"beam_width":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Beam Width","description":"Optional: maximum neighbors to expand per relation (beam width)"},"response_mode":{"type":"string","title":"Response Mode","description":"Response mode (compact/full)"},"max_evidence":{"type":"integer","exclusiveMinimum":0.0,"title":"Max Evidence","description":"Maximum evidence items per match"},"max_documents":{"type":"integer","exclusiveMinimum":0.0,"title":"Max Documents","description":"Maximum document nodes per match"},"include_raw_properties":{"type":"boolean","title":"Include Raw Properties","description":"Include raw properties in full mode","default":false},"candidates_max":{"type":"integer","minimum":0.0,"title":"Candidates Max","description":"Emit best-effort candidates when > 0","default":0},"candidates_min_relations":{"type":"integer","minimum":0.0,"title":"Candidates Min Relations","description":"Minimum relations for candidates when enabled","default":0},"candidates_include_exact":{"type":"boolean","title":"Candidates Include Exact","description":"Whether candidates may include exact matches","default":false},"constraint_fuzzy":{"$ref":"#/components/schemas/ConstraintFuzzyConfig","description":"Fuzzy constraint matching configuration (required)"},"csp":{"anyOf":[{"$ref":"#/components/schemas/CSPConfig"},{"type":"null"}],"description":"Optional CSP configuration (advanced matching)"},"query_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query Type","description":"Optional planner hint: pure_graph, pure_vector, hybrid, entity_lookup"},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor","description":"Optional pagination cursor for streaming large result sets"},"page_size":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Page Size","description":"Optional page size for pagination"}},"type":"object","required":["max_matches","max_expansions","timeout_ms","response_mode","max_evidence","max_documents","constraint_fuzzy"],"title":"IntentMatchOptions","description":"Options for intent matching in HelixDB."},"IntentMatchStats":{"properties":{"matches_emitted":{"type":"integer","title":"Matches Emitted","description":"Number of matches returned"},"expansions":{"type":"integer","title":"Expansions","description":"Number of BFS expansions"},"documents_found":{"type":"integer","title":"Documents Found","description":"Number of documents found"},"elapsed_ms":{"type":"integer","title":"Elapsed Ms","description":"Elapsed time in milliseconds"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Non-fatal degradations the engine applied (e.g. a planner-proposed relation whose edge type is not in this tenant's schema was dropped)"},"constraint_resolution":{"items":{"type":"object"},"type":"array","title":"Constraint Resolution","description":"Per constrained variable: {variable, node_type, constraint, candidates[{entity_name, label, aliases, score}]}. Empty candidates = the constraint names nothing visible."},"unverified_relations":{"items":{"type":"object"},"type":"array","title":"Unverified Relations","description":"Planner relations ({from_var, to_var, role}) the schema has no matching edge type for; any edge between the two types was accepted, so matches do not verify them."}},"type":"object","required":["matches_emitted","expansions","documents_found","elapsed_ms"],"title":"IntentMatchStats","description":"Statistics for intent matching."},"IntentMatchesResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether matching succeeded"},"matches":{"items":{"$ref":"#/components/schemas/IntentMatch"},"type":"array","title":"Matches","description":"Intent matches"},"candidates":{"items":{"type":"object"},"type":"array","title":"Candidates","description":"Best-effort candidate matches (partial subgraphs) when enabled"},"stats":{"$ref":"#/components/schemas/IntentMatchStats","description":"Matching statistics"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if failed"}},"type":"object","required":["success","stats"],"title":"IntentMatchesResponse","description":"Response from HelixDB intent matching."},"JobProgress":{"properties":{"current_step":{"type":"string","title":"Current Step","description":"Current step"},"progress_percent":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Progress Percent","description":"Progress percentage"},"steps_completed":{"items":{"type":"string"},"type":"array","title":"Steps Completed","description":"Completed steps"},"steps_remaining":{"items":{"type":"string"},"type":"array","title":"Steps Remaining","description":"Remaining steps"}},"type":"object","required":["current_step","progress_percent"],"title":"JobProgress","description":"Job progress information."},"JobStatusResponse":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"Job identifier"},"job_type":{"type":"string","title":"Job Type","description":"Job type"},"status":{"type":"string","title":"Status","description":"Job status"},"progress":{"$ref":"#/components/schemas/JobProgress","description":"Progress info"},"scope":{"$ref":"#/components/schemas/Scope","description":"Job scope"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation time"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update time"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"Completion time"},"google_drive_file_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Google Drive File Id","description":"Google Drive file ID"},"unstructured_job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unstructured Job Id","description":"Unstructured job ID"},"s3_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"S3 Url","description":"S3 URL"},"helix_response":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Helix Response","description":"HelixDB response"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Error message"},"partial":{"type":"boolean","title":"Partial","description":"True when the engine stored the ingest but dropped some items (HTTP 206); see partial_errors","default":false},"partial_errors":{"items":{"type":"string"},"type":"array","title":"Partial Errors","description":"Per-item errors for a partial ingest"}},"type":"object","required":["job_id","job_type","status","progress","scope","created_at","updated_at"],"title":"JobStatusResponse","description":"Job status response."},"LoginRequest":{"properties":{"org_id":{"type":"string","minLength":1,"title":"Org Id","description":"Organization identifier"},"user_id":{"type":"string","minLength":1,"title":"User Id","description":"User identifier"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Optional session identifier"},"password":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Password","description":"Optional password"}},"type":"object","required":["org_id","user_id"],"title":"LoginRequest","description":"Login credentials for obtaining JWT tokens."},"MeResponse":{"properties":{"org_id":{"type":"string","title":"Org Id"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"api_keys":{"items":{"$ref":"#/components/schemas/APIKeyOut"},"type":"array","title":"Api Keys"}},"type":"object","required":["org_id"],"title":"MeResponse"},"MemoryBulkDeleteResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether deletion succeeded"},"deleted_count":{"type":"integer","minimum":0.0,"title":"Deleted Count","description":"Number of memories soft-deleted"},"user_id":{"type":"string","title":"User Id","description":"User ID whose memories were deleted"},"message":{"type":"string","title":"Message","description":"Status message","default":""}},"type":"object","required":["success","deleted_count","user_id"],"title":"MemoryBulkDeleteResponse","description":"Response from bulk memory deletion (GDPR/CCPA erasure)."},"MemoryDeleteResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether deletion succeeded"},"message":{"type":"string","title":"Message","description":"Status message","default":""}},"type":"object","required":["success"],"title":"MemoryDeleteResponse","description":"Response from memory deletion."},"MemoryListResponse":{"properties":{"memories":{"items":{"$ref":"#/components/schemas/MemoryResponse"},"type":"array","title":"Memories"},"count":{"type":"integer","title":"Count","description":"Number of items returned","default":0},"next_offset":{"type":"integer","title":"Next Offset","description":"Offset for next page","default":0}},"type":"object","title":"MemoryListResponse","description":"Paginated list of memories."},"MemoryResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Memory ID (UUID)"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"Owner user ID"},"type":{"type":"string","title":"Type","description":"Memory type: document, episode, preference","default":"unknown"},"label":{"type":"string","title":"Label","description":"Graph label","default":""},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"Text content or summary"},"status":{"type":"string","title":"Status","description":"Lifecycle status","default":"stored"},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata","description":"Additional properties"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At","description":"Creation timestamp (ISO)"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At","description":"Last update timestamp (ISO)"},"contexts":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Contexts","description":"Context sentences the entity appeared in (GET by id only; additive)"},"inferences":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Inferences","description":"Inference text generated for this node (GET by id only; additive)"}},"type":"object","required":["id"],"title":"MemoryResponse","description":"A single memory/document object."},"MemoryRetrievalHit":{"properties":{"fragment_id":{"type":"string","title":"Fragment Id","description":"Fragment ID (active) or HelixDB node ID (passive)"},"score":{"type":"number","title":"Score","description":"Final ranked score in [0, 1]. Active hits include a +0.15 recency boost prior to clamping."},"text":{"type":"string","title":"Text","description":"Fragment text (active) or LLM episode summary text (passive)"},"timestamp_ms":{"type":"integer","title":"Timestamp Ms","description":"Fragment or episode-window timestamp (ms since epoch)"},"episode_id":{"type":"string","title":"Episode Id","description":"Episode this hit belongs to"},"agent_id":{"type":"string","title":"Agent Id","description":"Agent that produced this memory"},"source":{"type":"string","title":"Source","description":"Memory tier: 'active' or 'passive'"},"entities":{"items":{"type":"string"},"type":"array","title":"Entities","description":"Extracted entities (populated for active episodes only)"},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata","description":"Opaque metadata forwarded from the backing store"}},"type":"object","required":["fragment_id","score","text","timestamp_ms","episode_id","agent_id","source"],"title":"MemoryRetrievalHit","description":"A single retrieval result from either the active or passive memory tier.\n\nThe ``source`` field indicates the tier:\n \"active\" → raw fragment text, recent, from the Durable Object\n \"passive\" → LLM-generated episode summary, older, from HelixDB"},"MemoryRetrieveRequest":{"properties":{"agent_id":{"type":"string","maxLength":256,"minLength":1,"title":"Agent Id","description":"Agent identifier"},"user_hash":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"User Hash","description":"Hashed user ID (never raw PII). If omitted, backend derives it from authenticated org_id + effective user scope."},"scope_user_id":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"Scope User Id","description":"Optional effective user_id for agent/service tokens. If provided, user_hash must match server-derived hash for this user."},"query_text":{"type":"string","maxLength":4096,"minLength":1,"title":"Query Text","description":"Text to embed and search"},"top_k":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Top K","description":"Max hits to return across all sources","default":10},"include_active":{"type":"boolean","title":"Include Active","description":"Query ACTIVE episodes (Cloudflare Durable Object)","default":true},"include_passive":{"type":"boolean","title":"Include Passive","description":"Query PASSIVE episodes (HelixDB consolidated summaries)","default":true},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope","description":"Optional scope \":\" to narrow the read to. Must be in the caller's visible scopes (403 otherwise); omitted = every visible scope."}},"type":"object","required":["agent_id","query_text"],"title":"MemoryRetrieveRequest","description":"Unified episodic memory retrieval request.\n\nRoutes automatically across two memory tiers based on the Episode Registry:\n ACTIVE episodes → Cloudflare Durable Object (recent, fast, per-fragment)\n PASSIVE episodes → HelixDB (consolidated summaries, older)\n\nResults from both tiers are merged and re-ranked before being returned.\nActive hits receive a recency score boost because an agent's current session\nis statistically more likely to be relevant than months-old consolidations."},"MemoryRetrieveResponse":{"properties":{"hits":{"items":{"$ref":"#/components/schemas/MemoryRetrievalHit"},"type":"array","title":"Hits"},"total_hits":{"type":"integer","title":"Total Hits","description":"Number of hits returned (≤ top_k)"},"active_episodes_searched":{"type":"integer","title":"Active Episodes Searched","description":"Number of ACTIVE episodes found in the registry"},"passive_episodes_searched":{"type":"integer","title":"Passive Episodes Searched","description":"Number of PASSIVE episodes found in the registry"}},"type":"object","required":["total_hits","active_episodes_searched","passive_episodes_searched"],"title":"MemoryRetrieveResponse","description":"Unified retrieval response with merged and re-ranked results from both tiers."},"MemoryUpdateRequest":{"properties":{"content":{"anyOf":[{"type":"string","maxLength":65536,"minLength":1,"description":"Memory text (at most 65536 characters and 8191 tokens)"},{"type":"null"}],"title":"Content","description":"New text content (triggers re-embed)"},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata","description":"Properties to merge"},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope","description":"Optional explicit write scope \":\" (kinds: user/team/org/project). Must be within the caller's visible scopes; defaults to user:."}},"type":"object","title":"MemoryUpdateRequest","description":"Request to update a memory's content or metadata."},"NLQAnswer":{"properties":{"status":{"type":"string","enum":["answered","no_match","no_data"],"title":"Status"},"source":{"anyOf":[{"type":"string","enum":["graph","vector"]},{"type":"null"}],"title":"Source"},"text":{"type":"string","title":"Text"},"entities":{"items":{"type":"string"},"type":"array","title":"Entities","description":"Answer entities, best first (graph answers)"},"evidence":{"items":{"$ref":"#/components/schemas/NLQEvidence"},"type":"array","title":"Evidence","description":"What the answer rests on"},"unresolved":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array","title":"Unresolved","description":"Constraints of the question that name nothing in your memory ({variable, constraint})"}},"type":"object","required":["status","text"],"title":"NLQAnswer","description":"The answer /nlq/execute computed from what it retrieved.\n\nDecided deterministically (no LLM): the best-scoring graph matches, else\nvector passages that mention every resolved anchor of the question, else\nno_match. Identical calls on unchanged data give the identical answer."},"NLQEvidence":{"properties":{"text":{"type":"string","title":"Text"},"source":{"type":"string","enum":["graph","vector"],"title":"Source"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"}},"type":"object","required":["text","source"],"title":"NLQEvidence"},"NLQExecuteRequest":{"properties":{"query":{"type":"string","minLength":1,"title":"Query","description":"Natural language query to execute"},"enable_pruning":{"type":"boolean","title":"Enable Pruning","description":"Enable schema pruning (planner)","default":true},"use_local_intelligence":{"type":"boolean","title":"Use Local Intelligence","description":"Use local intelligent planner (planner)","default":true},"execute":{"type":"boolean","title":"Execute","description":"If true, execute IntentGraph via intent matching","default":true},"enrich":{"type":"boolean","title":"Enrich","description":"If true, enrich results with neighboring nodes/edges for agent context (DEPRECATED - use intent matching)","default":true},"enrich_limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Enrich Limit","description":"Max neighbors per edge type during enrichment (DEPRECATED)","default":10},"compact":{"type":"boolean","title":"Compact","description":"If true, return agent-friendly output (redact internal fields, keep only relevant context)","default":true},"require_helix_ql":{"type":"boolean","title":"Require Helix Ql","description":"DEPRECATED: If true, fail when planner doesn't return helix_ql (legacy mode)","default":false},"intent_match_options":{"anyOf":[{"$ref":"#/components/schemas/IntentMatchOptions"},{"type":"null"}],"description":"Options for intent matching (if not provided, uses sensible defaults matching bloom-visualizer)"}},"type":"object","required":["query"],"title":"NLQExecuteRequest","description":"Natural language query -> plan -> execute request."},"NLQExecuteResponse":{"properties":{"answer":{"anyOf":[{"$ref":"#/components/schemas/NLQAnswer"},{"type":"null"}],"description":"The computed answer (null only for plan-only requests, execute=false)"},"planner":{"anyOf":[{"$ref":"#/components/schemas/QueryPlanResponse"},{"type":"null"}],"description":"Planner output (IntentGraph); null when the planner was not needed (no data) or failed"},"executed":{"type":"boolean","title":"Executed","description":"Whether intent matching was performed"},"intent_graph":{"anyOf":[{"$ref":"#/components/schemas/IntentGraph"},{"type":"null"}],"description":"Parsed IntentGraph from planner"},"intent_matches":{"anyOf":[{"$ref":"#/components/schemas/IntentMatchesResponse"},{"type":"null"}],"description":"Intent matching results from HelixDB (when executed=true)"},"rag":{"anyOf":[{"$ref":"#/components/schemas/SearchResponse"},{"type":"null"}],"description":"Optional vector-retrieval results (ranked passages) useful for RAG-style queries. When planner.query_type is 'pure_rag' (or 'hybrid' with parallel retrieval enabled), IntegrationBackend will include these results so clients can synthesize grounded answers."},"helixdb_query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Helixdb Query","description":"DEPRECATED: Legacy HelixQL query string (not used in intent matching mode)"},"chunks":{"items":{"type":"object"},"type":"array","title":"Chunks","description":"DEPRECATED: Resolved chunk contents (use intent_matches.evidence instead)"},"unresolved_chunk_ids":{"items":{"type":"string"},"type":"array","title":"Unresolved Chunk Ids","description":"DEPRECATED: Unresolved chunk IDs (not used in intent matching mode)"},"context":{"type":"object","title":"Context","description":"DEPRECATED: Agent context (use intent_matches.bindings/documents instead)"},"helixdb_result":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Helixdb Result","description":"DEPRECATED: Legacy HelixDB query result (use intent_matches instead)"},"helixdb_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Helixdb Error","description":"Error message if intent matching failed"},"nlq_status":{"type":"string","enum":["ok","degraded","failed","not_executed","no_data"],"title":"Nlq Status","description":"Outcome of retrieval. ok: executed cleanly. degraded: results returned but something was relaxed or a secondary leg failed (see degraded_reasons). failed: graph/vector retrieval failed and returned nothing (HTTP status is still 200). not_executed: plan-only request (execute=false). no_data: this tenant has no knowledge graph yet (the planner is not called).","default":"ok"},"degraded_reasons":{"items":{"type":"string"},"type":"array","title":"Degraded Reasons","description":"Stable codes for why nlq_status is degraded/failed: graph_unavailable, vector_unavailable, plan_unavailable, graph_relation_substituted, graph_relation_dropped, graph_relation_unverified, graph_plan_relaxed"}},"type":"object","required":["executed"],"title":"NLQExecuteResponse","description":"Natural language query -> plan -> execute response."},"NodeInsert":{"properties":{"label":{"type":"string","title":"Label","description":"Node type/label"},"properties":{"type":"object","title":"Properties","description":"Node properties"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Optional UUID"}},"type":"object","required":["label","properties"],"title":"NodeInsert","description":"Node insertion model."},"OrgSettingsOut":{"properties":{"org_id":{"type":"string","title":"Org Id"},"active_memory_inactivity_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Active Memory Inactivity Seconds","description":"Org default idle time (seconds) before an active-memory episode is closed and consolidated; null = system default. A write's inactivity_timeout_seconds overrides it."},"active_memory_inactivity_default_seconds":{"type":"integer","title":"Active Memory Inactivity Default Seconds","default":1800},"active_memory_inactivity_bounds":{"$ref":"#/components/schemas/InactivityBounds"}},"type":"object","required":["org_id"],"title":"OrgSettingsOut"},"OrgSettingsPatch":{"properties":{"active_memory_inactivity_seconds":{"anyOf":[{"type":"integer","maximum":86400.0,"minimum":300.0},{"type":"null"}],"title":"Active Memory Inactivity Seconds"}},"additionalProperties":false,"type":"object","title":"OrgSettingsPatch","description":"Partial update. ``null`` clears a setting back to the system default."},"PlannerSchema":{"properties":{"nodes":{"additionalProperties":{"$ref":"#/components/schemas/SchemaNode"},"type":"object","title":"Nodes","description":"Node types"},"edges":{"additionalProperties":{"$ref":"#/components/schemas/SchemaEdge"},"type":"object","title":"Edges","description":"Edge types"}},"type":"object","required":["nodes","edges"],"title":"PlannerSchema","description":"Database schema for query planner."},"PreferenceIngestRequest":{"properties":{"org_id":{"type":"string","title":"Org Id","description":"Organization identifier"},"user_id":{"type":"string","title":"User Id","description":"User identifier"},"preferences":{"items":{"$ref":"#/components/schemas/PreferenceItem"},"type":"array","minItems":1,"title":"Preferences","description":"Preferences"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Session identifier"},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope","description":"Optional explicit write scope \":\" (kinds: user/team/org/project). Must be within the caller's visible scopes; defaults to user:."}},"type":"object","required":["org_id","user_id","preferences"],"title":"PreferenceIngestRequest","description":"Preference ingestion request."},"PreferenceIngestResponse":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"Job identifier"},"status":{"type":"string","title":"Status","description":"Job status"},"preferences_count":{"type":"integer","title":"Preferences Count","description":"Number of preferences"},"estimated_time":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Estimated Time","description":"Estimated time in seconds"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Status message"}},"type":"object","required":["job_id","status","preferences_count"],"title":"PreferenceIngestResponse","description":"Preference ingestion response."},"PreferenceItem":{"properties":{"category":{"type":"string","title":"Category","description":"Preference category"},"entity":{"type":"string","title":"Entity","description":"Entity name"},"entity_type":{"type":"string","title":"Entity Type","description":"Entity type"},"preference_type":{"type":"string","title":"Preference Type","description":"PREFERS or DISLIKES"},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context","description":"Preference context"},"confidence":{"type":"string","title":"Confidence","description":"Confidence level","default":"medium"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Preference source","default":"user_statement"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Timestamp","description":"Preference timestamp"}},"type":"object","required":["category","entity","entity_type","preference_type"],"title":"PreferenceItem","description":"Preference item."},"ProbableAnswer":{"properties":{"id":{"type":"string","title":"Id","description":"Id of the chosen hit; always one of the hits in this response"},"text":{"type":"string","title":"Text","description":"The chosen hit's text, as in the list"},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timestamp","description":"The chosen hit's capture time, as in the list"},"probability":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Probability","description":"Probability that this memory is the answer (0..1)"},"question_time":{"type":"string","enum":["current","past","date","ever","future","timeless"],"title":"Question Time","description":"What time the question was read as being about"},"alternatives":{"items":{"$ref":"#/components/schemas/ProbableAnswerAlternative"},"type":"array","title":"Alternatives","description":"Up to two other hits that might be the answer, with their probabilities"}},"type":"object","required":["id","text","probability","question_time"],"title":"ProbableAnswer","description":"The memory that most probably answers the question, by sense."},"ProbableAnswerAlternative":{"properties":{"id":{"type":"string","title":"Id","description":"Id of another hit in the list"},"probability":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Probability"}},"type":"object","required":["id","probability"],"title":"ProbableAnswerAlternative"},"QueryPlanRequest":{"properties":{"query":{"type":"string","minLength":1,"title":"Query","description":"Natural language query"},"schema":{"$ref":"#/components/schemas/PlannerSchema","description":"Database schema"},"enable_pruning":{"type":"boolean","title":"Enable Pruning","description":"Enable schema pruning","default":true},"use_local_intelligence":{"type":"boolean","title":"Use Local Intelligence","description":"Use local intelligent planner","default":true}},"type":"object","required":["query","schema"],"title":"QueryPlanRequest","description":"Query plan generation request."},"QueryPlanResponse":{"properties":{"query_plan":{"type":"object","title":"Query Plan","description":"Generated QueryPlan JSON"},"query_type":{"type":"string","title":"Query Type","description":"Query type"},"constraint_embeddings":{"anyOf":[{"additionalProperties":{"items":{"type":"number"},"type":"array"},"type":"object"},{"type":"null"}],"title":"Constraint Embeddings","description":"Optional map of variable name -> 1024-d embedding for that variable's constraint string (BAAI/bge-large-en-v1.5 via emprocesser). If present, IntegrationBackend will forward this to HelixDB /intent/matches to enable vector-first constraint resolution."},"complexity_hints":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Complexity Hints","description":"Optional complexity hints from the planner (pass-through)"},"latency_ms":{"type":"number","title":"Latency Ms","description":"Processing latency"},"helix_ql":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Helix Ql","description":"Generated HelixQL code"},"entity":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Entity","description":"Detected entity info"},"planner_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Planner Version","description":"Planner version used"}},"type":"object","required":["query_plan","query_type","latency_ms"],"title":"QueryPlanResponse","description":"Query plan generation response."},"QueryRequest":{"properties":{"query":{"type":"string","minLength":1,"title":"Query","description":"HelixQL query string"},"params":{"type":"object","title":"Params","description":"Query parameters"},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope","description":"Optional explicit write scope \":\" (kinds: user/team/org/project). Must be within the caller's visible scopes; defaults to user:."}},"type":"object","required":["query"],"title":"QueryRequest","description":"Execute dynamic HelixQL query."},"QueryResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether query succeeded"},"data":{"title":"Data","description":"Query result data"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if failed"}},"type":"object","required":["success"],"title":"QueryResponse","description":"Query execution response."},"RecallEntity":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"label":{"type":"string","title":"Label"},"score":{"type":"number","title":"Score"}},"type":"object","required":["label","score"],"title":"RecallEntity"},"RecallHit":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"text":{"type":"string","title":"Text"},"score":{"type":"number","title":"Score"},"kind":{"type":"string","enum":["turn","observation","entity"],"title":"Kind","default":"turn"},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timestamp","description":"Capture time, ISO 8601 UTC"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms","description":"Capture time, epoch milliseconds"},"time_uncertain":{"type":"boolean","title":"Time Uncertain","description":"True when the turn's timestamp was not understood and the capture time is the arrival time","default":false}},"type":"object","required":["text","score"],"title":"RecallHit"},"RecallHits":{"properties":{"observations":{"items":{"$ref":"#/components/schemas/RecallHit"},"type":"array","title":"Observations"},"turns":{"items":{"$ref":"#/components/schemas/RecallHit"},"type":"array","title":"Turns"},"entities":{"items":{"$ref":"#/components/schemas/RecallEntity"},"type":"array","title":"Entities"}},"type":"object","title":"RecallHits"},"RecallRequest":{"properties":{"scope":{"anyOf":[{"type":"string"},{"$ref":"#/components/schemas/Scope"}],"title":"Scope","description":"Tenant scope dict (legacy) OR a hierarchical scope string \":\" narrowing the read to that visible scope"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Explicit session id, honored on the string-scope path"},"q":{"type":"string","maxLength":4096,"minLength":1,"title":"Q","description":"Query text (at most 4096 characters)"},"mode":{"type":"string","enum":["active","deep"],"title":"Mode","description":"Retrieval mode","default":"active"},"top_k":{"anyOf":[{"type":"integer","maximum":50.0,"minimum":1.0},{"type":"null"}],"title":"Top K","description":"Override default top_k"},"min_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Score","description":"Drop hits scoring below this. Without it, recall returns its full top_k nearest neighbours whatever their relevance — so escalating to the deep tier 'when active recall comes back empty' never fires against a non-empty store. Escalate on this threshold, not on an empty result."},"include_timeline":{"type":"boolean","title":"Include Timeline","description":"Attach a chronological timeline string to the response","default":false},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id","description":"Agent identifier for retrieval scoping; falls back to default-agent if unset"},"probable_answer":{"type":"boolean","title":"Probable Answer","description":"Ask for `probable_answer` in the response (default true). False skips it; the list is the same either way.","default":true}},"type":"object","required":["scope","q"],"title":"RecallRequest"},"RecallResponse":{"properties":{"hits":{"$ref":"#/components/schemas/RecallHits"},"timeline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timeline"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","description":"Relative confidence, NOT a calibrated probability. It is a sigmoid over the reranker's top-1 logit whose constants were never fitted (see services/retrieval_pipeline.py). It orders results correctly; its absolute value means nothing, so do not threshold on it — use min_score."},"mode":{"type":"string","enum":["active","deep"],"title":"Mode"},"usage":{"anyOf":[{"$ref":"#/components/schemas/Usage"},{"type":"null"}],"description":"Tokens billed for this call (always present in production)"},"active_tier_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Active Tier Error","description":"Set when the active-memory tier failed during this call; hits then come only from the remaining tier(s) (degraded, not empty-by-design)."},"deep_tier_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deep Tier Error","description":"Set when the deep (graph) tier failed during this call; hits then come only from the active tier (degraded, not empty-by-design)."},"probable_answer":{"anyOf":[{"$ref":"#/components/schemas/ProbableAnswer"},{"type":"null"}],"description":"Sometimes memory can give the most probable answer: when, by sense - the time or context the question is about - one memory is more probable than the others. It is one of the hits above; the list is still returned as before."},"probable_answer_reason":{"anyOf":[{"type":"string","enum":["no_memory_answers","unavailable","not_enabled"]},{"type":"null"}],"title":"Probable Answer Reason","description":"Why probable_answer is null (null when it is set): no_memory_answers = no memory in the list answers the question; unavailable = it could not be worked out this time; not_enabled = not requested or not enabled for this deployment."}},"type":"object","required":["hits","confidence","mode"],"title":"RecallResponse"},"RefreshTokenRequest":{"properties":{"refresh_token":{"type":"string","title":"Refresh Token","description":"Refresh token"}},"type":"object","required":["refresh_token"],"title":"RefreshTokenRequest","description":"Request to refresh access token."},"RelationHole":{"properties":{"from_var":{"type":"string","title":"From Var","description":"Source variable name"},"to_var":{"type":"string","title":"To Var","description":"Target variable name"},"role":{"type":"string","title":"Role","description":"Abstract semantic role (e.g., 'knows', 'employed_at', 'founded')"}},"type":"object","required":["from_var","to_var","role"],"title":"RelationHole","description":"An abstract relation between two variables (not bound to concrete edge label)."},"RelationshipItem":{"properties":{"from":{"type":"string","title":"From","description":"Source entity"},"relationship":{"type":"string","title":"Relationship","description":"Relationship type"},"to":{"type":"string","title":"To","description":"Target entity"},"confidence":{"type":"string","title":"Confidence","description":"Confidence level"},"context":{"type":"string","title":"Context","description":"Relationship context"}},"type":"object","required":["from","relationship","to","confidence","context"],"title":"RelationshipItem","description":"Relationship item from knowledge graph."},"SchemaEdge":{"properties":{"from":{"type":"string","title":"From","description":"Source node type"},"to":{"type":"string","title":"To","description":"Target node type"}},"type":"object","required":["from","to"],"title":"SchemaEdge","description":"Schema edge definition."},"SchemaNode":{"properties":{"fields":{"items":{"type":"string"},"type":"array","title":"Fields","description":"Regular fields"},"vector_fields":{"items":{"type":"string"},"type":"array","title":"Vector Fields","description":"Vector fields"}},"type":"object","required":["fields"],"title":"SchemaNode","description":"Schema node definition."},"SchemaResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether retrieval succeeded"},"data":{"type":"string","title":"Data","description":"HelixQL schema string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if failed"}},"type":"object","required":["success","data"],"title":"SchemaResponse","description":"Schema retrieval response."},"Scope":{"properties":{"org_id":{"type":"string","minLength":1,"title":"Org Id","description":"Organization ID"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"User ID"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Session ID"}},"type":"object","required":["org_id"],"title":"Scope","description":"Multi-tenant scope."},"ScopeMembershipGrant":{"properties":{"user_id":{"type":"string","maxLength":256,"minLength":1,"title":"User Id","description":"Application user ID"},"scope_id":{"type":"string","maxLength":256,"minLength":1,"title":"Scope Id","description":"Canonical scope id \":\" (kinds: user/team/org/project)"},"role":{"type":"string","maxLength":32,"minLength":1,"title":"Role","description":"Role within the scope","default":"member"}},"type":"object","required":["user_id","scope_id"],"title":"ScopeMembershipGrant","description":"Org-scoped grant request. Any `org_id` in the body is ignored."},"ScopeMembershipListResponse":{"properties":{"memberships":{"items":{"$ref":"#/components/schemas/ScopeMembershipResponse"},"type":"array","title":"Memberships"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["memberships","total"],"title":"ScopeMembershipListResponse"},"ScopeMembershipMutationResponse":{"properties":{"membership":{"$ref":"#/components/schemas/ScopeMembershipResponse"},"created":{"type":"boolean","title":"Created","description":"False when the grant already existed (idempotent add)"},"note":{"type":"string","title":"Note","description":"Propagation caveat","default":"Membership changes take effect on the user's next request; read-sets are resolved per request, not cached in tokens."}},"type":"object","required":["membership","created"],"title":"ScopeMembershipMutationResponse"},"ScopeMembershipResponse":{"properties":{"id":{"type":"integer","title":"Id"},"org_id":{"type":"string","title":"Org Id"},"user_id":{"type":"string","title":"User Id"},"scope_id":{"type":"string","title":"Scope Id"},"role":{"type":"string","title":"Role"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","org_id","user_id","scope_id","role","created_at"],"title":"ScopeMembershipResponse","description":"One membership row."},"ScopeMembershipTarget":{"properties":{"user_id":{"type":"string","maxLength":256,"minLength":1,"title":"User Id","description":"Application user ID"},"scope_id":{"type":"string","maxLength":256,"minLength":1,"title":"Scope Id","description":"Canonical scope id \":\" (kinds: user/team/org/project)"}},"type":"object","required":["user_id","scope_id"],"title":"ScopeMembershipTarget","description":"Who is being granted what, with no org — the org-scoped request body."},"SearchRequest":{"properties":{"query":{"type":"string","maxLength":4096,"minLength":1,"title":"Query","description":"Natural language search query"},"top_k":{"type":"integer","maximum":200.0,"minimum":1.0,"title":"Top K","description":"Number of results to return","default":10},"min_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Min Score","description":"Minimum similarity score (0-1)"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"Filter by node label/type"},"metadata_filter":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Metadata Filter","description":"Key-value metadata filters"}},"type":"object","required":["query"],"title":"SearchRequest","description":"Request for semantic vector search."},"SearchResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/SearchResultItem"},"type":"array","title":"Results"},"query_embedding_ms":{"type":"integer","title":"Query Embedding Ms","description":"Time to embed query (ms)","default":0},"search_ms":{"type":"integer","title":"Search Ms","description":"Time to search HNSW index (ms)","default":0}},"type":"object","title":"SearchResponse","description":"Response from semantic search."},"SearchResultItem":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID (UUID)"},"score":{"type":"number","title":"Score","description":"Similarity score (0-1)"},"text":{"type":"string","title":"Text","description":"Matched text content"},"type":{"type":"string","title":"Type","description":"Node type/label"},"metadata":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Metadata","description":"Node metadata. Engine-hydrated rendering keys (when available): text_source (vector|evidence|chunk|entity_name|none), entity_name, entity_type, source_chunk_id, source_document_id"},"inferences":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Inferences","description":"Inference text attached to the hit's entity (additive; null when none)"}},"type":"object","required":["id","score","text","type"],"title":"SearchResultItem","description":"A single search result."},"ServiceHealth":{"properties":{"name":{"type":"string","title":"Name","description":"Service name"},"available":{"type":"boolean","title":"Available","description":"Service availability"},"latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latency Ms","description":"Response latency"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message"}},"type":"object","required":["name","available"],"title":"ServiceHealth","description":"Individual service health status."},"SignupRequest":{"properties":{"org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id","description":"Optional org id (3-64 characters of lowercase a-z, 0-9, '-' or '_', starting with a letter or digit); auto-generated when omitted."},"name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Name","description":"Optional label for the first key"}},"type":"object","title":"SignupRequest"},"SignupResponse":{"properties":{"org_id":{"type":"string","title":"Org Id"},"user_id":{"type":"string","title":"User Id"},"key":{"$ref":"#/components/schemas/APIKeyOut"},"api_key":{"type":"string","title":"Api Key"}},"type":"object","required":["org_id","user_id","key","api_key"],"title":"SignupResponse"},"TokenExchangeRequest":{"properties":{"api_key":{"type":"string","title":"Api Key","description":"API Key starting with sk_live_"},"user_id":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"User Id","description":"Optional effective user_id for the minted JWT. If omitted, defaults to an api-key-scoped synthetic user."},"session_id":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"Session Id","description":"Optional session_id to include in the minted JWT"}},"type":"object","required":["api_key"],"title":"TokenExchangeRequest","description":"Request to exchange API key for access token."},"TokenResponse":{"properties":{"access_token":{"type":"string","title":"Access Token","description":"JWT access token"},"refresh_token":{"type":"string","title":"Refresh Token","description":"JWT refresh token"},"token_type":{"type":"string","title":"Token Type","description":"Token type","default":"bearer"},"expires_in":{"type":"integer","title":"Expires In","description":"Token expiration in seconds"}},"type":"object","required":["access_token","refresh_token","expires_in"],"title":"TokenResponse","description":"JWT token response."},"TurnTime":{"properties":{"turn_index":{"type":"integer","title":"Turn Index"},"original":{"title":"Original","description":"The timestamp as sent"},"timestamp":{"type":"string","title":"Timestamp","description":"Capture time, ISO 8601 UTC"},"timestamp_ms":{"type":"integer","title":"Timestamp Ms"},"source":{"type":"string","enum":["explicit","relative","arrival"],"title":"Source","description":"explicit time / natural language resolved against arrival / not understood"},"uncertain":{"type":"boolean","title":"Uncertain","description":"True when the capture time is only the arrival time"}},"type":"object","required":["turn_index","original","timestamp","timestamp_ms","source","uncertain"],"title":"TurnTime","description":"How one turn's capture time was obtained."},"TypedVariable":{"properties":{"name":{"type":"string","title":"Name","description":"Variable name"},"type":{"type":"string","title":"Type","description":"Node label/type from schema"},"constraint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Constraint","description":"Optional abstract constraint (e.g., 'large tech', 'recent')"}},"type":"object","required":["name","type"],"title":"TypedVariable","description":"A typed variable in the IntentGraph."},"UpdateSchemaRequest":{"properties":{"schema":{"type":"string","minLength":1,"title":"Schema","description":"HelixQL schema definition"}},"type":"object","required":["schema"],"title":"UpdateSchemaRequest","description":"Update database schema."},"Usage":{"properties":{"tokens_in":{"type":"integer","title":"Tokens In","description":"Tokens in the request payload","default":0},"tokens_out":{"type":"integer","title":"Tokens Out","description":"Tokens in the response payload","default":0}},"type":"object","title":"Usage","description":"Token usage for a metered API call.\n\nSurfaced on every metered response so developers can see the cost of\neach call inline — mirrors OpenAI / Anthropic ``usage`` objects so the\nTex bill is denominated in the same unit they already track for their\nLLM provider. Tokens are counted server-side with the ``cl100k_base``\nencoding (matches ``text-embedding-3-large``)."},"UsageQuotaStatus":{"properties":{"tokens_in_used":{"type":"integer","title":"Tokens In Used"},"tokens_out_used":{"type":"integer","title":"Tokens Out Used"},"tokens_in_limit":{"type":"integer","title":"Tokens In Limit"},"tokens_out_limit":{"type":"integer","title":"Tokens Out Limit"},"period":{"type":"string","title":"Period","default":"day"},"period_start":{"type":"string","title":"Period Start"},"period_end":{"type":"string","title":"Period End"}},"type":"object","required":["tokens_in_used","tokens_out_used","tokens_in_limit","tokens_out_limit","period_start","period_end"],"title":"UsageQuotaStatus"},"UsageWindow":{"properties":{"period":{"type":"string","title":"Period","description":"'day' or 'month'"},"start":{"type":"string","title":"Start","description":"ISO-8601 UTC start of window (inclusive)"},"end":{"type":"string","title":"End","description":"ISO-8601 UTC end of window (exclusive)"},"tokens_in":{"type":"integer","title":"Tokens In"},"tokens_out":{"type":"integer","title":"Tokens Out"}},"type":"object","required":["period","start","end","tokens_in","tokens_out"],"title":"UsageWindow"},"UserHashResponse":{"properties":{"org_id":{"type":"string","title":"Org Id"},"user_id":{"type":"string","title":"User Id"},"user_hash":{"type":"string","title":"User Hash"}},"type":"object","required":["org_id","user_id","user_hash"],"title":"UserHashResponse","description":"Server-generated user hash bound to org_id + user_id."},"UserProfileResponse":{"properties":{"profile":{"type":"string","title":"Profile","description":"Human-readable profile text","default":""},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At","description":"Last update timestamp"},"preferences_count":{"type":"integer","title":"Preferences Count","description":"Number of stored preferences","default":0},"episodes_count":{"type":"integer","title":"Episodes Count","description":"Number of stored episodes","default":0},"preferences":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"title":"Preferences","description":"Raw preference data"}},"type":"object","title":"UserProfileResponse","description":"Synthesized user profile for LLM injection."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VectorInsert":{"properties":{"label":{"type":"string","title":"Label","description":"Vector label"},"data":{"anyOf":[{"items":{"type":"number"},"type":"array"},{"type":"null"}],"title":"Data","description":"Raw vector data"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text","description":"Text to generate embedding from"},"properties":{"type":"object","title":"Properties","description":"Vector properties"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Optional UUID"}},"type":"object","required":["label"],"title":"VectorInsert","description":"Vector insertion model."},"_BatchFragment":{"properties":{"text":{"type":"string","maxLength":4096,"minLength":1,"title":"Text"},"agent_id":{"type":"string","title":"Agent Id"},"episode_id":{"type":"string","title":"Episode Id"},"user_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Hash"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"fragment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fragment Id"},"skip_enrichment":{"type":"boolean","title":"Skip Enrichment","default":true},"entities":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Entities"},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata"},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope"},"inactivity_timeout_seconds":{"anyOf":[{"type":"integer","maximum":86400.0,"minimum":300.0},{"type":"null"}],"title":"Inactivity Timeout Seconds"}},"type":"object","required":["text","agent_id","episode_id"],"title":"_BatchFragment"},"_BatchIngestRequest":{"properties":{"fragments":{"items":{"$ref":"#/components/schemas/_BatchFragment"},"type":"array","maxItems":2000,"minItems":1,"title":"Fragments"},"inactivity_timeout_seconds":{"anyOf":[{"type":"integer","maximum":86400.0,"minimum":300.0},{"type":"null"}],"title":"Inactivity Timeout Seconds"}},"type":"object","required":["fragments"],"title":"_BatchIngestRequest"},"_BatchIngestResponse":{"properties":{"ingested":{"type":"integer","title":"Ingested"},"total":{"type":"integer","title":"Total"},"failed":{"type":"integer","title":"Failed","default":0},"partial":{"type":"boolean","title":"Partial","default":false},"errors":{"items":{"$ref":"#/components/schemas/_BatchItemError"},"type":"array","title":"Errors","default":[]}},"type":"object","required":["ingested","total"],"title":"_BatchIngestResponse"},"_BatchItemError":{"properties":{"index":{"type":"integer","title":"Index"},"fragment_id":{"type":"string","title":"Fragment Id"},"episode_id":{"type":"string","title":"Episode Id"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code"},"error":{"type":"string","title":"Error"}},"type":"object","required":["index","fragment_id","episode_id","error"],"title":"_BatchItemError"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}}}