Receptors API
Receptors are triggers — not HTTP invoke gateways. Each receptor listens on configured active_channels (HTTP test fire, cron, Slack, email, …), owns persistence (thread subscriptions, dedupe), and dispatches its configured neuron, pathway, or system job when fired.
Ad-hoc execution (scripts, tools, dashboard test runs on a neuron directly) uses POST /v1/neurons/:id/invoke. Use POST /v1/receptors/:id/fire only to simulate or manually test a trigger (same pipeline as channel ingress).
Stimulus hooks (catalog)
Receptors with active_channels including stimulus subscribe to catalog hooks (vault.*, plasticity.*, maintenance.*).
- List hooks:
GET /v1/stimuli/catalog — add ?schedulable=true for schedule-eligible keys only.
- Configure:
PATCH /v1/receptors/:workspace_slug/:slug with source_config (stimulus_keys, activation: event | schedule, optional timing), executable_target, and optional sensory_reflex_id.
- Schedule sync: When
activation.kind is schedule, Synapse upserts a Connect connect_scheduled_triggers row by receptor_id (internal S2S only). Connect ticks deliver POST /v1/internal/stimulus with scoped receptor_schedule payload.
- Subscribe shortcut:
POST /v1/receptors/subscribe remains for templates; prefer full receptor CRUD + source_config for new integrations.
- Targets:
executable_target.kind may be neuron, pathway, action_plan (create run from stimulus or fork template; optional auto_execute), plasticity_pass (older alias), or system_job (platform hooks).
User stories:
- List receptors →
GET /v1/receptors
- Get one by slug or UUID →
GET /v1/receptors/:workspace_slug/:slug_or_id
- Fire (manual trigger test) →
POST /v1/receptors/:id/fire
- Share (create/get/revoke/rotate) →
POST|GET|DELETE|POST /v1/receptors/:workspace_slug/:slug_or_id/share and related
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=. Public execute fires the share receptor trigger (POST .../execute).
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, platform inbox Resend) must use bots.auvy.ai — POST /v1/chat-webhooks/slack, /teams, or /resend. Do not point providers at Connect or api.auvy.ai for these channels.
Shared inbox inbox@receiver.auvy.ai — enable in Admin → Bots (neuron receptor, Active, Email). Users Bcc the inbox on outbound mail; routing uses the sender’s confirmed login email. Self-hosted: contact support for webhook setup.
Create or select a neuron (or pathway), then ensure a receptor targets it (dashboard or API). Run ad-hoc work with neurons.invoke; fire the trigger with receptors.fire or channel ingress.
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. |
Fire receptor (trigger test)
Manually fire a receptor trigger. Requires API key or JWT. Body is the trigger payload (same shape as channel ingress / share execute).
POST /v1/receptors/:id/fire
Path Parameters
| Parameter | Type | Description |
|---|
id | string (UUID) | Receptor id |
Request Body
| Field | Type | Description |
|---|
invoke | object | Optional wrapper; when omitted, top-level fields are used as the trigger payload |
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 job. Same contract as Invoke neuron. |
Response
{
"job_id": "uuid",
"status": "pending"
}
Example
const { receptor } = await auvy.receptors.get('my-workspace', 'feedback-analyzer')
const result = await auvy.receptors.fire(receptor.id, {
data: { message: 'Analyze this feedback.' },
})
console.log(result.job_id, result.status)
curl -X POST https://api.auvy.ai/v1/receptors/RECEPTOR_UUID/fire \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "invoke": { "data": { "message": "Analyze this feedback." } } }'
- Neurons API – Ad-hoc
POST /v1/neurons/:id/invoke; creating a neuron auto-creates a receptor trigger
- Integrate the API – Neuron invoke + receptor fire patterns