{"openapi":"3.1.0","info":{"title":"AUVY API","version":"1.0.0","description":"Public API for receptors, workflows, unified resources (store / vault lanes), traces, and other API-key controllable AUVY surfaces."},"servers":[{"url":"https://api.auvy.ai","description":"Production Server"}],"paths":{"/v1/health":{"get":{"summary":"Health check","responses":{"200":{"description":"OK"}}}},"/v1/collaboration/notifications":{"get":{"summary":"List workspace inbox notifications","description":"Session-only in-app inbox rows for the authenticated workspace user.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Notifications plus unread_count and next_cursor"}}}},"/v1/collaboration/notifications/read":{"post":{"summary":"Mark workspace inbox notifications read","description":"Marks selected notification ids or all unread notifications for the user.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Read state update summary"}}}},"/v1/receptors":{"get":{"summary":"List receptors","description":"List receptors (neuron/pathway entry points). Requires X-Brain-Id for brain scope.","responses":{"200":{"description":"List of receptors"}}},"post":{"summary":"Create receptor","description":"Create a trigger entrypoint targeting an existing neuron or pathway. Requires X-Brain-Id; optional workspace_id must match auth when provided.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Created receptor"},"409":{"description":"Receptor already exists for target"}}}},"/v1/receptors/{workspace_slug}/{slug}":{"get":{"summary":"Get receptor by workspace and slug or receptor id","description":"Resolves workspace from workspace_slug, then loads the receptor by slug or id in that workspace. Second segment: receptor slug (lowercase) or receptor UUID. 404 if the receptor row is not in that workspace.","parameters":[{"name":"workspace_slug","in":"path","required":true,"schema":{"type":"string","description":"Workspace slug (must match the receptor workspace_id)"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string","description":"Receptor slug or UUID"}}],"responses":{"200":{"description":"Receptor"},"404":{"description":"Not found"}}},"patch":{"summary":"Update receptor","parameters":[{"name":"workspace_slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string","description":"Receptor slug or UUID"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated receptor"},"404":{"description":"Not found"}}}},"/v1/receptors/{workspace_slug}/{slug}/share":{"get":{"summary":"Get receptor share","parameters":[{"name":"workspace_slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Share info; `share_url` when `token_available` (vault or stored token); hash-only shares omit URL until rotate"}}},"post":{"summary":"Create share","parameters":[{"name":"workspace_slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Share URL and token (dashboard)"}}}},"/v1/internal/stimulus":{"post":{"summary":"Route a stimulus envelope (internal)","description":"Bearer AUVY_CONNECT_INTERNAL_SECRET or AUVY_RECEPTOR_TRIGGER_SECRET. Single ingress for routine and system stimulus routing.","responses":{"200":{"description":"fires[] or deduped"}}}},"/v1/internal/ingress/slack":{"post":{"summary":"Slack chat ingress (internal)","description":"Normalized Slack payload from bots.auvy.ai; builds ingress.slack.message stimulus.","responses":{"200":{"description":"fires[] or deduped"},"404":{"description":"No binding"}}}},"/v1/internal/ingress/teams":{"post":{"summary":"Teams chat ingress (internal)","description":"Normalized Teams payload from bots.auvy.ai; builds ingress.teams.message stimulus.","responses":{"200":{"description":"fires[] or deduped"},"404":{"description":"No binding"}}}},"/v1/internal/ingress/email":{"post":{"summary":"Platform inbox email ingress (internal)","description":"Normalized email payload from bots.auvy.ai; builds ingress.email.received stimulus.","responses":{"200":{"description":"fires[] or deduped"},"404":{"description":"No route"}}}},"/v1/stimuli/emit":{"post":{"summary":"Emit a workspace stimulus","description":"Workspace-auth emit → routeStimulus for subscribed routines and system handlers.","responses":{"200":{"description":"deduped or discarded"},"202":{"description":"job_id and fires"}}}},"/v1/internal/connect/refresh-integration-tools":{"post":{"summary":"Refresh integration tools from Connect (internal)","description":"Bearer AUVY_CONNECT_INTERNAL_SECRET or AUVY_RECEPTOR_TRIGGER_SECRET. Connect requests the refresh; Synapse enqueues the worker job.","responses":{"200":{"description":"job_id and status"},"400":{"description":"Invalid payload"}}}},"/v1/internal/receptor-channels/resolve-slack":{"post":{"summary":"Resolve Slack team+channel to binding","description":"Trusted service only; Connect or receptor trigger secret.","responses":{"200":{"description":"binding"},"404":{"description":"No binding"}}}},"/v1/jobs":{"get":{"summary":"List jobs","description":"List execution jobs. Filter by pathway_id, receptor_id, status. Workspace-scoped.","parameters":[{"name":"pathway_id","in":"query","schema":{"type":"string"}},{"name":"receptor_id","in":"query","schema":{"type":"string"}},{"name":"trace_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Jobs list with total"}}},"post":{"summary":"Start pathway run","description":"Enqueue a pathway execution. Body: pathway_id (or inline pathway), optional input or data. Returns job_id; poll GET /v1/jobs/{jobId}/status or GET /v1/jobs/{jobId}/stream.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"pathway_id":{"type":"string"},"input":{"type":"object"},"data":{"type":"object"}}}}}},"responses":{"200":{"description":"job_id and status"},"404":{"description":"Pathway not found"}}}},"/v1/jobs/{jobId}/status":{"get":{"summary":"Get job status","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job status and result"},"403":{"description":"Not your workspace"},"404":{"description":"Not found"}}}},"/v1/jobs/{jobId}/stream":{"get":{"summary":"Stream job progress","description":"SSE stream for job events until complete or error. Each event may be preceded by an SSE id line (Redis stream id) for resume. Optional query after=<id> replays only entries after that id (exclusive). Comment lines keep the connection alive during idle periods.","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}},{"name":"after","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d+-\\d+$"},"description":"Redis stream cursor; omit for full buffer replay"}],"responses":{"200":{"description":"text/event-stream"},"400":{"description":"Invalid after cursor"},"403":{"description":"Not your workspace"},"404":{"description":"Not found"},"503":{"description":"Stream subscriber pool exhausted"}}}},"/v1/jobs/{jobId}/cancel":{"post":{"summary":"Cancel job","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled"},"400":{"description":"Already completed/failed"}}}},"/v1/jobs/{jobId}/resume":{"post":{"summary":"Resume job","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resumed"}}}},"/v1/jobs/{jobId}/input":{"post":{"summary":"Submit intervention response for waiting job","description":"Body must include `input` with `type: intervention_response`, `interventionId`, and `action` (and optional fields per action). Updates the intervention record and resumes the run when finalized.","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["workspace_id","input"],"properties":{"workspace_id":{"type":"string"},"input":{"type":"object","required":["type","interventionId","action"],"properties":{"type":{"type":"string","enum":["intervention_response"]},"interventionId":{"type":"string"},"action":{"type":"string","enum":["approve","reject","submit_input","answer_questions","decline_questions"]},"reason":{"type":"string"},"value":{},"answers":{"type":"object","additionalProperties":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Response recorded; may include job_id when run resumed"},"400":{"description":"Invalid body"},"404":{"description":"Job or intervention not found"}}}},"/v1/workspace/brains/{brainId}/skills":{"get":{"summary":"List brain Agent Skills","description":"Skills stored in brain vault at `/.brain/skills/{name}/`.","parameters":[{"name":"brainId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"{ skills: [{ name, description, vault_path }] }"}}}},"/v1/workspace/brains/{brainId}/skills/install":{"post":{"summary":"Install Agent Skills directory into brain vault","parameters":[{"name":"brainId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"skill_name":{"type":"string"},"files":{"type":"array","items":{"type":"object","required":["relativePath","content"],"properties":{"relativePath":{"type":"string"},"content":{"type":"string"}}}}}}}}},"responses":{"202":{"description":"{ job_id, skill_name } — agent-end brain-skill-install job"}}}},"/v1/workspace/brains/{brainId}/skills/{name}":{"get":{"summary":"Get brain skill (parsed SKILL.md)","parameters":[{"name":"brainId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Skill frontmatter + body_md"},"404":{"description":"Not found"}}}},"/v1/interventions":{"get":{"summary":"List workspace interventions","description":"Brain-scoped by default: requires X-Brain-Id (and optional matching brain_id query). Use brain_scope=all for workspace-wide. summary=1 returns status counts only (same filters).","parameters":[{"name":"job_id","in":"query","schema":{"type":"string"}},{"name":"trace_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","approved","rejected","answered","expired","cancelled"]}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"brain_id","in":"query","description":"Optional; must match X-Brain-Id when both are set","schema":{"type":"string","format":"uuid"}},{"name":"brain_scope","in":"query","description":"Omit or brain: require resolved brain. all: list entire workspace (tenant still from auth).","schema":{"type":"string","enum":["brain","all"]}},{"name":"summary","in":"query","description":"If 1, return { counts } only (no intervention list).","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"{ interventions: [] } or { counts: byStatus + grouped }"}}}},"/v1/interventions/{id}":{"get":{"summary":"Get intervention with deliveries","description":"Same brain_scope / brain_id rules as list.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brain_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"brain_scope","in":"query","schema":{"type":"string","enum":["brain","all"]}}],"responses":{"200":{"description":"Intervention"},"404":{"description":"Not found"}}}},"/v1/interventions/{id}/respond":{"post":{"summary":"Submit intervention response (workspace auth)","description":"Body: intervention_response with interventionId, action, and optional reason/value/answers/resolution_payload per mode. Query brain_scope/brain_id same as GET.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"brain_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"brain_scope","in":"query","schema":{"type":"string","enum":["brain","all"]}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type","interventionId","action"],"properties":{"type":{"type":"string","enum":["intervention_response"]},"interventionId":{"type":"string"},"action":{"type":"string","enum":["approve","reject","submit_input","answer_questions","decline_questions"]},"reason":{"type":"string"},"value":{},"answers":{"type":"object","additionalProperties":{"type":"string"}},"resolution_payload":{}}}}}},"responses":{"200":{"description":"Result with intervention and optional job_id"}}}},"/v1/public/interventions/{token}":{"get":{"summary":"Get public intervention (delivery token)","description":"No auth; token is the delivery token from email or deep link.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Slim intervention + delivery"},"404":{"description":"Not found"}}}},"/v1/public/interventions/{token}/respond":{"post":{"summary":"Respond to public intervention","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type","interventionId","action"],"properties":{"type":{"type":"string","enum":["intervention_response"]},"interventionId":{"type":"string"},"action":{"type":"string"},"reason":{"type":"string"},"value":{},"answers":{"type":"object","additionalProperties":{"type":"string"}},"resolution_payload":{}}}}}},"responses":{"200":{"description":"Submit result"}}}},"/v1/resources/kind-definitions":{"get":{"summary":"Resource kind registry (version storage, browse shape, ...)","description":"Read-only. Returns JSON-serializable rows from `listResourceKindDefinitions()` (populated server-side). Same auth as other `/v1/resources` routes.","responses":{"200":{"description":"Array under `data`"},"401":{"description":"Unauthenticated"}}}},"/v1/resources/trash":{"get":{"summary":"List soft-deleted resource heads","description":"Workspace-admin trash listing over unified resource heads where `is_deleted=true`. Returns only rows the caller can act on; brain-scoped rows are checked against brain access. Supports cursor pagination via `meta.next_cursor`.","parameters":[{"name":"kind","in":"query","schema":{"type":"string"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"{ data, meta: { total, limit, offset, cursor, next_cursor, workspace_id } }"},"403":{"description":"Workspace admin role required"}}}},"/v1/resources/trash/{resourceId}/restore":{"post":{"summary":"Restore a soft-deleted resource by id","description":"Workspace-admin restore endpoint for trash rows. Resolves the resource kind from the head, asserts brain access when applicable, restores through the unified spine, and emits standard resource mutation effects.","parameters":[{"name":"resourceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"{ success, resource_id, kind, version, restored }"},"400":{"description":"Invalid id, not deleted, or restore unsupported for kind"},"403":{"description":"Workspace admin role or brain access required"},"404":{"description":"Resource not found or cannot be restored"}}}},"/v1/resources/trash/{resourceId}/purge":{"post":{"summary":"Permanently purge a soft-deleted resource by id","description":"Workspace-admin hard-delete endpoint for trash rows only. Removes indexed projections, best-effort file blobs for file-backed document-lane resources, and the unified resource spine.","parameters":[{"name":"resourceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"{ success, resource_id, purged }"},"400":{"description":"Invalid id, not soft-deleted, or purge unsupported for kind"},"403":{"description":"Workspace admin role or brain access required"},"404":{"description":"Resource not found"}}}},"/v1/resources/tree":{"get":{"summary":"Document-lane path tree (unified resource heads)","description":"Read-only. Query: brain_id, prefix, mode (rows|shape), optional tree_profile (broad|document). Default **broad** is the wider HTTP/catalog slice (`allowedKindsForDocumentLaneProfile(\"broad\")`). Native tree browse for assistants is **document_tree** (artifact + vault-document asset + meeting — same as **tree_profile: document**). **move** updates native folder paths; **`move_profile: document`** matches native **document_move**.","responses":{"200":{"description":"Tree rows or shape structure"},"400":{"description":"Invalid query"}}},"post":{"summary":"Document-lane path tree (POST body)","description":"JSON: brain_id, prefix, mode (rows|shape), optional tree_profile (broad|document). Same Redis row cache family; kindsKey differs when tree_profile=document.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Tree payload"},"400":{"description":"Invalid body"}}}},"/v1/resources/move":{"post":{"summary":"Batch native path moves for store resources","description":"Body: moves[{ path, new_path }], optional move_profile (resource|document). Default resource = vault-lane heads policy; document = artifact / vault-document asset / meeting (native document_move).","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Move result"},"400":{"description":"Invalid body"}}}},"/v1/resources/{catalog}":{"get":{"summary":"List synaptic SDK catalog resources","description":"Kinds that register `sdkExposure.listPath` under `/v1/resources/:catalog` (including document-lane `assets`/`artifacts` and synaptic `neurons`, `reflexes`, `receptors`, `cortex_engagements`). **Neuron head read** by UUID: `GET /v1/resources/neurons/:resource_id` (unified spine; SDK `client.resources.catalogGet(\"neurons\", resource_id)`). Legacy alternate: `GET /v1/neurons/:id` (`client.neurons.get`). Receptor list rows match `GET /v1/receptors` (including `target_type`, `is_active`, filters `target_type`, `ids`). Cortex engagements are brain-scoped governed engagement canvases.","parameters":[{"name":"catalog","in":"path","required":true,"schema":{"type":"string","enum":["assets","artifacts","neurons","reflexes","receptors","cortex_engagements"]}},{"name":"brain_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0}},{"name":"sortBy","in":"query","schema":{"type":"string"}},{"name":"sortDirection","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"target_type","in":"query","schema":{"type":"string","enum":["neuron","pathway"]}},{"name":"ids","in":"query","schema":{"type":"string","description":"Comma-separated receptor UUIDs (max 100)"}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Array rows, or `{ data, meta }` when `limit` or `offset` is set (neurons/reflex/receptor/cortex_engagements)"},"404":{"description":"Unknown catalog segment"}}},"post":{"summary":"Create resource for SDK catalog segment","description":"Currently supported for `catalog=cortex_engagements`. Creates a new governed **cortex_engagement** canvas for the resolved brain (`X-Brain-Id` or `brain_id`). Populate via the `apply_cortex_engagement_patch` native tool or cortex engagement SDK helpers.","parameters":[{"name":"catalog","in":"path","required":true,"schema":{"type":"string","enum":["cortex_engagements"]}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","maxLength":500},"path":{"type":"string","maxLength":2000,"description":"Vault folder path (default `/`)"},"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"`{ resource_id, title, path, updated_at, brain_id }`"},"404":{"description":"Create not supported for this catalog"}}}},"/v1/resources/{catalog}/{resourceId}":{"get":{"summary":"Read one synaptic SDK catalog resource by id","description":"Unified resource spine read by catalog UUID. **Neurons**: `GET /v1/resources/neurons/:resource_id` (same row shape as catalog list entries; SDK `client.resources.catalogGet(\"neurons\", resource_id)`). Alternately `GET /v1/neurons/:id` (`client.neurons.get`). Soft-deleted heads are not returned (**404**).","parameters":[{"name":"catalog","in":"path","required":true,"schema":{"type":"string","enum":["assets","artifacts","neurons","reflexes","receptors","cortex_engagements"]}},{"name":"resourceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Catalog document; for `catalog=receptors`, `{ receptor }` (same fields as `GET /v1/receptors/:ws/:slug`)"},"404":{"description":"Not found or wrong catalog"}}},"delete":{"summary":"Soft-delete one catalog resource by id","description":"Canonical Resource catalog delete. Appends a tombstone version, emits Resource mutation effects, and keeps legacy lane delete routes as compatibility adapters.","parameters":[{"name":"catalog","in":"path","required":true,"schema":{"type":"string","enum":["assets","artifacts","neurons","reflexes","receptors","cortex_engagements"]}},{"name":"resourceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"`{ success: true }`"},"404":{"description":"Not found or delete not supported"}}}},"/v1/resources/{catalog}/{resourceId}/restore":{"post":{"summary":"Restore a soft-deleted catalog resource","description":"Restores the latest non-tombstone Resource version through the unified mutation pipeline; replays cache invalidation, mutation events, projection effects, and audit logging.","parameters":[{"name":"catalog","in":"path","required":true,"schema":{"type":"string","enum":["assets","artifacts","neurons","reflexes","receptors","cortex_engagements"]}},{"name":"resourceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"`{ resource_id, kind, version, restored, head }`"},"404":{"description":"Not found or not restorable"}}}},"/v1/resources/cortex_engagements/{resourceId}/query":{"post":{"summary":"Run engagement graph query (EGQ)","description":"Read-only EGQ over a cortex engagement. Example body: `{ \"query\": \"changes days -7\" }` or `{ \"query\": \"timeline days -30 change_kind delivery risk\", \"limit\": 50 }`.","parameters":[{"name":"resourceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"additionalProperties":false,"properties":{"query":{"type":"string","description":"EGQ statement (e.g. changes days -7)"},"limit":{"type":"integer","minimum":1,"maximum":200}}}}}},"responses":{"200":{"description":"EGQ result with window, summary_delta/graph_diff or timeline rows"},"400":{"description":"Invalid EGQ or request body"},"404":{"description":"Engagement not found"}}}},"/v1/resources/cortex_engagements/{resourceId}/timeline":{"get":{"summary":"Cortex engagement version timeline (event metadata per commit)","description":"Projects `resource_versions` rows for a cortex engagement: change_kind, change_summary, event_type, actor/target nodes, commitments, and related audit fields. Body snapshots are graph+summary only.","parameters":[{"name":"resourceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"before_version","in":"query","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"`{ data: CortexEngagementTimelineRow[] }`"},"404":{"description":"Engagement not found"}}}},"/v1/resources/{catalog}/{resourceId}/history":{"get":{"summary":"Version metadata history for synaptic SDK catalog kinds","parameters":[{"name":"catalog","in":"path","required":true,"schema":{"type":"string","enum":["assets","artifacts","neurons","reflexes","receptors","cortex_engagements"]}},{"name":"resourceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"before_version","in":"query","schema":{"type":"integer","minimum":1}},{"name":"summary_only","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"`{ data: ResourceVersionRecord[] }`"},"404":{"description":"Unknown catalog or history disabled"}}}},"/v1/resources/{catalog}/{resourceId}/diff":{"get":{"summary":"Shallow top-level key adds/removes between consecutive stored versions","description":"For each step (v, v+1) from query `from` through `to`-1, compares version bodies as JSON objects at depth 1 only. Query: `from`, `to` (positive integers, `from` < `to`, span at most 100).","parameters":[{"name":"catalog","in":"path","required":true,"schema":{"type":"string","enum":["assets","artifacts","neurons","reflexes","receptors","cortex_engagements"]}},{"name":"resourceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","required":true,"schema":{"type":"integer","minimum":1}},{"name":"to","in":"query","required":true,"schema":{"type":"integer","minimum":2}}],"responses":{"200":{"description":"`{ resource_id, kind, from_version, to_version, steps: { from_version, to_version, added_keys, removed_keys }[] }`"},"400":{"description":"Invalid range, non-object body root, or span > 100"},"404":{"description":"Unknown catalog, diff disabled, or version not found"},"410":{"description":"Resource deleted"}}}},"/v1/resources/{catalog}/{resourceId}/versions/{version}":{"get":{"summary":"Read historical body at integer version (content-addressed store)","parameters":[{"name":"catalog","in":"path","required":true,"schema":{"type":"string","enum":["assets","artifacts","neurons","reflexes","receptors","cortex_engagements"]}},{"name":"resourceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"version","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"`{ resource_id, version_number, version_id, body, version }`"},"404":{"description":"Not found"}}}},"/v1/resources/{resourceId}/versions/{version}/promote":{"post":{"summary":"Restore stored version to live head","description":"Resource-id-centric promote (kind resolved from the Mongo head). Appends a new head version whose body matches version *N*; refreshes Mongo `resource_chunks` / grep index in the head's brain context and enqueues vector index jobs for kinds covered by `resolveVectorIndexJobPlan`.","parameters":[{"name":"resourceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"version","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"`{ resource_id, kind, version, promoted_from_version, did_update, head }`"},"403":{"description":"Promote not enabled for this resource kind"},"404":{"description":"Resource or version not found"}}}},"/v1/resources/{kind}/{resourceId}/patch":{"post":{"summary":"Central resource patch","description":"Unified orchestration for registry kinds with `surfaces.patch`. The URL `:kind` must match the envelope `patch_mode` (single source of truth in `@auvy-synapse/kernel/core/resources/resourcePatchRegistry`). Body is discriminated on `patch_mode`; response includes `patch_lane` (`document` for artifact text, `object` for structured updates). Optional `expected_latest_version` is optimistic concurrency. Some modes require `brain_id` (see registry). Native text patch tools (`apply_artifact_patch`, `apply_action_plan_patch`, `apply_routine_patch`) use the same envelopes via this route — resolve `resourceId` from the envelope (or pre-allocate for create) before POST. **Cortex engagements:** agents should use native `apply_cortex_engagement_patch` for governed engagement canvas edits. **Pathways:** `pathway_record_version` accepts the same delta shape for workflow graphs; agents use native `apply_pathway_patch` with `*** Apply Pathway` and identical `@@` sections. **Neurons:** `neuron_apply_text` accepts the same plain-text envelope as native `apply_neuron_patch` (`*** Target Neuron:` + `*** Apply Neuron` + `@@ system_prompt` / `@@ neuron_config` / metadata / name / description); `neuron_structured` remains the JSON merge mode for dashboard callers. No full-graph replace — create/delete heads via catalog.","parameters":[{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["artifact","meeting","pathway","cortex_engagement","cortex_action_plan","routine","lens_layout","neuron","reflex","receptor"]}},{"name":"resourceId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["patch_mode","input"],"properties":{"patch_mode":{"type":"string","enum":["artifact_apply_text"]},"input":{"type":"string","minLength":1},"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"},"trace_id":{"type":"string","minLength":1},"expected_latest_version":{"type":"integer","minimum":1}}},{"type":"object","additionalProperties":false,"required":["patch_mode","body_patch"],"properties":{"patch_mode":{"type":"string","enum":["meeting_structured"]},"body_patch":{"type":"object","additionalProperties":true,"description":"Partial structured meeting body (unified spine merge): agenda, notes, summary, attendee_ids, transcript_segments, speaker_assignments, transcription (includes diarize), etc. Decisions and action items live on engagements, not meetings. Canonical transcript version is `resources.current_version_id`. See `@auvy-synapse/kernel/schemas/meeting` MeetingObjectBody."},"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"},"trace_id":{"type":"string","minLength":1},"expected_latest_version":{"type":"integer","minimum":1}}},{"type":"object","additionalProperties":false,"required":["patch_mode","delta"],"description":"Record a new immutable pathway version. Requires brain scope and `delta` (incremental graph edit; same semantics as native `apply_pathway_patch`). Each successful patch appends `resource_versions` + `resource_chunks` for that version. Response may include `patch_apply_itemized`, `patch_applied`, `patch_errors` when delta rows partially apply.","properties":{"patch_mode":{"type":"string","enum":["pathway_record_version"]},"delta":{"type":"object","additionalProperties":true,"description":"Required incremental patch object. Keys: `add_nodes` (`{ nodes: [{ id?, type, data?, label?, position?, connect_from? }] }`), `update_nodes`, `remove_node_ids` (string[]), `add_edges` (`{ edges: [{ source, target, id?, sourceHandle?, targetHandle? }] }`), `remove_edges`. Node `id` is a graph node id from read (e.g. `node_0`), not the pathway resource UUID.","example":{"add_nodes":{"nodes":[{"id":"node_1","type":"neuron","data":{"target_id":"neurons/research"}}]},"add_edges":{"edges":[{"source":"node_0","target":"node_1"}]}}},"label":{"type":"string","maxLength":500},"change_summary":{"type":"string","maxLength":4000},"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"},"trace_id":{"type":"string","minLength":1},"expected_latest_version":{"type":"integer","minimum":1}}},{"type":"object","additionalProperties":false,"required":["patch_mode"],"properties":{"patch_mode":{"type":"string","enum":["cortex_action_plan_structured"]},"name":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"body_patch":{"type":"object","additionalProperties":true},"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"},"trace_id":{"type":"string","minLength":1},"expected_latest_version":{"type":"integer","minimum":1}}},{"type":"object","additionalProperties":false,"required":["patch_mode","input"],"properties":{"patch_mode":{"type":"string","enum":["cortex_action_plan_apply_text"]},"input":{"type":"string","minLength":1,"description":"Plain-text action plan patch envelope (`*** Write File` / `*** Update Action Plan:` + `@@ plan` / `@@ todos` / status). Same as native `apply_action_plan_patch`."},"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"},"trace_id":{"type":"string","minLength":1},"expected_latest_version":{"type":"integer","minimum":1}}},{"type":"object","additionalProperties":false,"required":["patch_mode"],"properties":{"patch_mode":{"type":"string","enum":["skill_structured"]},"name":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"body_patch":{"type":"object","additionalProperties":true},"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"},"trace_id":{"type":"string","minLength":1},"expected_latest_version":{"type":"integer","minimum":1}}},{"type":"object","additionalProperties":false,"required":["patch_mode"],"properties":{"patch_mode":{"type":"string","enum":["routine_structured"]},"body_patch":{"type":"object","additionalProperties":true},"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"},"trace_id":{"type":"string","minLength":1},"expected_latest_version":{"type":"integer","minimum":1}}},{"type":"object","additionalProperties":false,"required":["patch_mode","input"],"properties":{"patch_mode":{"type":"string","enum":["routine_apply_text"]},"input":{"type":"string","minLength":1},"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"},"trace_id":{"type":"string","minLength":1},"expected_latest_version":{"type":"integer","minimum":1}}},{"type":"object","additionalProperties":false,"required":["patch_mode","intent_patch"],"properties":{"patch_mode":{"type":"string","enum":["lens_layout_structured"]},"surface":{"type":"string","minLength":1},"intent_patch":{"type":"object","additionalProperties":true},"change_kind":{"type":"string","maxLength":120},"change_summary":{"type":"string","maxLength":4000},"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"},"trace_id":{"type":"string","minLength":1},"expected_latest_version":{"type":"integer","minimum":1}}},{"type":"object","additionalProperties":false,"required":["patch_mode","patch"],"properties":{"patch_mode":{"type":"string","enum":["cortex_engagement_structured"]},"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","maxLength":2000,"nullable":true},"patch":{"type":"object","additionalProperties":true},"event":{"type":"object","additionalProperties":true},"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"},"trace_id":{"type":"string","minLength":1},"expected_latest_version":{"type":"integer","minimum":1}}},{"type":"object","additionalProperties":false,"required":["patch_mode","input"],"properties":{"patch_mode":{"type":"string","enum":["neuron_apply_text"]},"input":{"type":"string","minLength":1},"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"},"trace_id":{"type":"string","minLength":1},"expected_latest_version":{"type":"integer","minimum":1}}},{"type":"object","additionalProperties":false,"required":["patch_mode"],"properties":{"patch_mode":{"type":"string","enum":["neuron_structured"]},"name":{"type":"string"},"description":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"neuron_config":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true},"scope":{"type":"string"},"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"},"trace_id":{"type":"string","minLength":1},"expected_latest_version":{"type":"integer","minimum":1}}},{"type":"object","additionalProperties":false,"required":["patch_mode"],"properties":{"patch_mode":{"type":"string","enum":["reflex_structured"]},"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["sensory","effector"]},"tools":{"type":"array","items":{}},"metadata":{"type":"object","additionalProperties":true},"is_active":{"type":"boolean"},"scope":{"type":"string"},"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid","nullable":true},"trace_id":{"type":"string","minLength":1},"expected_latest_version":{"type":"integer","minimum":1}}},{"type":"object","additionalProperties":false,"required":["patch_mode"],"properties":{"patch_mode":{"type":"string","enum":["receptor_structured"]},"description":{"type":"string"},"config":{"type":"object","additionalProperties":true},"is_active":{"type":"boolean"},"monthly_spending_limit_usd":{"type":"number","nullable":true},"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"},"trace_id":{"type":"string","minLength":1},"expected_latest_version":{"type":"integer","minimum":1}}}]}}}},"responses":{"200":{"description":"Patch result","content":{"application/json":{"schema":{"type":"object","required":["ok","kind","resource_id","patch_mode","patch_lane"],"properties":{"ok":{"type":"boolean","enum":[true]},"kind":{"type":"string"},"resource_id":{"type":"string"},"patch_mode":{"type":"string"},"patch_lane":{"type":"string","enum":["document","object"]},"version":{"type":"integer","minimum":1},"detail":{}}}}}},"400":{"description":"Invalid body"},"403":{"description":"Forbidden"},"404":{"description":"Not found"}}}},"/v1/data/status":{"get":{"summary":"Vault Data plane status","responses":{"200":{"description":"Data capabilities and source count"}}}},"/v1/data/sources":{"get":{"summary":"List data sources","parameters":[{"name":"provider","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Paginated sources"}}},"post":{"summary":"Connect PostgreSQL data source","responses":{"200":{"description":"Created source"}}}},"/v1/data/workbooks":{"post":{"summary":"Create workbook data source","responses":{"200":{"description":"Workbook source with univer_pro engine hint"}}}},"/v1/data/tables":{"post":{"summary":"Create sheet in default workbook","responses":{"200":{"description":"Source + table"}}}},"/v1/data/sources/{sourceId}/tables":{"post":{"summary":"Add sheet to workbook source","parameters":[{"name":"sourceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Source + table"}}}},"/v1/data/tables/{resourceId}":{"delete":{"summary":"Delete data table resource","parameters":[{"name":"resourceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}},"/v1/data/sources/{sourceId}/migrations":{"get":{"summary":"List DDL migrations for a data source","parameters":[{"name":"sourceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Migration history"}}},"post":{"summary":"Apply a DDL migration to a data source","description":"Workspace admin only. Requires allow_agent_ddl on the source. Workbook sources only.","parameters":[{"name":"sourceId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","query"],"properties":{"name":{"type":"string","description":"snake_case or YYYYMMDDHHmmss_description"},"query":{"type":"string","description":"PostgreSQL DDL migration script (semicolon-separated, comments OK)"}}}}}},"responses":{"200":{"description":"Migration applied","content":{"application/json":{"schema":{"type":"object","required":["success","statements_applied","mutations_applied","noops"],"properties":{"success":{"type":"boolean","enum":[true]},"statements_applied":{"type":"integer","minimum":0},"mutations_applied":{"type":"integer","minimum":0},"noops":{"type":"integer","minimum":0}}}}}}}}},"/v1/data/tables/{tableId}/sql":{"post":{"summary":"Execute SQL against a data table","description":"SELECT/WITH SELECT for all providers. Workbook sources also accept INSERT, UPDATE, and DELETE on existing sheets (changes persist on the resource spine). PostgreSQL runs in a read-only transaction; CSV/Excel uploads are SELECT-only previews.","parameters":[{"name":"tableId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"Single SQL statement (no comments or semicolons)"},"limit":{"type":"integer","minimum":1,"maximum":500,"description":"Max rows for SELECT queries"}}}}}},"responses":{"200":{"description":"Query rows or mutation summary (`mutation`, `rows_changed` for workbook INSERT/UPDATE/DELETE)"},"400":{"description":"Invalid SQL or mutations on non-workbook source"}}}},"/v1/data/query":{"post":{"summary":"Run read-only SQL against a data source","responses":{"200":{"description":"Query result rows"}}}},"/v1/data/chart-query":{"post":{"summary":"Run read-only SQL for a chart block","description":"Accepts a versioned chart block with sql (spreadsheet_table UUIDs quoted in SQL), optional params bound from widget_state, and a flat visualization grammar. Server derives access_mode=read, database, and row limits.","responses":{"200":{"description":"Query rows plus render-ready visualization with data.values"}}}},"/v1/meetings":{"get":{"summary":"List meetings (collaboration vertical)","description":"Brain-scoped list of `meeting` resources; same indexing/grep substrate as other registry resources.","responses":{"200":{"description":"List of meetings"},"400":{"description":"Invalid query"}}},"post":{"summary":"Create meeting","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Created meeting"},"400":{"description":"Invalid body"}}}},"/v1/meetings/search":{"post":{"summary":"Search meeting transcript segments on the unified resource spine (resource_chunks)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string"},"speaker":{"type":"integer","minimum":0},"speaker_id":{"type":"string","format":"uuid"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"responses":{"200":{"description":"Segment-level search hits"}}}},"/v1/meetings/{id}":{"get":{"summary":"Get meeting by id (includes transcript.segments and transcript.text)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Meeting detail"},"404":{"description":"Not found"}}},"delete":{"summary":"Delete meeting","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted"},"404":{"description":"Not found"}}}},"/v1/meetings/{id}/transcript":{"get":{"summary":"Get diarized transcript (segments + speaker-name markdown text)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Transcript block"},"404":{"description":"Not found"}}}},"/v1/transcription/runtime":{"get":{"summary":"Check async transcription readiness","responses":{"200":{"description":"Runtime readiness: Gladia configured on API (`available`, `gladia_configured`). Worker execution also requires GLADIA_API_KEY on agent-end."}}}},"/v1/voice/runtime":{"get":{"summary":"Check live Gladia dictation readiness","responses":{"200":{"description":"Runtime readiness for browser live capture (`available`, `gladia_configured`, optional `reason`)."}}}},"/v1/voice/live/connect":{"post":{"summary":"Mint Gladia live session credentials for browser PCM streaming","responses":{"200":{"description":"session_id, access_token, listen_url, expires_in, expires_at, optional gladia_session_id"}}}},"/v1/voice/sessions/{sessionId}":{"delete":{"summary":"End a live voice session (tenant check; does not close Gladia WSS server-side)","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok"}}}},"/v1/voice/stt-vocabulary/prewarm":{"post":{"summary":"Prewarm merged STT custom vocabulary for workspace/brain/user layers","responses":{"200":{"description":"ok + term_count","content":{"application/json":{"schema":{"type":"object","required":["ok","term_count"],"properties":{"ok":{"type":"boolean","enum":[true]},"term_count":{"type":"integer","minimum":0}}}}}}}}},"/v1/voice/stt-vocabulary/defaults":{"get":{"summary":"Static STT vocabulary layers (core + vertical)","responses":{"200":{"description":"vertical_id, core, vertical, merged_static term lists"}}}},"/v1/assets":{"get":{"summary":"List Mongo store rows (lane-scoped)","description":"Brain-scoped by default: requires X-Brain-Id (and optional matching brain_id query). `brain_scope=all` returns rows across all brains the caller participates in (not workspace-wide).","parameters":[{"name":"brain_scope","in":"query","required":false,"schema":{"type":"string","enum":["brain","all"]}},{"name":"brain_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Paginated list"}}},"post":{"summary":"Create store row (lane-specific)","description":"`assets` lane: multipart/JSON asset create routes; `artifacts` lane: artifact body POST. Exact shapes match server validators.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Created"}}}},"/v1/assets/{id}":{"get":{"summary":"Get store row","description":"URL lane must match the row native path (`assets` kinds vs standalone `artifact`). Optional includeChunks for chunk pages.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"UUID or name (brain context)"}},{"name":"includeChunks","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"chunksLimit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"chunksOffset","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Store resource document JSON"},"404":{"description":"Not in workspace or wrong lane","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string","enum":["RESOURCE_NOT_FOUND","NOT_FOUND"]}}}}}}}},"put":{"summary":"Update store row","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated"}}},"delete":{"summary":"Delete store row","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}},"/v1/assets/{id}/restore":{"post":{"summary":"Restore soft-deleted store row","description":"Restores the latest non-tombstone Resource version for asset/artifact document-lane rows and emits the standard Resource mutation effects.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Restored store resource document JSON"},"404":{"description":"Not found or not restorable"}}}},"/v1/assets/{id}/versions":{"get":{"summary":"List versions","description":"Stored version trail when enabled for this kind.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Versions"},"404":{"description":"Not found"}}}},"/v1/artifacts":{"get":{"summary":"List Mongo store rows (lane-scoped)","description":"Brain-scoped by default: requires X-Brain-Id (and optional matching brain_id query). `brain_scope=all` returns rows across all brains the caller participates in (not workspace-wide).","parameters":[{"name":"brain_scope","in":"query","required":false,"schema":{"type":"string","enum":["brain","all"]}},{"name":"brain_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Paginated list"}}},"post":{"summary":"Create store row (lane-specific)","description":"`assets` lane: multipart/JSON asset create routes; `artifacts` lane: artifact body POST. Exact shapes match server validators.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Created"}}}},"/v1/artifacts/{id}":{"get":{"summary":"Get store row","description":"URL lane must match the row native path (`assets` kinds vs standalone `artifact`). Optional includeChunks for chunk pages.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"UUID or name (brain context)"}},{"name":"includeChunks","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"chunksLimit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"chunksOffset","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Store resource document JSON"},"404":{"description":"Not in workspace or wrong lane","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string","enum":["RESOURCE_NOT_FOUND","NOT_FOUND"]}}}}}}}},"put":{"summary":"Update store row","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated"}}},"delete":{"summary":"Delete store row","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}},"/v1/artifacts/{id}/restore":{"post":{"summary":"Restore soft-deleted store row","description":"Restores the latest non-tombstone Resource version for asset/artifact document-lane rows and emits the standard Resource mutation effects.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Restored store resource document JSON"},"404":{"description":"Not found or not restorable"}}}},"/v1/artifacts/{id}/versions":{"get":{"summary":"List versions","description":"Stored version trail when enabled for this kind.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Versions"},"404":{"description":"Not found"}}}},"/v1/neurons":{"get":{"summary":"List neurons","responses":{"200":{"description":"List of neurons"}}},"post":{"summary":"Create neuron","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Created neuron"}}}},"/v1/neurons/{id}":{"get":{"summary":"Get neuron","description":"Returns the latest neuron head by default. Pass `version=N` for a full neuron-shaped historical read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"query","required":false,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Neuron"},"400":{"description":"Invalid version"},"404":{"description":"Not found"}}},"patch":{"summary":"Update neuron","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated neuron"}}},"delete":{"summary":"Delete neuron","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}},"/v1/neurons/{id}/invoke":{"post":{"summary":"Invoke neuron (ad-hoc run)","description":"Queue a neuron agent run. Body: message (or messages), optional stream, trace_id, neuron_task_options. Returns job_id; use GET /v1/jobs/{jobId}/stream when stream is true.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"stream":{"type":"boolean"},"trace_id":{"type":"string","format":"uuid"},"neuron_task_options":{"type":"object"}}}}}},"responses":{"202":{"description":"Neuron invoke queued; returns job_id"},"404":{"description":"Neuron not found"}}}},"/v1/neurons/{id}/versions":{"get":{"summary":"List neuron version history","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Version summaries"},"404":{"description":"Neuron not found"}}}},"/v1/neurons/{id}/versions/{version}":{"get":{"summary":"Get neuron body at a version","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Neuron version payload"},"404":{"description":"Not found"}}}},"/v1/neurons/{id}/versions/{version}/promote":{"post":{"summary":"Promote neuron version to head","description":"Roll-forward-as-new-version (same semantics as pathway promote). Optional body: expected_latest_version, trace_id.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated neuron (head)"},"404":{"description":"Not found"}}}},"/v1/pathways":{"get":{"summary":"List pathways","responses":{"200":{"description":"List of pathways"}}},"post":{"summary":"Create pathway","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Created pathway"}}}},"/v1/pathways/{id}":{"get":{"summary":"Get pathway","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Pathway"},"404":{"description":"Not found"}}},"put":{"summary":"Update pathway","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated pathway"}}},"delete":{"summary":"Delete pathway","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}},"/v1/pathways/{id}/execute":{"post":{"summary":"Execute pathway","description":"Start a pathway run by ID. Optional body: { input }. Returns job_id; poll GET /v1/jobs/{jobId}/status or stream.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"object"}}}}}},"responses":{"202":{"description":"Run started"},"404":{"description":"Pathway not found"}}}},"/v1/pathways/validate":{"post":{"summary":"Validate pathway graph","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Validation result"}}}},"/v1/pathways/compile":{"post":{"summary":"Compile pathway to execution graph","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Compiled graph"}}}},"/v1/routines/graph":{"get":{"summary":"Routines hub graph","description":"Returns event-to-routine wiring for the Routines hub. Brain-scoped via `X-Brain-Id`.","responses":{"200":{"description":"Routines graph"}}}},"/v1/cortex/action-plans":{"post":{"summary":"Create action plan template","description":"Creates a template (`role: template`, `parent_key: /`) on the resource spine. List/read via GET /v1/resources/cortex_action_plans.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Created action plan template"}}}},"/v1/cortex/action-plans/{templateId}/instantiate":{"post":{"summary":"Instantiate action plan run from template","parameters":[{"name":"templateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Created run; optional execution when start_trace is true"}}}},"/v1/cortex/action-plans/{runId}/run":{"post":{"summary":"Start trace for action plan run","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"202":{"description":"Neuron invoke queued; returns trace_id"}}}},"/v1/cortex/action-plans/{id}/plasticity-review":{"post":{"summary":"Start plasticity review trace for an action plan","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"202":{"description":"Plasticity review trace started"}}}},"/v1/cortex/action-plans/{id}/execute":{"post":{"summary":"Execute action plan run (alias for .../run)","deprecated":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"202":{"description":"Action plan execution started"}}}},"/v1/reflexes":{"get":{"summary":"List reflexes","responses":{"200":{"description":"List of reflexes"}}},"post":{"summary":"Create reflex","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Created reflex"}}}},"/v1/reflexes/{id}":{"get":{"summary":"Get reflex","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Reflex"},"404":{"description":"Not found"}}},"patch":{"summary":"Update reflex","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated reflex"}}},"delete":{"summary":"Delete reflex","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}},"/v1/traces":{"get":{"summary":"List traces","responses":{"200":{"description":"List of traces"}}}},"/v1/traces/{id}":{"get":{"summary":"Get trace","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Trace"},"404":{"description":"Not found"}}}},"/v1/traces/{id}/messages":{"get":{"summary":"Get trace engrams (JWT/API key, or receptor share: t + workspace + receptor, or t + receptor_id)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"t","in":"query","required":false,"description":"Receptor share token (public read)","schema":{"type":"string"}},{"name":"workspace","in":"query","required":false,"description":"With t: workspace slug (slug-based share)","schema":{"type":"string"}},{"name":"receptor","in":"query","required":false,"description":"With t: receptor slug (slug-based share)","schema":{"type":"string"}},{"name":"receptor_id","in":"query","required":false,"description":"With t: receptor UUID (id-based share)","schema":{"type":"string"}}],"responses":{"200":{"description":"Engrams"}}},"post":{"summary":"Add human turn to trace","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Created engram"}}}},"/v1/traces/{id}/events":{"get":{"summary":"Trace events SSE (Lane A; JWT/API key, or same receptor share query as GET …/messages)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"t","in":"query","required":false,"schema":{"type":"string"}},{"name":"workspace","in":"query","required":false,"schema":{"type":"string"}},{"name":"receptor","in":"query","required":false,"schema":{"type":"string"}},{"name":"receptor_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"after","in":"query","required":false,"description":"Resume after SSE id","schema":{"type":"string"}}],"responses":{"200":{"description":"text/event-stream"}}}},"/v1/resource-events/stream":{"get":{"summary":"Resource mutation events SSE (workspace + brain from auth headers, same as other workspace routes; optional after cursor for replay)","parameters":[{"name":"after","in":"query","required":false,"description":"Resume after SSE id","schema":{"type":"string"}}],"responses":{"200":{"description":"text/event-stream"}}}},"/v1/resource-events/workspace-lane-stream":{"get":{"summary":"Resource mutation events SSE for workspace-scoped document lane rows (Redis `br:_none_`; workspace from auth; optional after cursor)","parameters":[{"name":"after","in":"query","required":false,"description":"Resume after SSE id","schema":{"type":"string"}}],"responses":{"200":{"description":"text/event-stream"}}}},"/v1/traces/{id}/archive":{"post":{"summary":"Archive trace (lifecycle)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Trace detail"},"404":{"description":"Not found"}}}},"/v1/traces/{id}/unarchive":{"post":{"summary":"Unarchive trace (lifecycle)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Trace detail"},"404":{"description":"Not found"}}}},"/v1/usage":{"get":{"summary":"Get usage statistics","responses":{"200":{"description":"Usage data"}}}},"/v1/browse":{"get":{"summary":"List resources by type (browse-only; no pattern)","parameters":[{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["assets","artifacts","cortex_engagements","meetings","neurons","pathways","reflexes","receptors","spreadsheets","cortex_action_plans","routines"]}}],"responses":{"200":{"description":"Browse list payload (same list mode shape as lexical search jobs)"}}},"post":{"summary":"List resources by type (browse-only)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["assets","artifacts","cortex_engagements","meetings","neurons","pathways","reflexes","receptors","spreadsheets","cortex_action_plans","routines"]},"limit":{"type":"integer","minimum":1,"maximum":200},"full_heads":{"type":"boolean"},"offset":{"type":"integer","minimum":0,"maximum":500000},"include_total":{"type":"boolean"}},"required":["type"]}}}},"responses":{"200":{"description":"Browse list payload (same list mode shape as lexical search jobs)"}}}},"/v1/browse/resource-tree":{"post":{"summary":"Unified memory tree + Mongo resource heads (child-list kinds)","description":"Returns folder structure under native store paths (`/…`, e.g. assets) plus indexed resources (e.g. pathways, engagement graphs) merged at the browse parent. Requires `brain_id` in body or `X-Brain-Id`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"},"parent_key":{"type":"string","description":"ResourceStoreRow path segment or empty for roots"},"parent_keys":{"type":"array","maxItems":32,"items":{"type":"string"},"description":"Vault batch: multiple folder paths in one round-trip (exclusive with parent_key). Response mode is `resource_browse_batch`."}}}}}},"responses":{"200":{"description":"Nested browse nodes + structure fingerprint"},"400":{"description":"Validation or brain scope error"}}}},"/v1/browse/resource-by-id":{"post":{"summary":"Resolve one resource head to a ResourceBrowseNode (vault lane access + resource:head cache)","description":"Returns at most one browse node for `resource_id` when the head is visible for the session brain (same rules as `POST /v1/browse/resource-tree`). Requires `brain_id` in body or `X-Brain-Id`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"},"resource_id":{"type":"string","format":"uuid"},"browse_kind_filters":{"type":"array","items":{"type":"string"}},"vault_lane_documents":{"type":"boolean"}},"required":["resource_id"]}}}},"responses":{"200":{"description":"`mode: resource_browse_node` with `node` or null"},"400":{"description":"Validation or brain scope error"}}}},"/v1/search":{"post":{"summary":"Unified brain-wide resource discovery (sync). Requires X-Brain-Id.","description":"Brain-wide **`POST /v1/search`**: **`query`** is plain search text (**no facet grammar** — no path prefixes such as neurons/..., optional **`search_mode`** `hybrid` (default), `lexical`, or **`vector`**, optional catalog **`filters`**. Returns merged ranked **`results`** and **`normalized`** across document-lane facets **`assets`** and **`artifacts`** only, with **`brain_wide: true`** and applied **`search_mode`**. Async **`GET /v1/search`** defaults to all semantic facets when `types` is omitted.","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","description":"Plain search query (brain-wide)."},"search_mode":{"type":"string","enum":["hybrid","lexical","vector"],"description":"Default hybrid; use lexical for native grep parity."},"filters":{"type":"object","properties":{"is_active":{"type":"boolean"},"visibility":{"type":"string","enum":["public","private"]}}}},"required":["query"]}}}},"responses":{"200":{"description":"`{ brain_wide, search_mode, results, normalized?, total }` — merged facets; no single `type` bucket."}}},"get":{"summary":"Async multi-type search (returns job_id)","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"types","in":"query","required":false,"schema":{"type":"string","description":"JSON array of path plurals or a single type"}},{"name":"type","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"schema":{"type":"string"}},{"name":"threshold","in":"query","required":false,"schema":{"type":"string"}},{"name":"is_active","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}},{"name":"visibility","in":"query","required":false,"schema":{"type":"string","enum":["public","private"]}},{"name":"filters","in":"query","required":false,"schema":{"type":"string","description":"URL-encoded JSON object, e.g. {\"is_active\":true,\"visibility\":\"public\"}. Flat is_active/visibility override the same keys."}},{"name":"search_mode","in":"query","required":false,"schema":{"type":"string","enum":["hybrid","lexical","vector"]}}],"responses":{"200":{"description":"Job id"}}}},"/v1/tools":{"get":{"summary":"List native tools metadata","description":"Returns built-in tool names, descriptions, and JSON schemas.","responses":{"200":{"description":"Tool metadata array"}}}},"/v1/config/models":{"get":{"summary":"List available chat models","responses":{"200":{"description":"Model catalog"}}}},"/v1/config/embedding-model":{"get":{"summary":"Get the active embedding model","responses":{"200":{"description":"Embedding model and dimension"}}}},"/v1/config/cost-estimates":{"get":{"summary":"Get current cost estimates","responses":{"200":{"description":"Cost estimate response"}}}},"/v1/transcribe":{"post":{"summary":"Enqueue STT on ingested audio","description":"JSON body with `source` (`resource_id` from asset ingest). Upload bytes first via POST /v1/assets. Poll GET /v1/jobs/:id/status for `{ text, segments? }`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["source"],"properties":{"source":{"type":"object","required":["type","id"],"properties":{"type":{"type":"string","enum":["resource_id"]},"id":{"type":"string","format":"uuid"}}},"locale":{"type":"string"},"diarize":{"type":"boolean"},"diarization_config":{"type":"object"},"writeback":{"type":"string","enum":["none","resource_spine"]}}}}}},"responses":{"200":{"description":"{ job_id }"}}}},"/v1/public/receptors/by-id/{receptor_id}":{"get":{"summary":"Resolve a public receptor by id","description":"Share token required (query t). Same payload shape as workspace+slug resolve.","parameters":[{"name":"receptor_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"t","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Public receptor metadata"},"404":{"description":"Not found"}}}},"/v1/public/receptors/by-id/{receptor_id}/execute":{"post":{"summary":"Invoke a public receptor by id","parameters":[{"name":"receptor_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"t","in":"query","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Execution result"},"400":{"description":"Validation error"}}}},"/v1/public/receptors/{workspace_slug}/{slug}":{"get":{"summary":"Resolve a public receptor","parameters":[{"name":"workspace_slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"t","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Public receptor metadata"},"404":{"description":"Not found"}}}},"/v1/public/receptors/{workspace_slug}/{slug}/execute":{"post":{"summary":"Invoke a public receptor","parameters":[{"name":"workspace_slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"t","in":"query","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Execution result"},"400":{"description":"Validation error"}}}},"/v1/public/traces/{traceId}":{"get":{"summary":"Get a public trace (slim metadata; t + workspace + receptor, or t + receptor_id)","parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}},{"name":"t","in":"query","schema":{"type":"string"}},{"name":"workspace","in":"query","schema":{"type":"string"}},{"name":"receptor","in":"query","schema":{"type":"string"}},{"name":"receptor_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Trace payload"},"404":{"description":"Not found"}}}},"/v1/public/resources/{resource_id}":{"get":{"summary":"Public read-only store resource + chunks (share link; query t = raw token)","parameters":[{"name":"resource_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"t","in":"query","required":true,"schema":{"type":"string","description":"Share token (must match metadata hash on the resource row)"}}],"responses":{"200":{"description":"{ resource, chunks, totalCount }"},"401":{"description":"Missing or invalid token"},"404":{"description":"Unknown id; JSON may include code RESOURCE_NOT_FOUND"}}}},"/v1/public/traces/{traceId}/events":{"get":{"summary":"Public trace events SSE (Lane A; same t + receptor scope as public transcript; registered on jobs app)","parameters":[{"name":"traceId","in":"path","required":true,"schema":{"type":"string"}},{"name":"t","in":"query","required":true,"schema":{"type":"string"}},{"name":"workspace","in":"query","schema":{"type":"string"}},{"name":"receptor","in":"query","schema":{"type":"string"}},{"name":"receptor_id","in":"query","schema":{"type":"string"}},{"name":"after","in":"query","required":false,"description":"Resume after last-event-id","schema":{"type":"string"}}],"responses":{"200":{"description":"text/event-stream"},"401":{"description":"Missing/invalid share"},"403":{"description":"Trace not in scope"}}}},"/v1/public/jobs/{jobId}/stream":{"get":{"summary":"Public job token SSE (Lane B; receptor share: same t + workspace+receptor or t + receptor_id as invoke)","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}},{"name":"t","in":"query","required":true,"schema":{"type":"string"}},{"name":"workspace","in":"query","schema":{"type":"string"}},{"name":"receptor","in":"query","schema":{"type":"string"}},{"name":"receptor_id","in":"query","schema":{"type":"string"}},{"name":"after","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"text/event-stream"},"401":{"description":"Missing/invalid share"}}}},"/v1/gamification/challenges":{"get":{"summary":"All Cortex rewards (catalog)","responses":{"200":{"description":"Reward ids, points, cadence, category, audit triggers"}}}},"/v1/gamification/me":{"get":{"summary":"Current user Cortex reward state","responses":{"200":{"description":"Cortex points, level, tier ladder, progress_to_next (0-1), points_to_next_level, rewards, daily streak, and weekly momentum"}}},"patch":{"summary":"Update Cortex reward preferences","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"leaderboard_opt_out":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated state"}}}},"/v1/gamification/leaderboard":{"get":{"summary":"Cortex rewards leaderboard (members, global, or workspaces)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}},{"name":"scope","in":"query","schema":{"type":"string","enum":["workspace","global","workspaces"],"default":"workspace"}}],"responses":{"200":{"description":"Ranked entries; scope echoes query"}}}},"/v1/workspaces/{id}/subscription":{"get":{"summary":"Get Stripe subscription for workspace","description":"Returns `{ subscription }`. When the workspace has an active Stripe subscription, `subscription` is the Stripe Subscription resource as returned by the Stripe API (same JSON shape as GET https://docs.stripe.com/api/subscriptions/object ). Otherwise `subscription` is null.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Stripe Subscription JSON or null","content":{"application/json":{"schema":{"type":"object","properties":{"subscription":{"nullable":true,"description":"Stripe Subscription object","type":"object","additionalProperties":true}},"required":["subscription"]}}}}}},"delete":{"summary":"Cancel Stripe subscription","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"immediately","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Canceled Stripe Subscription object","content":{"application/json":{"schema":{"type":"object","properties":{"subscription":{"type":"object","additionalProperties":true,"description":"Stripe Subscription"}},"required":["subscription"]}}}}}}},"/v1/workspaces/{id}/subscription/checkout":{"post":{"summary":"Create Stripe Checkout session for self-serve billing","description":"Owner-only. Creates a Stripe-hosted subscription Checkout session. Optional `campaign_slug` applies an eligible server-side campaign discount; raw Stripe coupon/promotion ids are never accepted from clients.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["workspace_id","success_url","cancel_url"],"properties":{"workspace_id":{"type":"string","format":"uuid"},"success_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"},"interval":{"type":"string","enum":["month","year"]},"tier":{"type":"string","enum":["solo","team"]},"enable_automatic_tax":{"type":"boolean"},"campaign_slug":{"type":"string"}}}}}},"responses":{"200":{"description":"Stripe Checkout redirect URL","content":{"application/json":{"schema":{"type":"object","required":["url","session_id"],"properties":{"url":{"type":"string","format":"uri"},"session_id":{"type":"string"}}}}}}}}},"/v1/workspaces/{id}/subscription/campaigns/redeem":{"post":{"summary":"Redeem a workspace billing campaign","description":"Owner-only. Applies workspace-scoped campaign bonus usage through `workspace_quotas.bonus_monthly_cost_budget_usd`; plan baseline, Stripe prices, and seat counts are unchanged.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["workspace_id","campaign_slug"],"properties":{"workspace_id":{"type":"string","format":"uuid"},"campaign_slug":{"type":"string"}}}}}},"responses":{"200":{"description":"Campaign redemption result","content":{"application/json":{"schema":{"type":"object","required":["applied","grant_id","bonus_monthly_cost_budget_usd","campaign"],"properties":{"applied":{"type":"boolean"},"grant_id":{"type":"string","nullable":true},"bonus_monthly_cost_budget_usd":{"type":"number"},"campaign":{"type":"object","required":["slug","benefit","redemption_scope"],"properties":{"slug":{"type":"string"},"benefit":{"type":"string","enum":["stripe_discount","workspace_bonus_usage","user_usage_grant","combined"]},"redemption_scope":{"type":"string","enum":["user","workspace"]}}}}}}}}}}},"/v1/workspaces/{id}/subscription/resume":{"post":{"summary":"Resume a Stripe subscription scheduled for cancellation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Updated Stripe Subscription object","content":{"application/json":{"schema":{"type":"object","properties":{"subscription":{"type":"object","additionalProperties":true,"description":"Stripe Subscription"}},"required":["subscription"]}}}}}}},"/v1/workspaces/{id}/subscription/change-plan":{"post":{"summary":"Change self-serve plan (Solo↔Team, proration)","description":"Owner-only. Replaces Stripe subscription line items for an active subscription. Body: `workspace_id`, `tier` (`solo` | `team`), optional `interval`. Use Checkout when no subscription exists.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["workspace_id","tier"],"properties":{"workspace_id":{"type":"string","format":"uuid"},"tier":{"type":"string","enum":["solo","team"]},"interval":{"type":"string","enum":["month","year"]}}}}}},"responses":{"200":{"description":"Updated Stripe Subscription","content":{"application/json":{"schema":{"type":"object","properties":{"subscription":{"type":"object","additionalProperties":true,"description":"Stripe Subscription"}},"required":["subscription"]}}}}}}},"/v1/referrals/me":{"get":{"summary":"Referral profile for current user","description":"Solo workspaces only (403 on Team/Enterprise). Returns share code, active-period qualified count, and usage multiplier for the referrer. Referred users do not receive a bonus.","responses":{"200":{"description":"Referral profile","content":{"application/json":{"schema":{"type":"object","required":["code","share_url","qualified_count","qualified_count_lifetime","qualified_count_active","usage_multiplier","referral_program_eligible","referral_multiplier_active","billing_period_end","ineligible_reason","qualified_referees"],"properties":{"code":{"type":"string"},"share_url":{"type":"string","format":"uri"},"qualified_count":{"type":"integer"},"qualified_count_lifetime":{"type":"integer"},"qualified_count_active":{"type":"integer"},"usage_multiplier":{"type":"number"},"referral_program_eligible":{"type":"boolean"},"referral_multiplier_active":{"type":"boolean"},"billing_period_end":{"type":"string","format":"date-time","nullable":true},"ineligible_reason":{"type":"string","nullable":true,"enum":["solo_workspace_required","no_active_subscription"]},"qualified_referees":{"type":"array","items":{"type":"object","properties":{"display_name":{"type":"string","nullable":true},"qualified_at":{"type":"string","format":"date-time","nullable":true}}}}}}}}}}}},"/v1/referrals/resolve":{"get":{"summary":"Validate a referral code","parameters":[{"name":"code","in":"query","required":true,"schema":{"type":"string","minLength":4,"maxLength":32}}],"responses":{"200":{"description":"Code is valid","content":{"application/json":{"schema":{"type":"object","required":["valid"],"properties":{"valid":{"type":"boolean","enum":[true]}}}}}},"400":{"description":"Missing code","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean","enum":[false]}}}}}},"404":{"description":"Unknown code","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean","enum":[false]}}}}}}}}},"/v1/brains":{"get":{"summary":"List participating brains","description":"Brains the authenticated user participates in (owner or brain_participants). User-scoped API keys use the key creator identity. Optional query `all=true` requires workspace admin.","parameters":[{"name":"all","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true, list all workspace brains (admin only)."}],"responses":{"200":{"description":"brains array with id, name, slug, kind, role, avatar_url"}}}},"/v1/brains/{id}/owner":{"patch":{"summary":"Transfer brain ownership","description":"Workspace admin or brain `owner_id`. Body: `user_id` (UUID). Rejects personal brains; demotes previous owner participant to `member`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["user_id"],"properties":{"user_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Updated brain and participant list"}}}},"/v1/brains/{id}/participants":{"get":{"summary":"List brain participants","description":"Requires brain access or workspace admin. Returns member-safe enriched rows for each `brain_participants` row.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Participant list","content":{"application/json":{"schema":{"type":"object","required":["participants"],"properties":{"participants":{"type":"array","items":{"type":"object","required":["user_id","role","is_product_owner"],"properties":{"profile_id":{"type":["string","null"],"format":"uuid"},"user_id":{"type":"string","format":"uuid"},"role":{"type":"string"},"is_product_owner":{"type":"boolean"},"directory_redacted":{"type":"boolean"},"workspace_role":{"type":["string","null"]},"status":{"type":["string","null"]},"email":{"type":["string","null"]},"full_name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]}}}}}}}}}}},"post":{"summary":"Add workspace member to a brain","description":"Workspace admin or brain `owner_id`. Body: `user_id` (UUID); optional `role` (only `member`). Rejects personal brains.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["user_id"],"properties":{"user_id":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["member"]}}}}}},"responses":{"200":{"description":"Created participant; includes snapshot and full list"}}}},"/v1/brains/{id}/participants/{userId}":{"delete":{"summary":"Remove a brain participant","description":"Workspace admin or brain owner. Cannot remove the brain product owner user.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean"}}}}}}}}}},"components":{}}