Documentation Index
Fetch the complete documentation index at: https://docs.auvy.ai/llms.txt
Use this file to discover all available pages before exploring further.
Receptors API
Receptors are gateways: they are how you expose a neuron or pathway to HTTP clients, share links, cron, and channel triggers. They are not the conceptual center of the platform—you configure neurons first; receptors carry auth, slug, active_channels, and routing to that target. For HTTP invoke, receptors are the only supported public entry points (there is no separate “synapse execute” API).
User stories (invoke via receptor):
- List invokable receptors →
GET /v1/receptors
- Get one by slug or receptor UUID →
GET /v1/receptors/:workspace_slug/:slug_or_id (second segment is lowercase slug or UUID)
- Invoke (sync or stream) →
POST /v1/receptors/:workspace_slug/:slug_or_id/invoke
- Share (create/get/revoke/rotate) →
POST|GET|DELETE|POST /v1/receptors/:workspace_slug/:slug_or_id/share and related
There is no synapse execute or synapse CRUD; use receptors and neurons/pathways.
Authenticated vs public: Dashboard and API keys use the paths above. Share links (no API key) use /v1/public/receptors/... — by workspace + slug or /v1/public/receptors/by-id/:receptor_id with ?t=.
Channel triggers (Slack, Teams, …)
Bindings are receptor-scoped resources: GET|POST|PATCH|DELETE /v1/receptor-channel-bindings (dashboard session auth). Map external channel or conversation ids to a receptor; set the same channel in the receptor’s active_channels.
Provider webhooks (Slack Events API, Microsoft Bot Framework messaging endpoint) must use Connect only — https://<connect-host>/v1/trigger-webhooks/slack or /teams. Connect verifies the request and enqueues work via Synapse internal routes; do not point providers at apps/api for these channels.
Create or select a neuron (or pathway), then ensure a receptor targets it (dashboard or API). Invoke only via POST /v1/receptors/:workspace_slug/:slug_or_id/invoke.
List Receptors
List receptors for the authenticated workspace.
Brain scope required. Include the X-Brain-Id header or configure getBrainId in the public client.
| Header | Type | Description |
|---|
X-Brain-Id | string (UUID) | Required. Brain ID for scoping |
Query Parameters
| Parameter | Type | Description |
|---|
target_type | string | Filter by target: neuron or pathway |
limit | number | Maximum results (default: 20) |
offset | number | Pagination offset |
sortBy | string | Sort field |
sortDirection | string | asc or desc |
ids | string | Comma-separated receptor UUIDs (optional filter; max 100) |
Get Receptor
Get a single receptor by workspace slug and slug or receptor UUID in the second path segment.
GET /v1/receptors/:workspace_slug/:slug_or_id
Path Parameters
| Parameter | Type | Description |
|---|
workspace_slug | string | Workspace slug (e.g. my-workspace) |
slug_or_id | string | Receptor slug (e.g. my-neuron) or receptor UUID |
Response (List and Get)
Receptor objects include is_active. For receptors that target a neuron or pathway, is_active reflects the target’s is_active (from the neurons or pathways table).
Update Receptor
Update active channels and receptor config. For neuron or pathway targets, is_active updates the target neuron or pathway.
PATCH /v1/receptors/:workspace_slug/:slug_or_id
Request Body
| Field | Type | Description |
|---|
active_channels | string[] | e.g. ["http", "cron"] |
config | object | Receptor config (e.g. conditions) |
is_active | boolean | Optional. For neuron or pathway targets: updates the target neuron or pathway is_active. |
Invoke (Receptor-First)
Invoke the neuron or pathway behind the receptor. Requires API key or JWT. Body shape depends on target type (neuron vs pathway).
POST /v1/receptors/:workspace_slug/:slug_or_id/invoke
Path Parameters
| Parameter | Type | Description |
|---|
workspace_slug | string | Workspace slug |
slug_or_id | string | Receptor slug or receptor UUID |
Request Body
| Field | Type | Description |
|---|
data | object | Payload for the target (e.g. message, messages, or job-specific fields) |
stream | boolean | Optional; when true, use job streaming (GET /v1/jobs/:jobId/stream) for tokens |
trace_id | string (UUID) | Optional; correlates the run with Trace Chat / engrams when the target is a neuron |
neuron_task_options | object | Optional; merged into the BullMQ job. Same contract as Invoke neuron (pathwayContext, trace_type / traceType for background hygiene). Invalid JSON objects return 400. |
Response
{
"job_id": "uuid",
"status": "pending"
}
Example
const result = await auvy.receptors.invoke('my-workspace', 'feedback-analyzer', {
data: { message: 'Analyze this feedback.' }
})
console.log(result.job_id, result.status)
curl -X POST https://api.auvy.ai/v1/receptors/my-workspace/feedback-analyzer/invoke \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "data": { "message": "Analyze this feedback." } }'