Receptors API
Receptors are the only public entry points for invoking neurons or pathways. Each neuron, pathway, or completion synapse has one receptor with a unique slug. An in-code receptor gateway validates and transforms invoke requests before execution.
User stories (receptor-only):
- List invokable receptors →
GET /v1/receptors
- Get one by slug or ID →
GET /v1/receptors/:workspace_slug/:slug or GET /v1/receptors/by-id/:id
- Invoke (sync or stream) →
POST /v1/receptors/:workspace_slug/:slug/invoke
- Share (create/get/revoke/rotate) →
POST|GET|DELETE|POST /v1/receptors/:workspace_slug/:slug/share and related
There is no synapse execute or synapse CRUD; use receptors and neurons/pathways.
Creating a neuron via POST /v1/neurons automatically creates a receptor. Invoke only via POST /v1/receptors/:workspace_slug/:slug/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, pathway, or completion |
limit | number | Maximum results (default: 20) |
offset | number | Pagination offset |
sortBy | string | Sort field |
sortDirection | string | asc or desc |
Get Receptor
Get a single receptor by slug (with workspace) or by ID.
GET /v1/receptors/:workspace_slug/:slug
GET /v1/receptors/by-id/:id
Path Parameters
| Parameter | Type | Description |
|---|
workspace_slug | string | Workspace slug (e.g. my-workspace) |
slug | string | Receptor slug (e.g. my-neuron) |
id | string | Receptor UUID (use /v1/receptors/by-id/:id; no workspace in path) |
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). For completion receptors, is_active is stored on the receptor row and can be updated via PATCH.
Update Receptor
Update active channels, receptor config, and (for completion receptors) active status. For neuron or pathway targets, is_active updates the target neuron or pathway.
PATCH /v1/receptors/:workspace_slug/:slug
Request Body
| Field | Type | Description |
|---|
active_channels | string[] | e.g. ["http", "cron"] |
config | object | Receptor config (e.g. conditions) |
is_active | boolean | Optional. For completion receptors: update receptor row. For neuron/pathway targets: update the target’s 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/invoke
Path Parameters
| Parameter | Type | Description |
|---|
workspace_slug | string | Workspace slug |
slug | string | Receptor slug |
Request Body
| Field | Type | Description |
|---|
data | object | Payload for the target (e.g. message, messages, or job-specific fields) |
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." } }'