{"openapi":"3.1.0","info":{"title":"Aurochs API","version":"1.0.0","description":"Multi-tenant BaaS. The **Client API** (`/w/{workspaceId}/…`) authenticates with a session cookie (web) or a bearer session token (native apps); the **Agent API** authenticates with a workspace `ak_` API key. Auth endpoints (login, device flow) are documented at `/api/auth/reference`."},"servers":[{"url":"/","description":"Same origin"}],"tags":[{"name":"Client API (user / bearer)","description":"User-authenticated, workspace in the path."},{"name":"Agent API (key)","description":"API-key-authenticated; workspace bound to the key."}],"security":[{"bearerAuth":[]},{"cookieAuth":[]},{"oauth2":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A Better Auth session token (native), an `ak_` workspace API key (agents), or an OAuth access token (connected apps — see the `oauth2` scheme)."},"cookieAuth":{"type":"apiKey","in":"cookie","name":"better-auth.session_token","description":"First-party web session cookie (sent automatically same-origin)."},"oauth2":{"type":"oauth2","description":"Third-party apps ('Connect with Aurochs'). PKCE (S256) is required. A token is bound to the ONE workspace the person picked when connecting, so use the plain endpoints (/pages, /databases, …) exactly as an API key does — no workspace goes in the URL, and GET /workspace tells you which one you're in. Effective permission is the weaker of that person's role and the granted scope. Request `offline_access` for a refresh token. (MCP clients are account-wide instead and use /api/mcp; such tokens are rejected here.)","flows":{"authorizationCode":{"authorizationUrl":"/api/auth/oauth2/authorize","tokenUrl":"/api/auth/oauth2/token","refreshUrl":"/api/auth/oauth2/token","scopes":{"read":"View pages, tables, records and files.","write":"Create, edit and delete content.","admin":"Manage workspace settings and members (first-party apps only).","offline_access":"Receive a refresh token so access survives expiry."}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Node":{"type":"object","description":"A node: kind is page | database | row.","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["page","database","row"]},"parent_id":{"type":["string","null"]},"title":{"type":"string"},"icon":{"type":["string","null"]},"cover":{"type":["string","null"]},"position":{"type":"string"},"is_system":{"type":"boolean"},"schema":{"type":"array","items":{"type":"object"},"description":"Field defs (databases)."},"views":{"type":"array","items":{"type":"object"},"description":"Saved views (databases)."},"properties":{"type":"object","description":"Typed values keyed by field id (rows)."},"has_body":{"type":"boolean"},"created_by":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"Workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"icon":{"type":["string","null"]},"role":{"type":["string","null"],"enum":["viewer","editor","owner",null]}}},"Nav":{"type":"object","properties":{"workspace":{"$ref":"#/components/schemas/Workspace"},"pages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"icon":{"type":["string","null"]},"parent_id":{"type":["string","null"]}}}},"databases":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}}}},"favorites":{"type":"array","items":{"$ref":"#/components/schemas/Favorite"}}}},"Favorite":{"type":"object","properties":{"node_id":{"type":"string"},"title":{"type":"string"},"icon":{"type":["string","null"]},"kind":{"type":"string","enum":["page","database","row"]}}},"Share":{"type":"object","properties":{"node_id":{"type":"string"},"token":{"type":"string"},"url":{"type":"string"},"created_at":{"type":"string"}}},"SyncGrant":{"type":"object","description":"Token + origin to open the node's collaborative Yjs `/doc` socket.","properties":{"configured":{"type":"boolean"},"origin":{"type":"string"},"token":{"type":"string"},"user":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"}}}}},"BusGrant":{"type":"object","description":"Token + origin to subscribe to workspace realtime invalidations.","properties":{"configured":{"type":"boolean"},"origin":{"type":"string"},"token":{"type":"string"},"workspace_id":{"type":"string"}}},"Me":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"image":{"type":["string","null"]}}},"workspaces":{"type":"array","items":{"$ref":"#/components/schemas/Workspace"}}}},"PushDevice":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string","enum":["web","ios","macos"]},"endpoint":{"type":"string"},"user_agent":{"type":["string","null"]},"created_at":{"type":"string"}}},"PushDeviceInput":{"type":"object","required":["platform","endpoint"],"properties":{"platform":{"type":"string","enum":["web","ios","macos"]},"endpoint":{"type":"string","description":"APNs hex device token (ios/macos) or push service URL (web)."},"keys":{"type":"object","description":"Web push encryption keys. Required for `web`, omitted otherwise.","properties":{"p256dh":{"type":"string"},"auth":{"type":"string"}}},"user_agent":{"type":["string","null"]}}},"PageNode":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"parent_page_id":{"type":["string","null"]},"icon":{"type":["string","null"]},"updated_at":{"type":"string"}}},"Database":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"icon":{"type":["string","null"]},"is_system":{"type":"boolean"},"schema":{"type":"array","items":{"type":"object"}},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"Record":{"type":"object","properties":{"record_id":{"type":"string"},"database_id":{"type":["string","null"]},"properties":{"type":"object"},"position":{"type":"string"},"created_by":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"EndUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":["string","null"]},"provider":{"type":["string","null"]},"verified":{"type":"boolean"},"properties":{"type":"object"},"created_at":{"type":"string"},"last_seen_at":{"type":["string","null"]}}},"File":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mime":{"type":"string"},"size_bytes":{"type":"integer"},"visibility":{"type":"string","enum":["public","signed"]},"uploaded_by":{"type":["string","null"]},"created_at":{"type":"string"},"url":{"type":"string"}}},"Activity":{"type":"object","properties":{"id":{"type":"string"},"actor":{"type":"string"},"action":{"type":"string"},"target_type":{"type":["string","null"]},"target_id":{"type":["string","null"]},"detail":{"type":"object"},"created_at":{"type":"string"}}},"Member":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"role":{"type":"string","enum":["owner","editor","viewer"]},"joined_at":{"type":"string"}}},"NodeGrant":{"type":"object","properties":{"email":{"type":"string"},"role":{"type":"string","enum":["viewer","editor"]}}},"Comment":{"type":"object","description":"A message in a thread. `author` is the byline — whose name renders — while `actor` and `client_id` are the audit trail: who actually made the request. They differ when an app posts under its own name, which is why both are exposed.","properties":{"id":{"type":"string"},"thread_id":{"type":"string"},"body":{"type":"string"},"mentions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["user","node"]},"id":{"type":"string"}}}},"author":{"type":"string"},"author_kind":{"type":"string","enum":["user","app","key"]},"author_name":{"type":"string"},"author_icon":{"type":["string","null"]},"author_via":{"type":["string","null"]},"author_verified":{"type":"boolean"},"actor":{"type":"string"},"client_id":{"type":["string","null"]},"reactions":{"type":"array","items":{"type":"object","properties":{"emoji":{"type":"string"},"count":{"type":"integer"},"mine":{"type":"boolean"}}}},"created_at":{"type":"string"},"edited_at":{"type":["string","null"]}}},"CommentThread":{"type":"object","description":"A conversation attached to a node, or to one field of a database record (`field_id`). Comments come back in order, oldest first.","properties":{"id":{"type":"string"},"node_id":{"type":"string"},"node_title":{"type":["string","null"]},"node_kind":{"type":["string","null"]},"field_id":{"type":["string","null"]},"field_name":{"type":["string","null"]},"resolved":{"type":"boolean"},"resolved_at":{"type":["string","null"]},"resolved_by":{"type":["string","null"]},"comment_count":{"type":"integer"},"last_comment_at":{"type":"string"},"author":{"type":"string"},"author_name":{"type":"string"},"created_at":{"type":"string"},"comments":{"type":"array","items":{"$ref":"#/components/schemas/Comment"}}}},"InboxItem":{"type":"object","description":"A mention addressed to the caller. `read` is per-person.","properties":{"id":{"type":"string"},"read":{"type":"boolean"},"created_at":{"type":"string"},"thread_id":{"type":["string","null"]},"node":{"type":["object","null"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string"}}},"comment":{"$ref":"#/components/schemas/Comment"}}},"Flow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"type":"boolean"},"event":{"type":"string"},"target_node_id":{"type":["string","null"]},"target_title":{"type":["string","null"]},"node_count":{"type":"integer"},"actions":{"type":"array","items":{"type":"string"}},"has_conditions":{"type":"boolean"},"last_run_at":{"type":["string","null"]},"last_run_status":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"FlowRun":{"type":"object","properties":{"id":{"type":"string"},"flow_id":{"type":"string"},"event":{"type":"string"},"actor":{"type":"string"},"status":{"type":"string","enum":["ok","error"]},"steps":{"type":"array","items":{"type":"object","properties":{"node_id":{"type":"string"},"type":{"type":"string"},"outcome":{"type":"string","enum":["ok","error","skipped"]},"detail":{"type":["string","null"]},"ms":{"type":"integer"}}}},"started_at":{"type":"string"},"duration_ms":{"type":"integer"}}},"WorkspacePatch":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"icon":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}]}},"additionalProperties":false},"InviteMember":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"role":{"default":"editor","type":"string","enum":["owner","editor","viewer"]}},"required":["email","role"],"additionalProperties":false},"UpdateMember":{"type":"object","properties":{"role":{"type":"string","enum":["owner","editor","viewer"]}},"required":["role"],"additionalProperties":false},"CreateNodeGrant":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"role":{"default":"viewer","type":"string","enum":["viewer","editor"]}},"required":["email","role"],"additionalProperties":false},"UpdateNodeGrant":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"role":{"type":"string","enum":["viewer","editor"]}},"required":["email","role"],"additionalProperties":false},"NodePatch":{"type":"object","properties":{"title":{"type":"string","maxLength":200},"icon":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}]},"cover":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"move":{"type":"object","properties":{"parent_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"after_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"before_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]}},"required":["parent_id"],"additionalProperties":false}},"additionalProperties":false},"DatabasePatch":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":120},"type":{"type":"string","enum":["text","number","select","multi_select","date","duration","checkbox","url","file","files","relation","page_ref","person","place","formula","created_time","created_by","last_edited_time","last_edited_by"]},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":120},"color":{"type":"string","enum":["gray","red","orange","yellow","green","blue","purple","pink","brown"]}},"required":["id","name"],"additionalProperties":false}},"config":{"type":"object","properties":{"includeTime":{"type":"boolean"},"relation":{"type":"object","properties":{"databaseId":{"type":"string"}},"required":["databaseId"],"additionalProperties":false},"formula":{"type":"object","properties":{"expression":{"type":"string","maxLength":2000}},"required":["expression"],"additionalProperties":false}},"additionalProperties":false}},"required":["id","name","type"],"additionalProperties":false}},"views":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["table","board","gallery","list","feed","calendar","timeline","map","globe"]},"filter":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"op":{"type":"string","enum":["eq","contains","gt","lt"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"required":["field","op","value"],"additionalProperties":false}},"sort":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"dir":{"type":"string","enum":["asc","desc"]}},"required":["field","dir"],"additionalProperties":false}},"titleField":{"type":"string"},"groupBy":{"type":"string"},"visibleFields":{"type":"array","items":{"type":"string"}},"coverField":{"type":"string"},"dateField":{"type":"string"},"startField":{"type":"string"},"endField":{"type":"string"},"placeField":{"type":"string"}},"required":["id","name","type"],"additionalProperties":false}}},"additionalProperties":false},"CreateNode":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"page"},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"title":{"type":"string","maxLength":200},"parent_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["paragraph","heading","todo","bulleted","numbered","quote","code","math","divider","database","form","reference","file","bookmark","table","private","drawing"]},"text":{"type":"string"},"level":{"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3}]},"checked":{"type":"boolean"},"databaseId":{"type":"string"},"formConfig":{"type":"string"},"refNodeId":{"type":"string"},"refLabel":{"type":"string"},"fileId":{"type":"string"},"url":{"type":"string"},"description":{"type":"string","maxLength":2000},"runs":{"type":"array","items":{"type":"object","properties":{"insert":{"type":"string"},"marks":{"type":"object","properties":{"bold":{"type":"boolean","const":true},"italic":{"type":"boolean","const":true},"code":{"type":"boolean","const":true},"link":{"type":"string"}},"additionalProperties":false}},"required":["insert"],"additionalProperties":false}},"rows":{"type":"array","items":{"type":"array","items":{"type":"string"}}}},"additionalProperties":false}}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"database"},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"name":{"type":"string","minLength":1,"maxLength":120},"icon":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}]},"parent_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":120},"type":{"type":"string","enum":["text","number","select","multi_select","date","duration","checkbox","url","file","files","relation","page_ref","person","place","formula","created_time","created_by","last_edited_time","last_edited_by"]},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":120},"color":{"type":"string","enum":["gray","red","orange","yellow","green","blue","purple","pink","brown"]}},"required":["id","name"],"additionalProperties":false}},"config":{"type":"object","properties":{"includeTime":{"type":"boolean"},"relation":{"type":"object","properties":{"databaseId":{"type":"string"}},"required":["databaseId"],"additionalProperties":false},"formula":{"type":"object","properties":{"expression":{"type":"string","maxLength":2000}},"required":["expression"],"additionalProperties":false}},"additionalProperties":false}},"required":["id","name","type"],"additionalProperties":false}},"template":{"type":"string","maxLength":64}},"required":["kind"],"additionalProperties":false}]},"FavoriteInput":{"type":"object","properties":{"node_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["node_id"],"additionalProperties":false},"CreatePage":{"type":"object","properties":{"title":{"type":"string","maxLength":200},"icon":{"type":"string","maxLength":16},"parentId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["paragraph","heading","todo","bulleted","numbered","quote","code","math","divider","database","form","reference","file","bookmark","table","private","drawing"]},"text":{"type":"string"},"level":{"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3}]},"checked":{"type":"boolean"},"databaseId":{"type":"string"},"formConfig":{"type":"string"},"refNodeId":{"type":"string"},"refLabel":{"type":"string"},"fileId":{"type":"string"},"url":{"type":"string"},"description":{"type":"string","maxLength":2000},"runs":{"type":"array","items":{"type":"object","properties":{"insert":{"type":"string"},"marks":{"type":"object","properties":{"bold":{"type":"boolean","const":true},"italic":{"type":"boolean","const":true},"code":{"type":"boolean","const":true},"link":{"type":"string"}},"additionalProperties":false}},"required":["insert"],"additionalProperties":false}},"rows":{"type":"array","items":{"type":"array","items":{"type":"string"}}}},"additionalProperties":false}}},"additionalProperties":false},"PagePatch":{"type":"object","properties":{"title":{"type":"string","maxLength":200},"icon":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}]},"cover":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"parentId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"after":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"before":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"additionalProperties":false},"AppendBlocks":{"type":"object","properties":{"blocks":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["paragraph","heading","todo","bulleted","numbered","quote","code","math","divider","database","form","reference","file","bookmark","table","private","drawing"]},"text":{"type":"string"},"level":{"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3}]},"checked":{"type":"boolean"},"databaseId":{"type":"string"},"formConfig":{"type":"string"},"refNodeId":{"type":"string"},"refLabel":{"type":"string"},"fileId":{"type":"string"},"url":{"type":"string"},"description":{"type":"string","maxLength":2000},"runs":{"type":"array","items":{"type":"object","properties":{"insert":{"type":"string"},"marks":{"type":"object","properties":{"bold":{"type":"boolean","const":true},"italic":{"type":"boolean","const":true},"code":{"type":"boolean","const":true},"link":{"type":"string"}},"additionalProperties":false}},"required":["insert"],"additionalProperties":false}},"rows":{"type":"array","items":{"type":"array","items":{"type":"string"}}}},"additionalProperties":false}}},"required":["blocks"],"additionalProperties":false},"EditPage":{"type":"object","properties":{"ops":{"minItems":1,"maxItems":200,"type":"array","items":{"oneOf":[{"type":"object","properties":{"op":{"type":"string","const":"insert"},"after":{"type":"string"},"before":{"type":"string"},"blocks":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["paragraph","heading","todo","bulleted","numbered","quote","code","math","divider","database","form","reference","file","bookmark","table","private","drawing"]},"text":{"type":"string"},"level":{"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3}]},"checked":{"type":"boolean"},"databaseId":{"type":"string"},"formConfig":{"type":"string"},"refNodeId":{"type":"string"},"refLabel":{"type":"string"},"fileId":{"type":"string"},"url":{"type":"string"},"description":{"type":"string","maxLength":2000},"runs":{"type":"array","items":{"type":"object","properties":{"insert":{"type":"string"},"marks":{"type":"object","properties":{"bold":{"type":"boolean","const":true},"italic":{"type":"boolean","const":true},"code":{"type":"boolean","const":true},"link":{"type":"string"}},"additionalProperties":false}},"required":["insert"],"additionalProperties":false}},"rows":{"type":"array","items":{"type":"array","items":{"type":"string"}}}},"additionalProperties":false}}},"required":["op","blocks"],"additionalProperties":false},{"type":"object","properties":{"op":{"type":"string","const":"update"},"block_id":{"type":"string","minLength":1},"match":{"type":"object","properties":{"type":{"type":"string","enum":["paragraph","heading","todo","bulleted","numbered","quote","code","math","divider","database","form","reference","file","bookmark","table","private","drawing"]},"text":{"type":"string"}},"additionalProperties":false},"type":{"type":"string","enum":["paragraph","heading","todo","bulleted","numbered","quote","code","math","divider","database","form","reference","file","bookmark","table","private","drawing"]},"text":{"type":"string"},"level":{"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3}]},"checked":{"type":"boolean"},"refNodeId":{"type":"string"},"refLabel":{"type":"string"},"fileId":{"type":"string"},"description":{"type":"string","maxLength":2000},"databaseId":{"type":"string"},"formConfig":{"type":"string"},"url":{"type":"string"}},"required":["op"],"additionalProperties":false},{"type":"object","properties":{"op":{"type":"string","const":"move"},"block_id":{"type":"string","minLength":1},"match":{"type":"object","properties":{"type":{"type":"string","enum":["paragraph","heading","todo","bulleted","numbered","quote","code","math","divider","database","form","reference","file","bookmark","table","private","drawing"]},"text":{"type":"string"}},"additionalProperties":false},"after":{"type":"string"},"before":{"type":"string"}},"required":["op"],"additionalProperties":false},{"type":"object","properties":{"op":{"type":"string","const":"delete"},"block_id":{"type":"string","minLength":1},"match":{"type":"object","properties":{"type":{"type":"string","enum":["paragraph","heading","todo","bulleted","numbered","quote","code","math","divider","database","form","reference","file","bookmark","table","private","drawing"]},"text":{"type":"string"}},"additionalProperties":false}},"required":["op"],"additionalProperties":false}]}},"return":{"type":"string","enum":["none","changed","markdown"]}},"required":["ops"],"additionalProperties":false},"CreateDatabase":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"icon":{"type":"string"},"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":120},"type":{"type":"string","enum":["text","number","select","multi_select","date","duration","checkbox","url","file","files","relation","page_ref","person","place","formula","created_time","created_by","last_edited_time","last_edited_by"]},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":120},"color":{"type":"string","enum":["gray","red","orange","yellow","green","blue","purple","pink","brown"]}},"required":["id","name"],"additionalProperties":false}},"config":{"type":"object","properties":{"includeTime":{"type":"boolean"},"relation":{"type":"object","properties":{"databaseId":{"type":"string"}},"required":["databaseId"],"additionalProperties":false},"formula":{"type":"object","properties":{"expression":{"type":"string","maxLength":2000}},"required":["expression"],"additionalProperties":false}},"additionalProperties":false}},"required":["id","name","type"],"additionalProperties":false}}},"required":["name"],"additionalProperties":false},"InsertRecords":{"type":"object","properties":{"records":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"required":["records"],"additionalProperties":false},"UpdateRecord":{"type":"object","properties":{"properties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["properties"],"additionalProperties":false},"CreateUser":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"name":{"type":"string","maxLength":200},"provider":{"type":"string","maxLength":60},"verified":{"type":"boolean"},"properties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["email"],"additionalProperties":false},"UpdateUser":{"type":"object","properties":{"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"provider":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}]},"verified":{"type":"boolean"},"properties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"additionalProperties":false},"Presign":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"mime":{"default":"application/octet-stream","type":"string","minLength":1,"maxLength":160},"size":{"type":"integer","minimum":0,"maximum":104857600},"visibility":{"default":"signed","type":"string","enum":["public","signed"]}},"required":["name","mime","size","visibility"],"additionalProperties":false},"CreateCommentThread":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":10000},"fieldId":{"type":"string","maxLength":64},"as":{"type":"string","enum":["me","agent"]}},"required":["body"],"additionalProperties":false},"CreateCommentReply":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":10000},"as":{"type":"string","enum":["me","agent"]}},"required":["body"],"additionalProperties":false},"UpdateComment":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":10000}},"required":["body"],"additionalProperties":false},"UpdateCommentThread":{"type":"object","properties":{"resolved":{"type":"boolean"}},"required":["resolved"],"additionalProperties":false},"CommentReaction":{"type":"object","properties":{"emoji":{"type":"string","minLength":1,"maxLength":32},"as":{"type":"string","enum":["me","agent"]}},"required":["emoji"],"additionalProperties":false},"ToggleCommentReaction":{"type":"object","properties":{"emoji":{"type":"string","minLength":1,"maxLength":32},"as":{"type":"string","enum":["me","agent"]},"action":{"type":"string","enum":["add","remove"]}},"required":["emoji"],"additionalProperties":false},"PostComment":{"type":"object","properties":{"nodeId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"threadId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"body":{"type":"string","minLength":1,"maxLength":10000},"fieldId":{"type":"string","maxLength":64},"as":{"type":"string","enum":["me","agent"]}},"required":["body"],"additionalProperties":false},"PatchComment":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":10000},"resolved":{"type":"boolean"}},"additionalProperties":false},"MarkInboxRead":{"type":"object","properties":{"mentionIds":{"maxItems":500,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"additionalProperties":false}}},"paths":{"/api/v1/me":{"get":{"tags":["Client API (user / bearer)"],"summary":"The signed-in user and their workspaces.","security":[{"cookieAuth":[]},{"bearerAuth":[]},{"oauth2":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/devices":{"get":{"tags":["Client API (user / bearer)"],"summary":"Push devices registered by the signed-in user.","security":[{"cookieAuth":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PushDevice"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Client API (user / bearer)"],"summary":"Register or refresh this device for push notifications.","security":[{"cookieAuth":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDeviceInput"}}}},"responses":{"201":{"description":"Registered device.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDevice"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Client API (user / bearer)"],"summary":"Unregister a device by its endpoint (sign-out / opt-out).","security":[{"cookieAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"endpoint","in":"query","required":true,"schema":{"type":"string"},"description":"The device token or push service URL to remove."}],"responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"endpoint":{"type":"string"}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}":{"get":{"tags":["Client API (user / bearer)"],"summary":"Workspace meta + the caller's role.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Client API (user / bearer)"],"summary":"Rename or re-icon the workspace. Owner only; the slug is immutable.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspacePatch"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/nav":{"get":{"tags":["Client API (user / bearer)"],"summary":"Combined nav: pages, databases, favorites, workspace.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Nav"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/nodes":{"post":{"tags":["Client API (user / bearer)"],"summary":"Create a page or database node.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNode"}}}},"responses":{"201":{"description":"Created node.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Node"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/nodes/{id}":{"get":{"tags":["Client API (user / bearer)"],"summary":"Fetch a node (any kind).","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Node id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Node"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Client API (user / bearer)"],"summary":"Update title / icon / cover, or move the node.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Node id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NodePatch"}}}},"responses":{"200":{"description":"Updated node.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Node"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Client API (user / bearer)"],"summary":"Soft-delete a node.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Node id."}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"node_id":{"type":"string"}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/nodes/{id}/children":{"get":{"tags":["Client API (user / bearer)"],"summary":"Children of a node (optionally by kind).","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Parent node id."},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["page","database","row"]},"description":"e.g. `row` for a database's records."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Node"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/nodes/{id}/ancestors":{"get":{"tags":["Client API (user / bearer)"],"summary":"Breadcrumb chain (root → parent).","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Node id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"icon":{"type":["string","null"]}}}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/nodes/{id}/share":{"get":{"tags":["Client API (user / bearer)"],"summary":"The node's public share, or null.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Node id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"share":{"oneOf":[{"$ref":"#/components/schemas/Share"},{"type":"null"}]}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Client API (user / bearer)"],"summary":"Publish a public share link (idempotent).","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Node id."}],"responses":{"201":{"description":"Share.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Share"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Client API (user / bearer)"],"summary":"Revoke the node's share(s).","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Node id."}],"responses":{"200":{"description":"Unpublished.","content":{"application/json":{"schema":{"type":"object","properties":{"unpublished":{"type":"boolean"},"node_id":{"type":"string"}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/nodes/{id}/sync-grant":{"post":{"tags":["Client API (user / bearer)"],"summary":"Mint a Yjs sync grant to open the node's `/doc` socket.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Node id."}],"responses":{"200":{"description":"Grant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncGrant"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/bus-grant":{"post":{"tags":["Client API (user / bearer)"],"summary":"Mint a workspace bus grant for realtime invalidations.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."}],"responses":{"200":{"description":"Grant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusGrant"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/favorites":{"get":{"tags":["Client API (user / bearer)"],"summary":"The caller's starred nodes.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Favorite"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Client API (user / bearer)"],"summary":"Star a node.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FavoriteInput"}}}},"responses":{"201":{"description":"Favorited.","content":{"application/json":{"schema":{"type":"object","properties":{"favorited":{"type":"boolean"},"node_id":{"type":"string"}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/favorites/{nodeId}":{"delete":{"tags":["Client API (user / bearer)"],"summary":"Un-star a node.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"nodeId","in":"path","required":true,"schema":{"type":"string"},"description":"Node id."}],"responses":{"200":{"description":"Unfavorited."},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/activity":{"get":{"tags":["Client API (user / bearer)"],"summary":"Workspace activity, newest first (cursor-paginated).","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Activity"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/members":{"get":{"tags":["Client API (user / bearer)"],"summary":"Workspace members (plus open invitations, for owners).","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Member"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Client API (user / bearer)"],"summary":"Invite someone by email. Owner only.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteMember"}}}},"responses":{"201":{"description":"Added as a member, or invited.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["added","invited"]},"email":{"type":"string"},"role":{"type":"string"},"user_id":{"type":["string","null"]}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/members/{userId}":{"patch":{"tags":["Client API (user / bearer)"],"summary":"Change a member's role. Owner only.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"Member's user id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMember"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Member"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Would leave the workspace without an owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Client API (user / bearer)"],"summary":"Remove a member. Owner only; never the last owner.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"Member's user id."}],"responses":{"200":{"description":"Removed."},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Would leave the workspace without an owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/nodes/{id}/comments":{"get":{"tags":["Client API (user / bearer)"],"summary":"Comment threads on a page or record, newest activity first.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Node id."},{"name":"include_resolved","in":"query","schema":{"type":"boolean"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommentThread"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Client API (user / bearer)"],"summary":"Start a conversation on this node, or on one of its fields.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Node id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCommentThread"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentThread"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/comment-threads/{threadId}":{"patch":{"tags":["Client API (user / bearer)"],"summary":"Resolve or reopen a thread.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"threadId","in":"path","required":true,"schema":{"type":"string"},"description":"Thread id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCommentThread"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentThread"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Client API (user / bearer)"],"summary":"Delete a thread and its replies.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"threadId","in":"path","required":true,"schema":{"type":"string"},"description":"Thread id."}],"responses":{"200":{"description":"Deleted."},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/comment-threads/{threadId}/comments":{"post":{"tags":["Client API (user / bearer)"],"summary":"Reply to a thread.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"threadId","in":"path","required":true,"schema":{"type":"string"},"description":"Thread id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCommentReply"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comment"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/comments/{commentId}":{"patch":{"tags":["Client API (user / bearer)"],"summary":"Edit a comment's body. Only its author may.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"commentId","in":"path","required":true,"schema":{"type":"string"},"description":"Comment id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateComment"}}}},"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Client API (user / bearer)"],"summary":"Delete a comment. Its author, or a workspace owner.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"commentId","in":"path","required":true,"schema":{"type":"string"},"description":"Comment id."}],"responses":{"200":{"description":"Deleted."},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/comments/{commentId}/reactions":{"put":{"tags":["Client API (user / bearer)"],"summary":"Add an emoji reaction. Idempotent.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"commentId","in":"path","required":true,"schema":{"type":"string"},"description":"Comment id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentReaction"}}}},"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Client API (user / bearer)"],"summary":"Remove your reaction.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"commentId","in":"path","required":true,"schema":{"type":"string"},"description":"Comment id."},{"name":"emoji","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/inbox":{"get":{"tags":["Client API (user / bearer)"],"summary":"Mentions addressed to you, threads you're in, or open threads.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"tab","in":"query","schema":{"type":"string","enum":["mentions","participating","unresolved"]}},{"name":"unread_only","in":"query","schema":{"type":"boolean"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"unread_count":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/InboxItem"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Client API (user / bearer)"],"summary":"Mark mentions read. Omit mentionIds to clear everything.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkInboxRead"}}}},"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/nodes/{id}/grants":{"get":{"tags":["Client API (user / bearer)"],"summary":"People explicitly granted access to this node.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Node id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NodeGrant"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Client API (user / bearer)"],"summary":"Share this node with someone by email.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Node id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNodeGrant"}}}},"responses":{"201":{"description":"Shared.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NodeGrant"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Client API (user / bearer)"],"summary":"Change a person's role on this node.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Node id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateNodeGrant"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NodeGrant"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Client API (user / bearer)"],"summary":"Revoke a person's access to this node.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Node id."},{"name":"email","in":"query","required":true,"schema":{"type":"string"},"description":"The grantee's email."}],"responses":{"200":{"description":"Revoked."},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/flows":{"get":{"tags":["Client API (user / bearer)"],"summary":"Automation flows (triggers). Owner only.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Flow"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/flows/{flowId}":{"get":{"tags":["Client API (user / bearer)"],"summary":"One flow, including its graph. Owner only.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"flowId","in":"path","required":true,"schema":{"type":"string"},"description":"Flow id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flow"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Client API (user / bearer)"],"summary":"Enable/disable or rename a flow. Owner only; the graph is edited on the web canvas.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"flowId","in":"path","required":true,"schema":{"type":"string"},"description":"Flow id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"name":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flow"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/flows/{flowId}/runs":{"get":{"tags":["Client API (user / bearer)"],"summary":"Recent executions of a flow, with per-node outcomes. Owner only.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"flowId","in":"path","required":true,"schema":{"type":"string"},"description":"Flow id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FlowRun"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/databases/{id}":{"patch":{"tags":["Client API (user / bearer)"],"summary":"Rename a database or replace its schema / views.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Database node id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabasePatch"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Node"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/databases/{id}/records":{"get":{"tags":["Client API (user / bearer)"],"summary":"A database's rows (cursor-paginated, view-filterable).","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Database node id."},{"name":"limit","in":"query","schema":{"type":"integer"},"required":false},{"name":"cursor","in":"query","schema":{"type":"string"},"required":false},{"name":"filter","in":"query","schema":{"type":"string"},"required":false,"description":"URL-encoded JSON filter array."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Node"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Client API (user / bearer)"],"summary":"Insert rows (records keyed by field id).","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Database node id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsertRecords"}}}},"responses":{"201":{"description":"Created rows.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Node"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/w/{workspaceId}/search":{"get":{"tags":["Client API (user / bearer)"],"summary":"Full-text + fuzzy node search.","parameters":[{"name":"workspaceId","in":"path","required":true,"schema":{"type":"string"},"description":"Workspace id (uuid)."},{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"kinds","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated: page,database,row."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["page","database","row"]},"title":{"type":"string"},"icon":{"type":["string","null"]},"parent_id":{"type":["string","null"]}}}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/workspace":{"get":{"tags":["Agent API (key)"],"summary":"The key's workspace.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/comments":{"get":{"tags":["Agent API (key)"],"summary":"Comments on a node, or every open thread in the workspace.","security":[{"bearerAuth":[]}],"parameters":[{"name":"node_id","in":"query","schema":{"type":"string"},"description":"Omit for workspace-wide open threads."},{"name":"include_resolved","in":"query","schema":{"type":"boolean"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommentThread"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Agent API (key)"],"summary":"Start a thread (node_id) or reply to one (thread_id).","description":"`as` chooses the byline: \"agent\" signs with the calling app's own name, \"me\" signs with the person who authorized it. The audit trail records the real principal either way.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostComment"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentThread"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/comments/{id}":{"patch":{"tags":["Agent API (key)"],"summary":"Edit a comment ({body}) or resolve a thread ({resolved}).","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Comment id, or thread id when resolving."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchComment"}}}},"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Agent API (key)"],"summary":"Delete a comment, or a thread when the id names one.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Comment or thread id."}],"responses":{"200":{"description":"Deleted."},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/comments/{id}/reactions":{"post":{"tags":["Agent API (key)"],"summary":"Add or remove an emoji reaction.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Comment id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToggleCommentReaction"}}}},"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/pages":{"get":{"tags":["Agent API (key)"],"summary":"List pages (flat).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PageNode"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Agent API (key)"],"summary":"Create a page.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePage"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageNode"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/pages/{id}":{"get":{"tags":["Agent API (key)"],"summary":"A page with its block content + text.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Page id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageNode"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Agent API (key)"],"summary":"Update a page's title, icon, cover, and/or position.","description":"Metadata only — edit the body with /pages/{id}/edit.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Page id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PagePatch"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageNode"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Agent API (key)"],"summary":"Delete a page.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Page id."}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/pages/{id}/append":{"post":{"tags":["Agent API (key)"],"summary":"Append blocks to a page.","description":"Shorthand for adding at the end; /pages/{id}/edit also positions.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Page id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppendBlocks"}}}},"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/pages/{id}/edit":{"post":{"tags":["Agent API (key)"],"summary":"Edit a page body: insert / update / move / delete blocks.","description":"An ordered batch of ops anchored to the block ids returned by GET /pages/{id}. Insert with no anchor appends.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Page id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditPage"}}}},"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases":{"get":{"tags":["Agent API (key)"],"summary":"List databases.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Database"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Agent API (key)"],"summary":"Create a database.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDatabase"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Database"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{id}":{"get":{"tags":["Agent API (key)"],"summary":"A database + schema.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Database id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Database"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{id}/records":{"get":{"tags":["Agent API (key)"],"summary":"List records (cursor-paginated, filterable).","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Database id."},{"name":"limit","in":"query","schema":{"type":"integer"},"required":false},{"name":"cursor","in":"query","schema":{"type":"string"},"required":false},{"name":"filter","in":"query","schema":{"type":"string"},"required":false,"description":"URL-encoded JSON filter array."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Record"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Agent API (key)"],"summary":"Insert records.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Database id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsertRecords"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Record"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/records/{id}":{"patch":{"tags":["Agent API (key)"],"summary":"Update a record's properties.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Record id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRecord"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Record"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Agent API (key)"],"summary":"Delete a record.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Record id."}],"responses":{"200":{"description":"Deleted."},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/records/{id}/body":{"get":{"tags":["Agent API (key)"],"summary":"A record's block content + text.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Record id."}],"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/records/{id}/body/append":{"post":{"tags":["Agent API (key)"],"summary":"Append blocks to a record's body.","description":"Shorthand for adding at the end; /records/{id}/body/edit also positions.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Record id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppendBlocks"}}}},"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/records/{id}/body/edit":{"post":{"tags":["Agent API (key)"],"summary":"Edit a record's body: insert / update / move / delete blocks.","description":"An ordered batch of ops anchored to the block ids returned by GET /records/{id}/body.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Record id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditPage"}}}},"responses":{"200":{"description":"OK"},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/users":{"get":{"tags":["Agent API (key)"],"summary":"List end-users (your app's signups).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EndUser"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Agent API (key)"],"summary":"Create an end-user.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUser"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndUser"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/users/{id}":{"patch":{"tags":["Agent API (key)"],"summary":"Update an end-user.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"End-user id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUser"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndUser"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/files":{"get":{"tags":["Agent API (key)"],"summary":"List files (with signed URLs).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/File"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/files/presign":{"post":{"tags":["Agent API (key)"],"summary":"Get a presigned upload URL.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Presign"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"upload_url":{"type":"string"},"file_id":{"type":"string"},"key":{"type":"string"}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/files/{id}/complete":{"post":{"tags":["Agent API (key)"],"summary":"Finalize an uploaded file.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"File id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/activity":{"get":{"tags":["Agent API (key)"],"summary":"Activity log (cursor-paginated).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Activity"}}}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient role or scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not a member of the workspace).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}