{"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 an invoke 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}/invoke":{"post":{"summary":"Invoke receptor","description":"Invoke neuron or pathway by receptor. Path segment: receptor slug or receptor UUID. Returns job_id; poll GET /v1/jobs/{jobId}/status or GET /v1/jobs/{jobId}/stream.","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","properties":{"message":{"type":"string"},"data":{"type":"object"},"stream":{"type":"boolean"},"trace_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Job id and status"},"400":{"description":"Validation error"}}}},"/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/receptor-channel-bindings":{"get":{"summary":"List receptor channel bindings","description":"Map external channels (Slack, Teams, …) to receptors. Optional query receptor_id, channel.","parameters":[{"name":"receptor_id","in":"query","schema":{"type":"string"}},{"name":"channel","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Bindings"}}},"post":{"summary":"Create receptor channel binding","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Created binding"}}}},"/v1/receptor-channel-bindings/{id}":{"patch":{"summary":"Update receptor channel binding","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated"},"404":{"description":"Not found"}}},"delete":{"summary":"Delete receptor channel binding","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"404":{"description":"Not found"}}}},"/v1/receptor-channels/webhooks/slack":{"post":{"summary":"Removed — use Connect","description":"Gone: Slack Events URL must be Connect /v1/trigger-webhooks/slack.","responses":{"410":{"description":"Gone"}}}},"/v1/receptor-channels/webhooks/email":{"post":{"summary":"Removed — use Connect","responses":{"410":{"description":"Gone"}}}},"/v1/receptor-channels/webhooks/teams":{"post":{"summary":"Removed — use Connect","responses":{"410":{"description":"Gone"}}}},"/v1/internal/receptor-channel-triggers":{"post":{"summary":"Enqueue receptor from trusted channel/cron caller","description":"Bearer AUVY_CONNECT_INTERNAL_SECRET or AUVY_RECEPTOR_TRIGGER_SECRET. Same contract as HTTP invoke body.","responses":{"200":{"description":"job_id or deduped"}}}},"/v1/internal/connect-trigger-delivery":{"post":{"summary":"Normalized trigger delivery from Connect (internal)","description":"Bearer AUVY_CONNECT_INTERNAL_SECRET or AUVY_RECEPTOR_TRIGGER_SECRET. Connect activates triggers; Synapse enqueues typed jobs only.","responses":{"200":{"description":"job_id or deduped"},"400":{"description":"Unknown trigger_key"}}}},"/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/internal/receptor-triggers/teams-event":{"post":{"summary":"Teams event from Connect (internal)","description":"Normalized Teams payload after Connect verified Bot Framework JWT.","responses":{"200":{"description":"job_id or deduped"},"404":{"description":"No binding"}}}},"/v1/internal/receptor-triggers/slack-event":{"post":{"summary":"Slack event from Connect (internal)","description":"Normalized Slack payload after Connect verified signature.","responses":{"200":{"description":"job_id or deduped"},"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/skills":{"get":{"summary":"List skills","description":"Workspace-scoped markdown skills (RAG / tool-linked). Optional brain_id; optional sort.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0}},{"name":"brain_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["created_at","updated_at","name"]}},{"name":"sortDirection","in":"query","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"{ data, total, limit, offset }"}}},"post":{"summary":"Create skill","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["body_md"],"properties":{"body_md":{"type":"string"},"brain_id":{"type":"string","format":"uuid","nullable":true},"path_name":{"type":"string"},"tool_links":{"type":"array"}}}}}},"responses":{"201":{"description":"Created skill"},"400":{"description":"Validation error"}}}},"/v1/skills/{id}":{"get":{"summary":"Get skill by id or path name","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Skill with versioned body"},"404":{"description":"Not found"}}},"put":{"summary":"Update skill","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated skill"}}},"delete":{"summary":"Delete skill","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ deleted: true }"}}}},"/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[{ resource_id, from, to }], optional move_profile (resource|document). Default resource = vault-lane heads policy; document = artifact / vault-document asset / meeting only (native document_move).","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Move result"},"400":{"description":"Invalid body"}}}},"/v1/resources/stakeholder_maps/live":{"get":{"summary":"Live stakeholder map snapshot (memory-derived)","description":"Materializes the current stakeholder graph from stakeholder-kind memories and linked artifacts for the resolved brain scope. Same payload shape as a saved map body; not tied to a single resource head.","parameters":[{"name":"brain_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"stakeholder_limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000}},{"name":"interaction_limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000}}],"responses":{"200":{"description":"Stakeholder map snapshot"},"400":{"description":"Missing brain scope"}}}},"/v1/resources/stakeholder_maps/diff":{"get":{"summary":"Diff two stakeholder map states (live or integer version)","description":"Compares snapshots for `from` and `to`, each `\"live\"` or a positive integer version for the map head. When `resource_id` is omitted, versions resolve against the legacy singleton id for the brain; pass `resource_id` for a specific `stakeholder_map` head.","parameters":[{"name":"brain_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","required":true,"description":"\"live\" or version number as string","schema":{"type":"string"}},{"name":"to","in":"query","required":true,"description":"\"live\" or version number as string","schema":{"type":"string"}},{"name":"resource_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"stakeholder_limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000}},{"name":"interaction_limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000}}],"responses":{"200":{"description":"{ from, to, resource_id?, diff }"},"404":{"description":"Version not found"}}}},"/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`, `stakeholder_maps`). **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`). Stakeholder maps are brain-scoped heads.","parameters":[{"name":"catalog","in":"path","required":true,"schema":{"type":"string","enum":["assets","artifacts","neurons","reflexes","receptors","stakeholder_maps"]}},{"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/stakeholder_maps)"},"404":{"description":"Unknown catalog segment"}}},"post":{"summary":"Create resource for SDK catalog segment","description":"Currently supported only for `catalog=stakeholder_maps` (creates a new stakeholder_map head for the resolved brain scope). Other catalogs return 404.","parameters":[{"name":"catalog","in":"path","required":true,"schema":{"type":"string","enum":["stakeholder_maps"]}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","maxLength":500},"workspace_id":{"type":"string","format":"uuid"},"brain_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"`{ resource_id, title, 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","stakeholder_maps"]}},{"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","stakeholder_maps"]}},{"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","stakeholder_maps"]}},{"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/{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","stakeholder_maps"]}},{"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: 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","stakeholder_maps"]}},{"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","stakeholder_maps"]}},{"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 catalog search-resource embedding for kinds covered by `resolveCatalogEmbeddingPlan`.","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 `apply_patch` uses the same envelope and rules. Product callers may prefer `POST /v1/artifacts/patch` for artifact text.","parameters":[{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["artifact","meeting","pathway","stakeholder_map","cortex_action_plan","skill","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_partial"]},"body_patch":{"type":"object","additionalProperties":true,"description":"Partial structured meeting body (unified spine merge, pathway-style): agenda, notes, summary, attendee_ids, decisions, action_items, transcript_plain_text, transcript_ref, transcription, etc. 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"],"properties":{"patch_mode":{"type":"string","enum":["pathway_partial"]},"name":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"scope":{"type":"string","enum":["brain","workspace","core"]},"is_active":{"type":"boolean"},"pathway_graph":{"type":"object","additionalProperties":true},"pathway_data":{"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":["stakeholder_map_record_version"]},"graph":{"type":"object","additionalProperties":true},"label":{"type":"string","maxLength":500},"change_summary":{"type":"string","maxLength":4000},"stakeholder_limit":{"type":"integer","minimum":1,"maximum":1000},"interaction_limit":{"type":"integer","minimum":1,"maximum":1000},"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_partial"]},"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":["skill_partial"]},"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}}}]}}}},"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/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/{id}":{"get":{"summary":"Get meeting by id","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}/transcription/live/start":{"post":{"summary":"Start live meeting transcription (`voice-live-session` on agent-end; Redis PCM + SSE captions)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"type":"string","description":"Optional Deepgram language hint (e.g. app locale `de` or `en`). Omit for multilingual (`multi`)."}}}}}},"responses":{"200":{"description":"session + job ids"},"409":{"description":"Active session exists"}}}},"/v1/meetings/{id}/transcription/live/events/{sessionId}":{"get":{"summary":"SSE stream of live caption events for a meeting session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"text/event-stream"}}}},"/v1/meetings/{id}/transcription/chunk":{"post":{"summary":"Append base64-encoded linear16 PCM audio to Redis for the durable live voice session (agent-end forwards to Deepgram)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Chunk accepted or intentionally dropped under backpressure"},"404":{"description":"Unknown voice session / tenant mismatch"},"409":{"description":"Job not accepting chunks"}}}},"/v1/meetings/{id}/transcription/live/stop":{"post":{"summary":"Stop live transcription: signal agent-end shutdown, drain append queue, finalize meeting resource state, enqueue post-transcript AI enhancement","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Stop result"},"504":{"description":"Shutdown or Mongo append drain incomplete; safe to retry"}}}},"/v1/voice/sessions":{"post":{"summary":"Start composer live dictation voice session","description":"Enqueues BullMQ `voice-live-session` on agent-end; audio and SSE ingress use Redis streams under metered middleware.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"session id + expiry"},"503":{"description":"Queue / runtime unavailable"}}}},"/v1/voice/sessions/{sessionId}/audio":{"post":{"summary":"Append PCM chunks to composer live voice Redis stream","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Accepted chunk count"},"404":{"description":"Unknown session / tenant mismatch"}}}},"/v1/voice/sessions/{sessionId}/events":{"get":{"summary":"SSE stream of composer dictation captions / session events","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"text/event-stream"}}}},"/v1/voice/sessions/{sessionId}":{"delete":{"summary":"Stop composer live dictation session (shutdown signal to agent-end)","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"ok"},"404":{"description":"Unknown session / tenant mismatch"}}}},"/v1/assets":{"get":{"summary":"List Mongo store rows (lane-scoped)","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)","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}/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"}}},"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"}}],"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/cortex/review":{"post":{"summary":"Enqueue plasticity agent (neuron) run","description":"Invokes the configured plasticity receptor (workspace settings plasticity_receptor_slug or body receptor_slug) so cortex tools run in agent-end neuronExecution. Proposals are created via tools, not a separate batch heuristic.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"202":{"description":"Receptor execution job queued; includes action_plan_id"}}}},"/v1/cortex/action-plans":{"get":{"summary":"List cortex action plans","responses":{"200":{"description":"Cortex action plans"}}},"post":{"summary":"Create cortex action plan","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Created Cortex action plan"}}}},"/v1/cortex/action-plans/{id}":{"get":{"summary":"Get cortex action plan","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cortex action plan"},"404":{"description":"Not found"}}},"patch":{"summary":"Update cortex action plan","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated Cortex action plan"}}}},"/v1/cortex/action-plans/{id}/plasticity-review":{"post":{"summary":"Run plasticity review on an existing action plan","description":"Invokes the same plasticity neuron recorded on the plan (body.plasticity_neuron_id) using the shared neuron invoke shape as POST /v1/cortex/review.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"202":{"description":"Receptor execution job queued"}}}},"/v1/cortex/proposals":{"get":{"summary":"List cortex plasticity proposals","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"trace_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"action_plan_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Proposals"}}},"post":{"summary":"Append proposal to a cortex action plan (requires action_plan_id; cortex_bundle uses ordered items)","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Created proposal"}}}},"/v1/cortex/proposals/{id}":{"get":{"summary":"Get cortex proposal","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Proposal"},"404":{"description":"Not found"}}},"patch":{"summary":"Update proposal status (governance)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated proposal"}}}},"/v1/cortex/proposals/{id}/apply":{"post":{"summary":"Apply approved cortex_bundle (sync or queued)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Applied"},"202":{"description":"Apply job queued"},"409":{"description":"Version conflict"}}}},"/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","stakeholder_maps","meetings","neurons","pathways","reflexes","receptors","cortex_action_plans"]}}],"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","stakeholder_maps","meetings","neurons","pathways","reflexes","receptors","cortex_action_plans"]},"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, stakeholder maps) 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":"Create a transcription job","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"audio_base64":{"type":"string"},"mime_type":{"type":"string"}},"required":["audio_base64"]}}}},"responses":{"200":{"description":"Queued transcription job"}}}},"/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/transcribe":{"post":{"summary":"Transcribe audio for a shared receptor","description":"Requires share token query `t`. Bind the receptor with query `receptor_id`, or with both `workspace` (workspace slug) and `receptor` (receptor slug). Send only one binding style.","parameters":[{"name":"t","in":"query","required":true,"schema":{"type":"string"}},{"name":"receptor_id","in":"query","schema":{"type":"string"}},{"name":"workspace","in":"query","schema":{"type":"string"}},{"name":"receptor","in":"query","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"audio_base64":{"type":"string"},"mime_type":{"type":"string"}},"required":["audio_base64"]}}}},"responses":{"200":{"description":"Queued transcription job"},"400":{"description":"Validation error"},"401":{"description":"Missing or invalid share token or binding"}}}},"/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/stakeholders/briefing/{id}":{"get":{"summary":"Get a stakeholder briefing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Stakeholder briefing payload"},"404":{"description":"Not found"}}}},"/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/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":{}}