{"openapi":"3.1.0","info":{"title":"Orcha API","version":"1.0.0","description":"Token-authenticated REST API for AI agents: files, folders, memories, retrieval, filesystem-shaped access, ingestion, directory sync, structured databases, and feedback. Authenticate with an `orca_` API token created on the Tokens page; the token is scoped to one workspace and to `read`/`write`/`delete` permissions capped at the owner's live workspace role. Every request counts against per-token minute/hour/day rate-limit windows reported in `X-RateLimit-*` headers.","contact":{"name":"Orcha","url":"https://tryorcha.com"}},"servers":[{"url":"https://app.tryorcha.com","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Files","description":"Workspace file management"},{"name":"Folders","description":"Workspace folder management"},{"name":"Memories","description":"Curated context sets agents load whole"},{"name":"Retrieval","description":"Hybrid search and connected-source access"},{"name":"Filesystem","description":"Read-only filesystem-shaped VFS access"},{"name":"Ingestion","description":"External document ingestion and indexing"},{"name":"Directory sync","description":"Manifest-based directory synchronization"},{"name":"Structured databases","description":"Typed databases, records, fields, and views"},{"name":"Feedback","description":"Agent feedback to workspace maintainers"}],"paths":{"/api/v1/files":{"get":{"operationId":"listFiles","tags":["Files"],"summary":"List files","description":"Returns all files accessible to the token within its workspace, without content bodies.\n\nPermission required: `read`.","parameters":[{"name":"folderId","in":"query","required":false,"description":"Filter files by folder ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Files","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/File"}}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createFile","tags":["Files"],"summary":"Create a file","description":"Create a file\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileCreate"}}}},"responses":{"201":{"description":"Created file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/files/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"File ID","schema":{"type":"string"}}],"get":{"operationId":"getFile","tags":["Files"],"summary":"Get a file","description":"Returns a specific file including its content.\n\nPermission required: `read`.","responses":{"200":{"description":"File","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateFile","tags":["Files"],"summary":"Update a file","description":"Updates name, content, folder, or tags. Only provided fields are updated; ownership and workspace scope are immutable.\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileUpdate"}}}},"responses":{"200":{"description":"Updated file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteFile","tags":["Files"],"summary":"Delete a file","description":"Moves the file to trash (soft delete); it can be restored from the Trash page.\n\nPermission required: `delete`.","responses":{"204":{"description":"File moved to trash"},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/files/{id}/raw":{"parameters":[{"name":"id","in":"path","required":true,"description":"File ID","schema":{"type":"string"}}],"get":{"operationId":"getFileRaw","tags":["Files"],"summary":"Download raw file content","description":"Returns the raw body with a Content-Type matching the file type: text/markdown, application/json, text/yaml, or text/plain.\n\nPermission required: `read`.","responses":{"200":{"description":"Raw file body","content":{"text/markdown":{"schema":{"type":"string"}},"application/json":{"schema":{}},"text/yaml":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/folders":{"get":{"operationId":"listFolders","tags":["Folders"],"summary":"List folders","description":"List folders\n\nPermission required: `read`.","parameters":[{"name":"parentId","in":"query","required":false,"description":"Filter by parent folder ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Folders","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Folder"}}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createFolder","tags":["Folders"],"summary":"Create a folder","description":"Create a folder\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderCreate"}}}},"responses":{"201":{"description":"Created folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Folder"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/folders/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Folder ID","schema":{"type":"string"}}],"get":{"operationId":"getFolder","tags":["Folders"],"summary":"Get a folder","description":"Get a folder\n\nPermission required: `read`.","responses":{"200":{"description":"Folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Folder"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateFolder","tags":["Folders"],"summary":"Update a folder","description":"Updates name or parent. Moves are validated against the same workspace and cycles are rejected.\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderUpdate"}}}},"responses":{"200":{"description":"Updated folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Folder"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteFolder","tags":["Folders"],"summary":"Delete a folder","description":"Moves the folder and its contents to trash (soft delete).\n\nPermission required: `delete`.","responses":{"204":{"description":"Folder moved to trash"},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/folders/{id}/files":{"parameters":[{"name":"id","in":"path","required":true,"description":"Folder ID","schema":{"type":"string"}}],"get":{"operationId":"listFolderFiles","tags":["Folders"],"summary":"List files in a folder","description":"Returns files in the folder, including subfolders by default.\n\nPermission required: `read`.","parameters":[{"name":"recursive","in":"query","required":false,"description":"Set to false to exclude subfolder files (default true)","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Files","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/File"}}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/folders/{id}/subfolders":{"parameters":[{"name":"id","in":"path","required":true,"description":"Folder ID","schema":{"type":"string"}}],"get":{"operationId":"listSubfolders","tags":["Folders"],"summary":"List direct subfolders","description":"List direct subfolders\n\nPermission required: `read`.","responses":{"200":{"description":"Folders","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Folder"}}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memories":{"get":{"operationId":"listMemories","tags":["Memories"],"summary":"List memories","description":"List memories\n\nPermission required: `read`.","responses":{"200":{"description":"Memories","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Memory"}}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createMemory","tags":["Memories"],"summary":"Create a memory","description":"Creates a memory, optionally with an initial `members` array.\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryCreate"}}}},"responses":{"201":{"description":"Created memory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Memory"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memories/{idOrSlug}":{"parameters":[{"name":"idOrSlug","in":"path","required":true,"description":"Memory ID or slug for GET; PATCH and DELETE require the memory ID","schema":{"type":"string"}}],"get":{"operationId":"getMemory","tags":["Memories"],"summary":"Get a memory with resolved members","description":"Returns the memory with members resolved to current contents plus coverage notes for gaps, truncation, and scope exclusions.\n\nPermission required: `read`.","responses":{"200":{"description":"Resolved memory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryResolved"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateMemory","tags":["Memories"],"summary":"Update a memory","description":"Updates name, slug, description, `useWhen`, or `isPublic`. Addressed by memory ID.\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryUpdate"}}}},"responses":{"200":{"description":"Updated memory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Memory"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteMemory","tags":["Memories"],"summary":"Delete a memory","description":"Deletes the memory; its members' targets are untouched. Addressed by memory ID.\n\nPermission required: `delete`.","responses":{"204":{"description":"Memory deleted"},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memories/{id}/members":{"parameters":[{"name":"id","in":"path","required":true,"description":"Memory ID","schema":{"type":"string"}}],"post":{"operationId":"addMemoryMembers","tags":["Memories"],"summary":"Add memory members","description":"Add memory members\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["members"],"properties":{"members":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/MemoryMemberInput"}}}}}}},"responses":{"201":{"description":"The members that were added","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MemoryMember"}}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memories/{id}/members/{memberId}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Memory ID","schema":{"type":"string"}},{"name":"memberId","in":"path","required":true,"description":"Member ID","schema":{"type":"string"}}],"delete":{"operationId":"removeMemoryMember","tags":["Memories"],"summary":"Remove a memory member","description":"Remove a memory member\n\nPermission required: `delete`.","responses":{"204":{"description":"Member removed"},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/memories/{slug}/export":{"parameters":[{"name":"slug","in":"path","required":true,"description":"Memory slug","schema":{"type":"string"}}],"get":{"operationId":"exportMemory","tags":["Memories"],"summary":"Export a memory","description":"Exports memory metadata plus resolved member contents. This is the one endpoint that accepts an unauthenticated request, and only for a memory explicitly marked `isPublic`; an unauthenticated export serves file and folder members only, excluding connected-source and database members with a coverage note.\n\nPermission required: `read`.","responses":{"200":{"description":"Memory export","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryResolved"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{}]}},"/api/v1/search_context":{"post":{"operationId":"searchContext","tags":["Retrieval"],"summary":"Search workspace context","description":"Returns ranked, workspace-scoped chunks with source citations using keyword, semantic, or hybrid retrieval, optional typed sub-queries, and fast/balanced/fresh source routing.\n\nPermission required: `read`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/sources/{sourceId}/query":{"parameters":[{"name":"sourceId","in":"path","required":true,"description":"Connected source ID","schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"querySource","tags":["Retrieval"],"summary":"Query a single connected source","description":"Queries exactly one connected source: retained content first, then the provider's live-search path or catalog with a bounded live fetch, under the connection's daily provider budget. Folder-scoped tokens cannot use this endpoint.\n\nPermission required: `read`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceQueryRequest"}}}},"responses":{"200":{"description":"Source query results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceQueryResponse"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/sources/{sourceId}/documents/{externalId}":{"parameters":[{"name":"sourceId","in":"path","required":true,"description":"Connected source ID","schema":{"type":"string","format":"uuid"}},{"name":"externalId","in":"path","required":true,"description":"Provider-native document ID","schema":{"type":"string"}}],"get":{"operationId":"fetchSourceDocument","tags":["Retrieval"],"summary":"Fetch a source document","description":"Returns one connected-source document's full body, from the index (`origin: \"indexed\"`) or fetched live under the daily budget (`origin: \"live\"`, not persisted). Folder-scoped tokens cannot use this endpoint.\n\nPermission required: `read`.","responses":{"200":{"description":"Source document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceDocumentResponse"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vfs/exec":{"post":{"operationId":"execVfsScript","tags":["Filesystem"],"summary":"Execute a read-only VFS script","description":"Runs a filesystem-shaped script against a virtual tree of the token's workspace (/files, /memories, /databases, /sources). Bounded by a scan budget and an output cap; the surface is read-only by construction. This endpoint backs the orcha CLI and the browse_context MCP tool.\n\nPermission required: `read`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VfsExecRequest"}}}},"responses":{"200":{"description":"Script output with citations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VfsExecResponse"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/ingest":{"post":{"operationId":"ingestDocument","tags":["Ingestion"],"summary":"Ingest a document","description":"Validates and queues non-Orcha source content for indexing. New work returns 202; an identical idempotency-key replay returns 200 with `deduplicated: true`; reusing the key with different content returns 409.\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestRequest"}}}},"responses":{"200":{"description":"Deduplicated replay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestStatus"}}}},"202":{"description":"Accepted for indexing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestStatus"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key reused with different content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/ingest/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Ingested document ID","schema":{"type":"string"}}],"get":{"operationId":"getIngestStatus","tags":["Ingestion"],"summary":"Get ingestion status","description":"Get ingestion status\n\nPermission required: `read`.","responses":{"200":{"description":"Ingestion status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestStatus"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/sync/preview":{"post":{"operationId":"previewSync","tags":["Directory sync"],"summary":"Preview a directory sync","description":"Creates a run in ready state without writing content and returns it with a `wouldPrune` list. Requires a workspace-wide token; folder-scoped tokens are rejected.\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncPreviewRequest"}}}},"responses":{"201":{"description":"Preview run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncRun"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/sync/{runId}":{"parameters":[{"name":"runId","in":"path","required":true,"description":"Sync run ID","schema":{"type":"string"}}],"get":{"operationId":"getSyncRun","tags":["Directory sync"],"summary":"Get sync run status","description":"Get sync run status\n\nPermission required: `read`.","responses":{"200":{"description":"Sync run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncRun"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSyncRun","tags":["Directory sync"],"summary":"Delete a sync run","description":"Removes the run and its stored manifest snapshot; synced content is untouched, but deleting a completed run forfeits its rollback. Busy runs return 409.\n\nPermission required: `write`.","responses":{"204":{"description":"Run deleted"},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Run is busy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/sync/{runId}/start":{"parameters":[{"name":"runId","in":"path","required":true,"description":"Sync run ID","schema":{"type":"string"}}],"post":{"operationId":"startSyncRun","tags":["Directory sync"],"summary":"Start a sync run","description":"Re-checks plan limits, then queues the run. Returns 403 with `error: \"LIMIT_EXCEEDED\"` when the run exceeds plan limits, or 409 when the run is not startable.\n\nPermission required: `write`.","responses":{"202":{"description":"Run queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncRun"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Run is not in a startable state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/feedback":{"post":{"operationId":"submitFeedback","tags":["Feedback"],"summary":"Submit agent feedback","description":"Sends feedback about the workspace's context to its maintainers through the product feedback pipeline; nothing is stored in the workspace. A 502 means an email provider is configured but delivery failed.\n\nPermission required: `read`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackRequest"}}}},"responses":{"200":{"description":"Feedback sent","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Feedback delivery failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases":{"get":{"operationId":"listDatabases","tags":["Structured databases"],"summary":"List databases","description":"List databases\n\nPermission required: `read`.","responses":{"200":{"description":"Databases","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StructuredDatabase"}}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createDatabase","tags":["Structured databases"],"summary":"Create a database","description":"Creates a database with a primary Name property and a default table view.\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"folderId":{"type":["string","null"]}},"additionalProperties":true}}}},"responses":{"201":{"description":"Created database","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredDatabase"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/trash":{"get":{"operationId":"listTrashedDatabases","tags":["Structured databases"],"summary":"List trashed databases","description":"List trashed databases\n\nPermission required: `read`.","responses":{"200":{"description":"Trashed databases","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StructuredDatabase"}}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{databaseId}":{"parameters":[{"name":"databaseId","in":"path","required":true,"description":"Database ID","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getDatabase","tags":["Structured databases"],"summary":"Get a database","description":"Returns schema, fields, views, and record count.\n\nPermission required: `read`.","responses":{"200":{"description":"Database","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredDatabase"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateDatabase","tags":["Structured databases"],"summary":"Update a database","description":"Updates name, description, icon, or folder.\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":["string","null"]},"icon":{"type":["string","null"]},"folderId":{"type":["string","null"]}},"additionalProperties":true}}}},"responses":{"200":{"description":"Updated database","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredDatabase"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteDatabase","tags":["Structured databases"],"summary":"Delete a database","description":"Moves the database to trash (soft delete).\n\nPermission required: `delete`.","responses":{"204":{"description":"Database moved to trash"},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{databaseId}/restore":{"parameters":[{"name":"databaseId","in":"path","required":true,"description":"Database ID","schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"restoreDatabase","tags":["Structured databases"],"summary":"Restore a database from trash","description":"Restore a database from trash\n\nPermission required: `delete`.","responses":{"200":{"description":"Restored database","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredDatabase"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{databaseId}/permanent":{"parameters":[{"name":"databaseId","in":"path","required":true,"description":"Database ID","schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"permanentlyDeleteDatabase","tags":["Structured databases"],"summary":"Permanently delete a trashed database","description":"Permanently delete a trashed database\n\nPermission required: `delete`.","responses":{"204":{"description":"Database permanently deleted"},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{databaseId}/records":{"parameters":[{"name":"databaseId","in":"path","required":true,"description":"Database ID","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listDatabaseRecords","tags":["Structured databases"],"summary":"List records","description":"Search, sort, filter, target a citation recordId, and paginate records. Filter operators are contains, equals, not_equals, is_empty, and is_not_empty.\n\nPermission required: `read`.","parameters":[{"name":"recordId","in":"query","required":false,"description":"Return the page containing this record","schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","required":false,"description":"Free-text search across record values","schema":{"type":"string"}},{"name":"sortFieldId","in":"query","required":false,"description":"Field UUID to sort by","schema":{"type":"string"}},{"name":"sortDirection","in":"query","required":false,"description":"asc or desc","schema":{"type":"string","enum":["asc","desc"]}},{"name":"filterFieldId","in":"query","required":false,"description":"Field UUID to filter on","schema":{"type":"string"}},{"name":"filterOperator","in":"query","required":false,"description":"Filter operator","schema":{"type":"string","enum":["contains","equals","not_equals","is_empty","is_not_empty"]}},{"name":"filterValue","in":"query","required":false,"description":"Filter comparison value","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size (max 200)","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"offset","in":"query","required":false,"description":"Pagination offset","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Records page","content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/DatabaseRecord"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"additionalProperties":true}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createDatabaseRecord","tags":["Structured databases"],"summary":"Create a record","description":"Create a record\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseRecordInput"}}}},"responses":{"201":{"description":"Created record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseRecord"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{databaseId}/records/{recordId}":{"parameters":[{"name":"databaseId","in":"path","required":true,"description":"Database ID","schema":{"type":"string","format":"uuid"}},{"name":"recordId","in":"path","required":true,"description":"Record ID","schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateDatabaseRecord","tags":["Structured databases"],"summary":"Update a record","description":"Merges values and saves a record version.\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseRecordInput"}}}},"responses":{"200":{"description":"Updated record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseRecord"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteDatabaseRecord","tags":["Structured databases"],"summary":"Delete a record","description":"Moves the record to trash (soft delete).\n\nPermission required: `delete`.","responses":{"204":{"description":"Record moved to trash"},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{databaseId}/records/{recordId}/restore":{"parameters":[{"name":"databaseId","in":"path","required":true,"description":"Database ID","schema":{"type":"string","format":"uuid"}},{"name":"recordId","in":"path","required":true,"description":"Record ID","schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"restoreDatabaseRecord","tags":["Structured databases"],"summary":"Restore a record from trash","description":"Restore a record from trash\n\nPermission required: `write`.","responses":{"200":{"description":"Restored record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseRecord"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{databaseId}/records/{recordId}/permanent":{"parameters":[{"name":"databaseId","in":"path","required":true,"description":"Database ID","schema":{"type":"string","format":"uuid"}},{"name":"recordId","in":"path","required":true,"description":"Record ID","schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"permanentlyDeleteDatabaseRecord","tags":["Structured databases"],"summary":"Permanently delete a trashed record","description":"Permanently delete a trashed record\n\nPermission required: `delete`.","responses":{"204":{"description":"Record permanently deleted"},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{databaseId}/records/{recordId}/versions":{"parameters":[{"name":"databaseId","in":"path","required":true,"description":"Database ID","schema":{"type":"string","format":"uuid"}},{"name":"recordId","in":"path","required":true,"description":"Record ID","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listDatabaseRecordVersions","tags":["Structured databases"],"summary":"List record versions","description":"List record versions\n\nPermission required: `read`.","responses":{"200":{"description":"Record versions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{databaseId}/fields":{"parameters":[{"name":"databaseId","in":"path","required":true,"description":"Database ID","schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"createDatabaseField","tags":["Structured databases"],"summary":"Add a typed field","description":"Add a typed field\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseFieldInput"}}}},"responses":{"201":{"description":"Created field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseField"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{databaseId}/fields/{fieldId}":{"parameters":[{"name":"databaseId","in":"path","required":true,"description":"Database ID","schema":{"type":"string","format":"uuid"}},{"name":"fieldId","in":"path","required":true,"description":"Field ID","schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateDatabaseField","tags":["Structured databases"],"summary":"Update a field","description":"Update a field\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseFieldInput"}}}},"responses":{"200":{"description":"Updated field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseField"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteDatabaseField","tags":["Structured databases"],"summary":"Delete a non-primary field","description":"Delete a non-primary field\n\nPermission required: `delete`.","responses":{"204":{"description":"Field deleted"},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{databaseId}/views":{"parameters":[{"name":"databaseId","in":"path","required":true,"description":"Database ID","schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"createDatabaseView","tags":["Structured databases"],"summary":"Create a saved view","description":"Create a saved view\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"type":{"type":"string","default":"table"},"config":{"type":"object","additionalProperties":true}},"additionalProperties":true}}}},"responses":{"201":{"description":"Created view","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseView"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{databaseId}/views/{viewId}":{"parameters":[{"name":"databaseId","in":"path","required":true,"description":"Database ID","schema":{"type":"string","format":"uuid"}},{"name":"viewId","in":"path","required":true,"description":"View ID","schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateDatabaseView","tags":["Structured databases"],"summary":"Update a saved view","description":"Update a saved view\n\nPermission required: `write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"config":{"type":"object","additionalProperties":true}},"additionalProperties":true}}}},"responses":{"200":{"description":"Updated view","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseView"}}}},"400":{"description":"Invalid request body or parameters; `errors` carries the validation issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteDatabaseView","tags":["Structured databases"],"summary":"Delete a saved view","description":"Delete a saved view\n\nPermission required: `delete`.","responses":{"204":{"description":"View deleted"},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/files/{fileId}/database-backlinks":{"parameters":[{"name":"fileId","in":"path","required":true,"description":"File ID","schema":{"type":"string"}}],"get":{"operationId":"listFileDatabaseBacklinks","tags":["Structured databases"],"summary":"List database records referencing a file","description":"List database records referencing a file\n\nPermission required: `read`.","responses":{"200":{"description":"Backlinking records","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"401":{"description":"Missing, invalid, expired, or deactivated API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token lacks the required permission or the resource is outside its scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in the token's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A per-token rate-limit window is exhausted; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Orcha API token, prefixed `orca_`. Shown once at creation; only a hashed verifier is stored."}},"schemas":{"Error":{"type":"object","description":"Standard error body. `errors` appears on validation failures; `code` appears when the failing operation exposes a machine-readable cause.","required":["message"],"properties":{"message":{"type":"string"},"code":{"type":"string"},"errors":{"type":"array","description":"Validation issues (Zod issue objects)","items":{"type":"object"}}},"additionalProperties":true},"File":{"type":"object","description":"A workspace file. List responses omit `content`; single-file responses include it.","required":["id","name","fileType","workspaceId"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"content":{"type":"string"},"fileType":{"type":"string","enum":["markdown","json","yaml","text"]},"folderId":{"type":["string","null"]},"workspaceId":{"type":"string"},"tags":{"type":["array","null"],"items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"FileCreate":{"type":"object","required":["name","content","fileType"],"properties":{"name":{"type":"string"},"content":{"type":"string"},"fileType":{"type":"string","enum":["markdown","json","yaml","text"]},"folderId":{"type":["string","null"],"description":"Parent folder ID; null or omitted for root"},"tags":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"FileUpdate":{"type":"object","description":"All fields optional; only provided fields are updated.","properties":{"name":{"type":"string"},"content":{"type":"string"},"folderId":{"type":["string","null"]},"tags":{"type":["array","null"],"items":{"type":"string"}}},"additionalProperties":false},"Folder":{"type":"object","required":["id","name","workspaceId"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"parentId":{"type":["string","null"]},"workspaceId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"FolderCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"parentId":{"type":["string","null"],"description":"Parent folder ID; null or omitted for root"}},"additionalProperties":false},"FolderUpdate":{"type":"object","properties":{"name":{"type":"string"},"parentId":{"type":["string","null"]}},"additionalProperties":false},"Memory":{"type":"object","description":"A curated context set agents load whole instead of searching. `version` increments on every metadata or membership change.","required":["id","name","slug","version"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string","description":"Workspace-unique slug"},"description":{"type":["string","null"]},"useWhen":{"type":["string","null"],"description":"Tells an agent when this memory applies"},"isPublic":{"type":"boolean"},"version":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"MemoryMemberInput":{"type":"object","description":"One member of a memory. Exactly one of `fileId`, `folderId`, `sourceDocumentId`, or `databaseId` must match `kind`.","required":["kind"],"properties":{"kind":{"type":"string","enum":["file","folder","source_document","database"]},"fileId":{"type":"string"},"folderId":{"type":"string"},"sourceDocumentId":{"type":"string"},"databaseId":{"type":"string"},"databaseQuery":{"type":"object","description":"Optional query for database members: `search`, `filter`, `sortFieldId`, `sortDirection`, `limit`","additionalProperties":true}},"additionalProperties":true},"MemoryMember":{"type":"object","description":"A persisted memory member row as returned when members are added.","properties":{"id":{"type":"string"},"memoryId":{"type":"string"},"kind":{"type":"string","enum":["file","folder","source_document","database"]},"fileId":{"type":["string","null"]},"folderId":{"type":["string","null"]},"sourceDocumentId":{"type":["string","null"]},"databaseId":{"type":["string","null"]},"databaseQuery":{"type":["string","null"],"description":"JSON-encoded record query for database members; null means the default listing"},"addedAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"MemoryCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"slug":{"type":"string","description":"Defaults to a slug derived from the name"},"description":{"type":"string"},"useWhen":{"type":"string"},"isPublic":{"type":"boolean"},"members":{"type":"array","description":"Optional initial members","items":{"$ref":"#/components/schemas/MemoryMemberInput"}}},"additionalProperties":true},"MemoryUpdate":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"useWhen":{"type":["string","null"]},"isPublic":{"type":"boolean"}},"additionalProperties":false},"MemoryResolved":{"type":"object","description":"A memory with its members resolved to current contents plus coverage notes for gaps, truncation, and scope exclusions.","properties":{"memory":{"$ref":"#/components/schemas/Memory"},"items":{"type":"array","items":{"type":"object","additionalProperties":true}},"coverage":{"type":"array","description":"Honest notes about members that could not be fully resolved","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"Citation":{"type":"object","description":"Provenance for externally sourced content","required":["provider","objectId","deepLink"],"properties":{"provider":{"type":"string"},"objectId":{"type":"string"},"deepLink":{"type":"string","format":"uri"},"title":{"type":"string"},"author":{"type":"string"},"location":{"type":"string"},"version":{"type":"string"}},"additionalProperties":true},"SearchRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":1000,"description":"Supports websearch syntax: quoted phrases and -excluded terms"},"searches":{"type":"array","maxItems":8,"description":"Typed sub-queries fused with the original query by weighted reciprocal-rank fusion; the original query runs at double weight","items":{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["lex","vec","hyde"],"description":"lex routes to full-text search; vec and hyde to vector search (hyde is a short hypothetical answer passage)"},"text":{"type":"string","minLength":1,"maxLength":1000}}}},"strategy":{"type":"string","enum":["keyword","semantic","hybrid"],"default":"hybrid"},"mode":{"type":"string","enum":["fast","balanced","fresh"],"default":"balanced","description":"fast searches retained content only; balanced adds the connected-source catalog with bounded live fetches of decisive matches; fresh additionally consults live-mode providers"},"sourceIds":{"type":"array","maxItems":10,"items":{"type":"string","format":"uuid"},"description":"Restrict results to specific connected sources"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10},"minScore":{"type":"number","description":"Drop results scoring below this value"},"tokenBudget":{"type":"integer","description":"Pack results within an approximate token budget"},"explain":{"type":"boolean","default":false,"description":"Attach per-result score traces"}},"additionalProperties":false},"SearchResponse":{"type":"object","description":"`results` is cited evidence; `coverage` carries routing notes (live fetches, unfetched catalog matches, budget limits) and must never be quoted as content.","properties":{"results":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string"},"documentId":{"type":"string"},"fileId":{"type":["string","null"]},"score":{"type":"number"},"content":{"type":"string"},"startLine":{"type":"integer"},"endLine":{"type":"integer"},"headingPath":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":"string","format":"date-time"},"citation":{"$ref":"#/components/schemas/Citation"}},"additionalProperties":true}},"coverage":{"type":"array","items":{"type":"object","additionalProperties":true}},"mode":{"type":"string","enum":["fast","balanced","fresh"]}},"additionalProperties":true},"SourceQueryRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":1000},"limit":{"type":"integer","minimum":1,"maximum":20,"default":5}},"additionalProperties":false},"SourceQueryResponse":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","additionalProperties":true}},"coverage":{"type":"array","items":{"type":"object","additionalProperties":true}},"providerOperations":{"type":"integer"}},"additionalProperties":true},"SourceDocumentResponse":{"type":"object","properties":{"title":{"type":"string"},"content":{"type":"string"},"citation":{"$ref":"#/components/schemas/Citation"},"origin":{"type":"string","enum":["indexed","live"],"description":"indexed bodies come from the retained index; live bodies are fetched from the provider under the daily budget and not persisted"},"providerOperations":{"type":"integer"}},"additionalProperties":true},"VfsExecRequest":{"type":"object","required":["script"],"properties":{"script":{"type":"string","minLength":1,"maxLength":2000,"description":"Read-only shell-shaped script (ls, tree, find, cat, grep/rg, head, tail, wc, stat; pipes and ;/&& chaining). Write-shaped constructs are rejected."},"cwd":{"type":"string","maxLength":500,"default":"/"},"maxOutputBytes":{"type":"integer","minimum":1024,"maximum":200000,"default":60000}},"additionalProperties":false},"VfsExecResponse":{"type":"object","properties":{"output":{"type":"string"},"cwd":{"type":"string"},"truncated":{"type":"boolean"},"failed":{"type":"boolean","description":"Bash-style status: true when the last command errored or the script aborted on a parse error or budget stop"},"citations":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"entityType":{"type":"string"},"entityId":{"type":"string"},"title":{"type":"string"},"deepLink":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":true}},"budget":{"type":"object","properties":{"filesOpened":{"type":"integer"},"bytesRead":{"type":"integer"},"nodesVisited":{"type":"integer"},"exhausted":{"type":["string","null"]}},"additionalProperties":true}},"additionalProperties":true},"IngestRequest":{"type":"object","required":["idempotencyKey","title","content","mimeType"],"properties":{"idempotencyKey":{"type":"string","description":"Replaying the same key with identical content deduplicates; reusing it with different content returns 409"},"title":{"type":"string"},"content":{"type":"string","description":"Up to 5 MB"},"mimeType":{"type":"string","description":"A text MIME type such as text/markdown, text/plain, application/json, text/yaml, or text/xml"},"externalId":{"type":"string"},"externalRevision":{"type":"string"},"metadata":{"type":"object","description":"Up to 16 KB serialized","additionalProperties":true},"citation":{"$ref":"#/components/schemas/Citation"}},"additionalProperties":false},"IngestStatus":{"type":"object","properties":{"documentId":{"type":"string"},"status":{"type":"string","enum":["pending","indexing","indexed","failed"]},"contentHash":{"type":"string"},"indexedAt":{"type":["string","null"],"format":"date-time"},"citation":{"$ref":"#/components/schemas/Citation"},"error":{"type":["string","null"]},"deduplicated":{"type":"boolean"}},"additionalProperties":true},"SyncDocument":{"type":"object","required":["path","content"],"properties":{"path":{"type":"string","description":"Relative path; absolute paths, .. segments, and control characters are rejected"},"content":{"type":"string","description":"Up to 5 MB per document"},"tags":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"SyncPreviewRequest":{"type":"object","required":["name","documents"],"properties":{"name":{"type":"string","description":"Durable sync identity; later runs with the same name reconcile against earlier ones"},"conflictPolicy":{"type":"string","enum":["update","skip","duplicate"],"default":"update","description":"update applies local changes but never overwrites a file edited in Orcha since the last sync, flagging a conflict instead"},"prune":{"type":"boolean","description":"Move previously synced files absent from this manifest to trash"},"documents":{"type":"array","maxItems":5000,"items":{"$ref":"#/components/schemas/SyncDocument"},"description":"Up to 5,000 documents and 24 MB of content per run"}},"additionalProperties":true},"SyncRun":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["ready","queued","running","completed","completed_with_warnings","failed","cancelled","rolled_back"]},"counters":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"skipped":{"type":"integer"},"conflicts":{"type":"integer"},"pruned":{"type":"integer"}},"additionalProperties":true},"wouldPrune":{"type":"array","description":"Preview only: previously synced files and folders absent from this manifest that a prune pass would move to trash","items":{"type":"object","additionalProperties":true}},"warnings":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"FeedbackRequest":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":5000},"category":{"type":"string","enum":["missing_context","stale_content","wrong_result","tool_problem","other"],"default":"other"},"context":{"type":"object","description":"Structured details, e.g. the query used; must serialize to 10 KB or less","additionalProperties":true},"channel":{"type":"string","enum":["rest","cli"],"default":"rest"}},"additionalProperties":false},"StructuredDatabase":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"icon":{"type":["string","null"]},"folderId":{"type":["string","null"]},"workspaceId":{"type":"string"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/DatabaseField"}},"views":{"type":"array","items":{"type":"object","additionalProperties":true}},"recordCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"DatabaseField":{"type":"object","description":"A typed property. Record values are keyed by the field's stable UUID, so renaming a field does not break API consumers.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string","enum":["text","number","boolean","date","select","multi_select","url","relation","file_reference","asset_reference"]},"config":{"type":"object","additionalProperties":true},"isPrimary":{"type":"boolean"}},"additionalProperties":true},"DatabaseFieldInput":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["text","number","boolean","date","select","multi_select","url","relation","file_reference","asset_reference"]},"config":{"type":"object","additionalProperties":true}},"additionalProperties":true},"DatabaseRecord":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"databaseId":{"type":"string","format":"uuid"},"values":{"type":"object","description":"Keyed by field UUID","additionalProperties":true},"contentFileId":{"type":["string","null"],"description":"Optional Orcha file used as the record's editable page body"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"DatabaseRecordInput":{"type":"object","properties":{"values":{"type":"object","description":"Keyed by field UUID","additionalProperties":true},"contentFileId":{"type":["string","null"]}},"additionalProperties":true},"DatabaseView":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string"},"config":{"type":"object","additionalProperties":true}},"additionalProperties":true}}}}