{"openapi":"3.1.0","info":{"title":"Verix","description":"Verix is the verified knowledge layer of SNO Nexus — semantic retrieval, grounded chat, and a queryable knowledge graph over content you curate.","version":"0.10.33"},"servers":[{"url":"https://verix.sno.ai","description":"Production"}],"tags":[{"name":"Identity","description":"Authenticated session and read-only identity lookups."},{"name":"Ingest","description":"Add curated content into the knowledge base."},{"name":"Retrieve","description":"Search, chat, and surface grounded suggestions."},{"name":"Knowledge","description":"Manage the documents that ground your answers."},{"name":"Spaces","description":"Scope content into collaborative collections."},{"name":"Knowledge Graph","description":"Entities, relationships, and graph-aware retrieval."},{"name":"System","description":"Health and operational endpoints."}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Project-scoped HMAC API key. Format: `sno-{random}-{signature}`. Also accepted via `Authorization: Bearer …`."}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{"type":"string"},"timestamp":{"type":"string"}},"required":["error"]}},"parameters":{}},"paths":{"/health":{"get":{"tags":["System"],"summary":"Liveness and readiness check","responses":{"200":{"description":"Health status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","unhealthy"]},"ready":{"type":"boolean"},"version":{"type":"string"},"timestamp":{"type":"string"},"service":{"type":"string"},"services":{"type":"object","additionalProperties":{"type":"string","enum":["connected","disconnected","degraded","unknown","n/a"]}},"issues":{"type":"array","items":{"type":"string"}},"metrics":{"type":"object","additionalProperties":{}}},"required":["status","ready","version","timestamp","service"]}}}}}}},"/v1/user":{"get":{"tags":["Identity"],"summary":"Workspace owner and workspace metadata","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Workspace owner profile","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":["string","null"]},"userPlan":{"type":["string","null"]},"workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kbEnabled":{"type":["boolean","null"]}},"required":["id","name"]}},"required":["id","username","workspace"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Workspace owner not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/user/spaces":{"get":{"tags":["Identity"],"summary":"Spaces the caller can access","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Spaces in caller's workspace","content":{"application/json":{"schema":{"type":"object","properties":{"workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kbEnabled":{"type":["boolean","null"]}},"required":["id","name"]},"projects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":["string","null"]},"hasApiKey":{"type":"boolean"},"createdAt":{"type":["string","null"]},"updatedAt":{"type":["string","null"]}},"required":["id","title","hasApiKey"]}}},"required":["workspace","projects"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/user/history":{"get":{"tags":["Identity"],"summary":"Caller's chat thread history","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Chat thread history","content":{"application/json":{"schema":{"type":"object","properties":{"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"userDataId":{"type":["string","null"]},"title":{"type":["string","null"]},"createdAt":{"type":["string","null"]}},"required":["id"],"additionalProperties":{}}}},"required":["history"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/user/invitations":{"get":{"tags":["Identity"],"summary":"Read-only list of workspace members","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Workspace members","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"userId":{"type":"string"},"role":{"type":["string","null"]},"isPrimaryAdmin":{"type":["boolean","null"]},"createdAt":{"type":["string","null"]},"username":{"type":["string","null"]}},"required":["id","userId"]}}},"required":["message","workspace","members"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/user/key":{"get":{"tags":["Identity"],"summary":"Retrieve the project's API key","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Project API key","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"project":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":["string","null"]}},"required":["id","title"]},"message":{"type":"string"}},"required":["key","project","message"]}}}},"400":{"description":"No key configured for this project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/spaces":{"get":{"tags":["Spaces"],"summary":"List spaces in the workspace","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Spaces in caller's workspace","content":{"application/json":{"schema":{"type":"object","properties":{"spaces":{"type":"array","items":{}}},"required":["spaces"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/spaces/{spaceId}":{"get":{"tags":["Spaces"],"summary":"Fetch a single space","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"spaceId","in":"path"}],"responses":{"200":{"description":"Space details","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Space not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/spaces/addContent":{"post":{"tags":["Spaces"],"summary":"Attach a document to a space","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"spaceId":{"type":"string"},"documentId":{"type":"string"}},"required":["spaceId","documentId"]}}}},"responses":{"200":{"description":"Content attached","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"spaceId":{"type":"string"}},"required":["success"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to add content to space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/spaces/moveContent":{"post":{"tags":["Spaces"],"summary":"Move a document between spaces","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"spaceId":{"type":"string"},"documentId":{"type":"string"}},"required":["spaceId","documentId"]}}}},"responses":{"200":{"description":"Content moved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"spaceId":{"type":"string"}},"required":["success"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to move content to space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/chat/{threadUuid}":{"get":{"tags":["Retrieve"],"summary":"Fetch a chat thread's history","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"threadUuid","in":"path"}],"responses":{"200":{"description":"Chat thread history","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{}}},"required":["messages"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Chat history not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/chat":{"post":{"tags":["Retrieve"],"summary":"Grounded RAG chat (SSE streaming)","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant","system"]},"content":{"type":"string","minLength":1,"maxLength":32000},"annotations":{},"experimental_attachments":{"type":"array","items":{}},"data":{"type":"object","additionalProperties":{}}},"required":["role","content"]},"minItems":1,"maxItems":50},"threadId":{"type":"string","format":"uuid"}},"required":["messages"]}}}},"responses":{"200":{"description":"Streaming chat response (Server-Sent Events)","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-Sent Events stream. Each event is a `data: {json}\\n\\n` line."}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Chat thread not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/recommended-questions":{"get":{"tags":["Retrieve"],"summary":"AI-generated follow-up questions","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Recommended follow-up questions","content":{"application/json":{"schema":{"type":"object","properties":{"questions":{"type":"array","items":{"type":"string"}}},"required":["questions"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/suggested-learnings":{"get":{"tags":["Retrieve"],"summary":"Learning cards from your sources","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Suggested learning cards","content":{"application/json":{"schema":{"type":"object","properties":{"learnings":{"type":"array","items":{}}},"required":["learnings"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/search":{"post":{"tags":["Retrieve"],"summary":"Hybrid semantic + vector search","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":1000},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10},"threshold":{"type":"number","minimum":0,"maximum":1,"default":0.5},"spaces":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50}},"required":["query"]}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{}},"query":{"type":"string"}},"required":["results","query"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/add":{"post":{"tags":["Ingest"],"summary":"Add one item (URL, text, or file)","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":100000},"spaces":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":5},"id":{"type":"string","format":"uuid"},"metadata":{"type":"object","additionalProperties":{}},"images":{"type":"array","items":{"type":"string","maxLength":2048},"maxItems":10},"prefetched":{"type":"object","properties":{"contentToVectorize":{"type":"string","minLength":1,"maxLength":100000},"contentToSave":{"type":"string","minLength":1,"maxLength":100000},"title":{"type":"string","maxLength":500},"type":{"type":"string","maxLength":50},"description":{"type":"string","maxLength":2000},"ogImage":{"type":"string","maxLength":2048}},"required":["contentToVectorize","contentToSave","title","type"]}},"required":["content"]}}}},"responses":{"200":{"description":"Content added successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"id":{"type":"string"},"type":{"type":"string"}},"required":["message","id","type"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Content already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/batch-add":{"post":{"tags":["Ingest"],"summary":"Add many items in a single request","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"urls":{"type":"array","items":{"type":"string","maxLength":2048},"minItems":1,"maxItems":50},"contents":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":100000},"title":{"type":"string","maxLength":500},"type":{"type":"string","enum":["page","tweet","note","document","notion"]}},"required":["content","title","type"]},"maxItems":50},"spaces":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":5}}}}}},"responses":{"200":{"description":"Streaming batch add progress (Server-Sent Events)","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-Sent Events stream. Each event is a `data: {json}\\n\\n` line."}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/integrations/notion/import":{"get":{"tags":["Ingest"],"summary":"Stream an import from Notion (SSE)","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Streaming Notion import progress (Server-Sent Events)","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-Sent Events stream. Each event is a `data: {json}\\n\\n` line."}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/memories":{"get":{"tags":["Knowledge"],"summary":"List documents, paginated","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","default":"0"},"required":false,"name":"start","in":"query"},{"schema":{"type":"string","default":"10"},"required":false,"name":"count","in":"query"},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i"},"required":false,"name":"spaceId","in":"query"}],"responses":{"200":{"description":"Paginated list of documents","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{}},"total":{"type":"number"}},"required":["items","total"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Knowledge"],"summary":"Remove up to 50 documents in one call","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i"}}},"required":["ids"]}}}},"responses":{"200":{"description":"Batch delete result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"deletedCount":{"type":"number"},"requestedCount":{"type":"number"}},"required":["success","deletedCount","requestedCount"]}}}},"400":{"description":"Invalid batch request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No documents found to delete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/memories/{id}":{"get":{"tags":["Knowledge"],"summary":"Fetch a document by id","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Document","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Memory not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Knowledge"],"summary":"Remove a single document","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Document deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Memory not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/entities":{"get":{"tags":["Knowledge Graph"],"summary":"Browse extracted entities with filters","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["person","organization","location","topic","concept","product","event"]},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"search","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["mentions","recent","name"],"default":"mentions"},"required":false,"name":"sortBy","in":"query"}],"responses":{"200":{"description":"List of entities with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"entities":{"type":"array","items":{}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["entities","pagination"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/entities/stats":{"get":{"tags":["Knowledge Graph"],"summary":"Aggregate counts and top mentions","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Entity stats","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/entities/{id}":{"get":{"tags":["Knowledge Graph"],"summary":"Entity detail, mentions, confidence","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":["number","null"],"example":123},"required":false,"name":"id","in":"path"}],"responses":{"200":{"description":"Entity detail","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Entity not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/entities/{id}/related":{"get":{"tags":["Knowledge Graph"],"summary":"Entities linked by relationships","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":["number","null"],"example":123},"required":false,"name":"id","in":"path"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"maximum":100,"default":40},"required":false,"name":"minStrength","in":"query"}],"responses":{"200":{"description":"Related entities","content":{"application/json":{"schema":{"type":"object","properties":{"entityId":{"type":"number"},"related":{"type":"array","items":{}}},"required":["entityId","related"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Entity not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/entities/{id}/neighborhood":{"get":{"tags":["Knowledge Graph"],"summary":"Multi-hop graph around an entity","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":["number","null"],"example":123},"required":false,"name":"id","in":"path"},{"schema":{"type":"number","minimum":1,"maximum":3,"default":2},"required":false,"name":"maxHops","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"maximum":100,"default":40},"required":false,"name":"minStrength","in":"query"}],"responses":{"200":{"description":"Entity neighborhood","content":{"application/json":{"schema":{"type":"object","properties":{"entityId":{"type":"number"},"maxHops":{"type":"number"},"entities":{"type":"array","items":{}}},"required":["entityId","maxHops","entities"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Entity not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/entities/{id}/documents":{"get":{"tags":["Knowledge Graph"],"summary":"Source documents that mention it","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":["number","null"],"example":123},"required":false,"name":"id","in":"path"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Entity documents","content":{"application/json":{"schema":{"type":"object","properties":{"entityId":{"type":"number"},"documents":{"type":"array","items":{}}},"required":["entityId","documents"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Entity not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/entities/graph/path":{"get":{"tags":["Knowledge Graph"],"summary":"Shortest path between two entities","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":["number","null"]},"required":false,"name":"from","in":"query"},{"schema":{"type":["number","null"]},"required":false,"name":"to","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":5,"default":3},"required":false,"name":"maxDepth","in":"query"}],"responses":{"200":{"description":"Shortest path result","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/entities/graph/related-documents/{documentId}":{"get":{"tags":["Knowledge Graph"],"summary":"Documents related via shared entities","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"documentId","in":"path"}],"responses":{"200":{"description":"Related documents","content":{"application/json":{"schema":{"type":"object","properties":{"documentId":{"type":"string"},"relatedDocuments":{"type":"array","items":{}}},"required":["documentId","relatedDocuments"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/entities/graph/expand-query":{"post":{"tags":["Knowledge Graph"],"summary":"Expand a query with entity context","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500},"maxExpansions":{"type":"number","minimum":1,"maximum":10,"default":5}},"required":["query"]}}}},"responses":{"200":{"description":"Expanded query","content":{"application/json":{"schema":{"type":"object","properties":{"originalQuery":{"type":"string"},"expansions":{"type":"array","items":{}},"expandedQuery":{"type":"string"}},"required":["originalQuery","expansions","expandedQuery"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/session":{"get":{"tags":["Identity"],"summary":"Current authenticated session","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Authenticated user context","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{},"additionalProperties":{}}},"required":["user"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{}}