{"components":{"responses":{"Error":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"schemas":{"Error":{"properties":{"error":{"type":"string"}},"type":"object"},"GraphAskRequest":{"description":"Either query or seed_ids must be supplied.","properties":{"max_hops":{"default":2,"description":"Traversal depth. Values outside 1-5 are clamped to 2 rather than rejected.","maximum":5,"minimum":1,"type":"integer"},"query":{"description":"Natural-language question; resolved to seed entities.","type":"string"},"seed_ids":{"description":"Explicit entity IDs to start traversal from, instead of resolving a query.","items":{"type":"string"},"maxItems":32,"type":"array"}},"type":"object"},"Memory":{"properties":{"agent_id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"metadata":{"type":"object"},"tags":{"items":{"type":"string"},"type":"array"},"text":{"type":"string"}},"required":["id"],"type":"object"},"MemoryList":{"properties":{"agent_id":{"type":"string"},"count":{"type":"integer"},"items":{"items":{"$ref":"#/components/schemas/Memory"},"type":"array"},"results":{"items":{"$ref":"#/components/schemas/Memory"},"type":"array"}},"type":"object"},"OntologyAssertion":{"properties":{"object":{"type":"string"},"predicate":{"enum":["has_status","belongs_to","created_in","written_by","references","supersedes","consolidated_from"],"type":"string"},"subject":{"type":"string"}},"required":["subject","predicate","object"],"type":"object"},"OntologyEnvelope":{"properties":{"assertion":{"$ref":"#/components/schemas/OntologyAssertion"},"source_excerpt":{"description":"Must occur verbatim in text when supplied.","maxLength":1000,"type":"string"},"source_memory_id":{"description":"Existing memory ID in the authenticated tenant; use when source text is unavailable.","type":"string"},"version":{"const":"heurchain-ontology/v1","type":"string"}},"required":["version","assertion"],"type":"object"},"QueryRequest":{"anyOf":[{"properties":{"embedding":{"minItems":1}},"required":["embedding"]},{"properties":{"text":{"pattern":"\\S"}},"required":["text"]}],"description":"Provide a nonempty embedding or nonblank text. A supplied nonempty embedding takes precedence; otherwise the broker generates one using its configured embedding provider.","properties":{"agent_id":{"type":"string"},"embedding":{"items":{"type":"number"},"maxItems":4096,"type":"array"},"tags":{"items":{"type":"string"},"type":"array"},"text":{"type":"string"},"threshold":{"type":"number"},"top_k":{"minimum":1,"type":"integer"}},"type":"object"},"SearchRequest":{"properties":{"agent_id":{"type":"string"},"limit":{"maximum":50,"minimum":1,"type":"integer"},"tags":{"items":{"type":"string"},"type":"array"},"text":{"type":"string"}},"required":["text"],"type":"object"},"SessionStartRequest":{"properties":{"agent_id":{"type":"string"},"ttl_seconds":{"minimum":1,"type":"integer"}},"required":["agent_id"],"type":"object"},"StoreRequest":{"properties":{"agent_id":{"type":"string"},"metadata":{"type":"object"},"namespace":{"default":"notes","description":"Memory decay tier. Governs how fast this item loses activation and is eventually moved to the cold vault (where it stops appearing in search results). 'ops' decays fastest (operational chatter), 'notes' is the default, 'self' decays slowest (durable facts about the agent or user). An unrecognised value is rejected with 400 rather than silently defaulting.","enum":["ops","notes","self"],"type":"string"},"ontology":{"$ref":"#/components/schemas/OntologyEnvelope"},"tags":{"items":{"type":"string"},"type":"array"},"text":{"type":"string"}},"required":["text"],"type":"object"}},"securitySchemes":{"AdminBasicAuth":{"scheme":"basic","type":"http"},"HeurChainAPIKey":{"in":"header","name":"X-HeurChain-API-Key","type":"apiKey"},"HeurChainTenant":{"in":"header","name":"X-HeurChain-Tenant","type":"apiKey"}}},"info":{"description":"Persistent, tenant-isolated memory for AI agents. Send both HeurChain headers on every secured operation.","title":"HeurChain Memory API","version":"0.4.4"},"openapi":"3.1.0","paths":{"/admin/vault/rehydrate":{"post":{"operationId":"rehydrateVaultDocument","parameters":[{"in":"query","name":"tenant_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"doc_id":{"type":"string"}},"required":["doc_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Document rehydrated"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"security":[{"AdminBasicAuth":[]}],"summary":"Restore one vaulted document to active retrieval"}},"/agent/{agent_id}":{"get":{"operationId":"getAgentMemories","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"default":10,"maximum":50,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryList"}}},"description":"Recent agent memories"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}},"summary":"Get an agent's most recent memories"}},"/agent/{agent_id}/recall":{"get":{"operationId":"getAgentSessions","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Active sessions"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}},"summary":"Get active session IDs for compatibility"}},"/graph/ask":{"post":{"description":"Traverses the heurgraph relationship index to answer questions that need more than one hop, e.g. \"what depends on X?\", returning each answer with per-edge provenance back to the source memory.\n\n**Currently returns 501 Not Implemented.** Authentication and input validation are live, but traversal is not built yet — the endpoint deliberately 501s rather than returning an empty 200, because an empty success is indistinguishable from \"the graph has no answer\" and would cause callers to cache a false negative. Do not depend on this endpoint yet.","operationId":"graphAsk","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphAskRequest"}}},"required":true},"responses":{"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"501":{"$ref":"#/components/responses/Error"}},"summary":"Multi-hop knowledge-graph query (NOT YET IMPLEMENTED — returns 501)"}},"/health":{"get":{"operationId":"getHealth","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Health status"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}},"security":[],"summary":"Check Redis/SQLite liveness; does not check Qdrant"}},"/memory/manifest":{"get":{"operationId":"getMemoryManifest","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Memory manifest"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}},"summary":"Inspect available memory before asking the user"}},"/ontology/capabilities":{"get":{"operationId":"getOntologyCapabilities","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Ontology policy capabilities"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}},"security":[],"summary":"Inspect the optional ontology policy"}},"/openapi.json":{"get":{"operationId":"getOpenAPISpec","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OpenAPI document"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}},"security":[],"summary":"Get this OpenAPI document"}},"/query":{"post":{"operationId":"queryMemories","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Query results"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"503":{"description":"Text query embedding provider is unavailable or returned an invalid vector"}},"summary":"Query memories with text or a client-provided embedding"}},"/ready":{"get":{"operationId":"getReadiness","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Dependencies reachable; index_coverage is not_checked"},"503":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"One or more dependencies unavailable; includes per-dependency status"}},"security":[],"summary":"Check Redis, SQLite and authenticated Qdrant read connectivity within two seconds; not index coverage"}},"/search":{"post":{"operationId":"searchMemories","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryList"}}},"description":"Ranked memories"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}},"summary":"Search durable memories by meaning"}},"/session/end":{"post":{"operationId":"endSession","requestBody":{"content":{"application/json":{"schema":{"properties":{"session_id":{"type":"string"}},"required":["session_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Session ended"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}},"summary":"End an agent session"}},"/session/start":{"post":{"operationId":"startSession","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionStartRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Started session"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}},"summary":"Start an agent session"}},"/session/{session_id}/context":{"get":{"operationId":"getSessionContext","parameters":[{"in":"path","name":"session_id","required":true,"schema":{"type":"string"}},{"in":"query","name":"n","schema":{"default":20,"maximum":50,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Session context"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}},"summary":"Get recent session context"}},"/store":{"post":{"operationId":"storeMemory","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Stored and indexed memory (non-silo); stored encrypted memory (silo)"},"202":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Memory stored, but indexing incomplete. indexed=false; retry the same document ID. No automatic retry is scheduled."},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}},"summary":"Store a durable memory"}}},"security":[{"HeurChainAPIKey":[],"HeurChainTenant":[]}],"servers":[{"url":"https://api.heurchain.com"}]}