{"openapi":"3.1.0","info":{"title":"Soma API","summary":"Your organization's knowledge: documents, search, knowledge graph, answers.","description":"Authenticate with `Authorization: Bearer <token>`: an OAuth access token (the Soma CLI and MCP clients get one by signing in) or an API key created in Soma under Account settings.","version":"1.0.0"},"servers":[{"url":"https://staging.soma.evarist.com/v1"}],"paths":{"/me":{"get":{"tags":["Workspaces"],"summary":"Get the current caller","operationId":"me_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}}},"security":[{"HTTPBearer":[]}]}},"/workspaces":{"get":{"tags":["Workspaces"],"summary":"List workspaces","description":"The workspaces the caller can read.","operationId":"list_workspaces_workspaces_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Workspace_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Workspaces"],"summary":"Create a workspace","description":"Creates a workspace; the caller becomes its owner.","operationId":"create_workspace_workspaces_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}},"403":{"description":"Read-only token, or not allowed in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workspaces/{workspace_id}":{"get":{"tags":["Workspaces"],"summary":"Get a workspace","operationId":"get_workspace_workspaces__workspace_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["Workspaces"],"summary":"Update a workspace","description":"Rename a workspace or change its description (owner or editor).","operationId":"update_workspace_workspaces__workspace_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}},"403":{"description":"Read-only token, or not allowed in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Workspaces"],"summary":"Delete a workspace","description":"Removes the workspace and its memberships for everyone and stops its ingestions. Its documents stay indexed for the other workspaces that use them.","operationId":"delete_workspace_workspaces__workspace_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}],"responses":{"204":{"description":"Successful Response"},"403":{"description":"Read-only token, or not allowed in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workspaces/{workspace_id}/documents":{"get":{"tags":["Documents"],"summary":"List documents","description":"The documents of a workspace's knowledge base.","operationId":"list_documents_workspaces__workspace_id__documents_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter on the title (case-insensitive substring).","title":"Q"},"description":"Filter on the title (case-insensitive substring)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Document_"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workspaces/{workspace_id}/documents/{document_id}":{"get":{"tags":["Documents"],"summary":"Read a document","description":"Returns the document's chunks in reading order, about `max_chars` characters per page. Use it for tables and matrices, which search returns only in part.","operationId":"read_document_workspaces__workspace_id__documents__document_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}},{"name":"max_chars","in":"query","required":false,"schema":{"type":"integer","maximum":60000,"minimum":2000,"default":18000,"title":"Max Chars"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentContent"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workspaces/{workspace_id}/search":{"post":{"tags":["Search"],"summary":"Search documents","description":"Hybrid (semantic + keyword) search. Returns the most relevant chunks, best first.","operationId":"search_workspaces__workspace_id__search_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResults"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workspaces/{workspace_id}/entities":{"get":{"tags":["Knowledge graph"],"summary":"List entities","description":"With `q`: the best matches by name and meaning (at most 25, no further page). Without: every entity, ordered by type then name.","operationId":"list_entities_workspaces__workspace_id__entities_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search by name or meaning.","title":"Q"},"description":"Search by name or meaning."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only entities of this type.","title":"Type"},"description":"Only entities of this type."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Entity_"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workspaces/{workspace_id}/entities/{entity_id}":{"get":{"tags":["Knowledge graph"],"summary":"Get an entity","description":"An entity of the knowledge graph and its relations.","operationId":"get_entity_workspaces__workspace_id__entities__entity_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Entity Id"}},{"name":"depth","in":"query","required":false,"schema":{"type":"integer","maximum":2,"minimum":1,"description":"1 = direct relations, 2 = also theirs.","default":1,"title":"Depth"},"description":"1 = direct relations, 2 = also theirs."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNeighborhood"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workspaces/{workspace_id}/themes":{"get":{"tags":["Knowledge graph"],"summary":"Get main themes","description":"The workspace's main entities and entity types.","operationId":"themes_workspaces__workspace_id__themes_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of top entities.","default":15,"title":"Limit"},"description":"Number of top entities."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Themes"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workspaces/{workspace_id}/scopes":{"get":{"tags":["Search"],"summary":"List sub-scopes","description":"Named subsets of the workspace's documents; pass a name as `scope` to search.","operationId":"scopes_workspaces__workspace_id__scopes_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Scope_"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workspaces/{workspace_id}/ask":{"post":{"tags":["Ask"],"summary":"Ask a question","description":"Soma's agent searches the workspace (documents and knowledge graph) as many times as it needs, then answers in markdown with `[N]` markers; `citations` gives the passage behind each N. An answer takes 10 to 120 seconds; use `stream` to follow progress.","operationId":"ask_workspaces__workspace_id__ask_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"404":{"description":"Unknown workspace or thread.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Hourly question limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workspaces/{workspace_id}/files":{"post":{"tags":["Documents"],"summary":"Upload files","description":"PDF, Word, PowerPoint, Excel, CSV, Markdown, text and images. Files are parsed and indexed in the background: poll the returned job with GET /v1/jobs/{job_id}. Up to 20 files per request.","operationId":"upload_files_workspaces__workspace_id__files_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_files_workspaces__workspace_id__files_post"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"403":{"description":"Read-only token, or not allowed in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"A file is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/jobs/{job_id}":{"get":{"tags":["Documents"],"summary":"Get an upload job","operationId":"get_job_jobs__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/Job"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Answer":{"properties":{"thread_id":{"type":"string","title":"Thread Id"},"answer":{"type":"string","title":"Answer","description":"Markdown, with `[N]` citation markers."},"citations":{"items":{"$ref":"#/components/schemas/Citation"},"type":"array","title":"Citations","description":"The passages the answer cites."}},"type":"object","required":["thread_id","answer","citations"],"title":"Answer"},"AskRequest":{"properties":{"question":{"type":"string","maxLength":8000,"minLength":1,"title":"Question"},"thread_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Thread Id","description":"Continue this thread (from a previous answer)."},"stream":{"type":"boolean","title":"Stream","description":"Stream Server-Sent Events: `step` while the agent works, then `answer` (the same body as a non-streamed response), or `error`.","default":false}},"type":"object","required":["question"],"title":"AskRequest"},"Body":{"properties":{"type":{"type":"string","title":"Type"},"message":{"type":"string","title":"Message"}},"type":"object","required":["type","message"],"title":"Body"},"Body_upload_files_workspaces__workspace_id__files_post":{"properties":{"files":{"items":{"type":"string","contentMediaType":"application/octet-stream"},"type":"array","title":"Files","description":"One or more files."}},"type":"object","required":["files"],"title":"Body_upload_files_workspaces__workspace_id__files_post"},"Chunk":{"properties":{"id":{"type":"string","title":"Id"},"document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Id"},"document_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Title"},"text":{"type":"string","title":"Text"},"type":{"type":"string","title":"Type","description":"text, table or figure.","default":"text"},"page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"Link to the original, when it has one."}},"type":"object","required":["id","text"],"title":"Chunk"},"Citation":{"properties":{"number":{"type":"integer","title":"Number","description":"The N of the `[N]` markers in the answer."},"chunk_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chunk Id"},"document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Id"},"document_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Title"},"page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"text":{"type":"string","title":"Text","description":"The cited passage (up to 1,500 characters)."}},"type":"object","required":["number","text"],"title":"Citation"},"Document":{"properties":{"id":{"type":"string","title":"Id"},"title":{"type":"string","title":"Title"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider","description":"gdrive, notion, github, upload…"},"chunk_count":{"type":"integer","title":"Chunk Count"},"has_tables":{"type":"boolean","title":"Has Tables"}},"type":"object","required":["id","title","chunk_count","has_tables"],"title":"Document"},"DocumentContent":{"properties":{"id":{"type":"string","title":"Id"},"title":{"type":"string","title":"Title"},"total_chunks":{"type":"integer","title":"Total Chunks"},"chunks":{"items":{"$ref":"#/components/schemas/Chunk"},"type":"array","title":"Chunks"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["id","title","total_chunks","chunks","has_more"],"title":"DocumentContent"},"Entity":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases"},"mention_count":{"type":"integer","title":"Mention Count"}},"type":"object","required":["id","name","type","mention_count"],"title":"Entity"},"EntityNeighborhood":{"properties":{"entity":{"$ref":"#/components/schemas/EntityRef"},"depth":{"type":"integer","title":"Depth"},"outgoing":{"items":{"$ref":"#/components/schemas/Relation"},"type":"array","title":"Outgoing","description":"Relations from this entity to others."},"incoming":{"items":{"$ref":"#/components/schemas/Relation"},"type":"array","title":"Incoming","description":"Relations from others to this entity."}},"type":"object","required":["entity","depth","outgoing","incoming"],"title":"EntityNeighborhood"},"EntityRef":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"}},"type":"object","required":["id","name"],"title":"EntityRef"},"Error":{"properties":{"error":{"$ref":"#/components/schemas/Body"}},"type":"object","required":["error"],"title":"Error"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Job":{"properties":{"id":{"type":"string","title":"Id"},"status":{"type":"string","enum":["queued","running","done"],"title":"Status"},"files":{"items":{"$ref":"#/components/schemas/JobFile"},"type":"array","title":"Files"}},"type":"object","required":["id","status","files"],"title":"Job"},"JobFile":{"properties":{"filename":{"type":"string","title":"Filename"},"status":{"type":"string","enum":["queued","running","done","error"],"title":"Status"},"document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Id","description":"Set once the file is ingested."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["filename","status"],"title":"JobFile"},"Me":{"properties":{"id":{"type":"string","title":"Id"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Null for an API key."},"auth":{"type":"string","enum":["session","oauth","api_key"],"title":"Auth"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"workspace_count":{"type":"integer","title":"Workspace Count"}},"type":"object","required":["id","auth","scopes","workspace_count"],"title":"Me"},"Page_Document_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Document"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"Whether another page follows."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as `cursor` to get the next page."}},"type":"object","required":["data","has_more"],"title":"Page[Document]"},"Page_Entity_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Entity"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"Whether another page follows."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as `cursor` to get the next page."}},"type":"object","required":["data","has_more"],"title":"Page[Entity]"},"Page_Scope_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Scope"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"Whether another page follows."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as `cursor` to get the next page."}},"type":"object","required":["data","has_more"],"title":"Page[Scope]"},"Page_Workspace_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Workspace"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"Whether another page follows."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as `cursor` to get the next page."}},"type":"object","required":["data","has_more"],"title":"Page[Workspace]"},"Relation":{"properties":{"type":{"type":"string","title":"Type"},"evidence_count":{"type":"integer","title":"Evidence Count"},"entity":{"$ref":"#/components/schemas/EntityRef","description":"The entity at the other end."}},"type":"object","required":["type","evidence_count","entity"],"title":"Relation"},"Scope":{"properties":{"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"document_count":{"type":"integer","title":"Document Count"},"ready":{"type":"boolean","title":"Ready"}},"type":"object","required":["name","document_count","ready"],"title":"Scope"},"SearchRequest":{"properties":{"query":{"type":"string","maxLength":2000,"minLength":1,"title":"Query"},"limit":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Limit","description":"Number of chunks to return.","default":10},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope","description":"Name of a sub-scope of the workspace to search in (see /scopes)."},"entity_ids":{"items":{"type":"string"},"type":"array","title":"Entity Ids","description":"Only return chunks that mention one of these knowledge-graph entities."}},"type":"object","required":["query"],"title":"SearchRequest"},"SearchResults":{"properties":{"query":{"type":"string","title":"Query"},"data":{"items":{"$ref":"#/components/schemas/Chunk"},"type":"array","title":"Data"}},"type":"object","required":["query","data"],"title":"SearchResults"},"Themes":{"properties":{"total_entities":{"type":"integer","title":"Total Entities"},"types":{"items":{"$ref":"#/components/schemas/TypeCount"},"type":"array","title":"Types"},"top_entities":{"items":{"$ref":"#/components/schemas/Entity"},"type":"array","title":"Top Entities"}},"type":"object","required":["total_entities","types","top_entities"],"title":"Themes"},"TypeCount":{"properties":{"type":{"type":"string","title":"Type"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["type","count"],"title":"TypeCount"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"Workspace":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"ready":{"type":"boolean","title":"Ready","description":"Whether the knowledge base can be queried."},"document_count":{"type":"integer","title":"Document Count","description":"Documents in the knowledge base."},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","name","ready","document_count","created_at"],"title":"Workspace"},"WorkspaceCreate":{"properties":{"name":{"type":"string","maxLength":256,"minLength":1,"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Description"}},"type":"object","required":["name"],"title":"WorkspaceCreate"},"WorkspaceUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Description"}},"type":"object","title":"WorkspaceUpdate"}},"securitySchemes":{"HTTPBearer":{"type":"http","description":"An OAuth access token (`soma_at_…`) or an API key (`scribe_mcp_…`).","scheme":"bearer"}}}}