Neurons API

Neurons are the agents you configure: model, instructions, memory, tools (via reflexes), and scope (core | workspace | brain). To run HTTP or channel traffic against a neuron, attach or use a receptor that targets it—see Receptors API and Neuron scope.

Unified resource catalog (same spine)

Neurons are kind: neuron on the unified resource spine. Alongside the vertical routes below, you can use the Resources catalog for symmetric list/read/history/version operations:

Operation	Catalog (resource UUID)	Vertical (`/v1/neurons`)
List	`GET /v1/resources/neurons`	`GET /v1/neurons`
Read head by UUID	`GET /v1/resources/neurons/:resource_id`	`GET /v1/neurons/:id` (also accepts name/slug segments)
Version history rows	`GET /v1/resources/neurons/:resource_id/history`	`GET /v1/neurons/:id/versions` (summary shape differs)
Version body snapshot	`GET /v1/resources/neurons/:resource_id/versions/:version`	`GET /v1/neurons/:id/versions/:version`
Promote version → head	`POST /v1/resources/:resource_id/versions/:version/promote`	`POST /v1/neurons/:id/versions/:version/promote`
Delete	`DELETE /v1/resources/neurons/:resource_id` — soft-delete (spine); restore via `POST .../restore`	`DELETE /v1/neurons/:id` — hard remove on the vertical route
Create / update	Use `POST /v1/neurons`, `PUT /v1/neurons/:id` (or central patch where applicable)	—
Invoke / reflex joins	`POST /v1/neurons/:id/invoke`, reflex routes under `/v1/neurons/:id/reflexes`	—

Catalog list and UUID reads apply the same brain-coordinate attachment and core catalog redaction rules as GET /v1/neurons. Slug-style resolution stays on GET /v1/neurons/:segment only. SDK: auvy.neurons.list, UUID auvy.neurons.get, listVersions, getVersion call /v1/resources/neurons/... under the hood. auvy.neurons.softDelete / restore map to catalog delete/restore. Use auvy.neurons for create, update, vertical delete (hard remove), invoke, reflex joins, promoteVersion, get(..., { version }), and get with a non-UUID segment (slug). Prefer auvy.resources.neurons when you want the catalog namespace explicitly (same HTTP).

const rows = await auvy.neurons.list({ search: 'billing' })
const head = await auvy.neurons.get(neuronUuid)

List Neurons

Get a list of neurons with optional filtering.

Brain scope required. Include the X-Brain-Id header or configure getBrainId in the public client.

GET /v1/neurons

Headers

Header	Type	Description
`X-Brain-Id`	string (UUID)	Required. Brain ID for scoping

Query Parameters

Parameter	Type	Description
`search`	string	Search by name or description
`limit`	number	Maximum number of results (default: 20)
`offset`	number	Offset for pagination
`sortBy`	string	Sort field: `created_at`, `updated_at`, `name`
`sortDirection`	string	Sort direction: `asc` or `desc`

Example Request

TypeScript
curl

const neurons = await auvy.neurons.list({
  is_active: true
})

curl https://api.auvy.ai/v1/neurons?is_active=true \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Brain-Id: YOUR_BRAIN_ID"

Get Neuron

Get a single neuron by ID. By default this returns the latest head; pass version=N to return the same full neuron JSON shape hydrated from that historical version.

GET /v1/neurons/:id
GET /v1/neurons/:id?version=N

Path Parameters

Parameter	Type	Description
`id`	string	Neuron UUID

Query Parameters

Parameter	Type	Description
`version`	number	Optional historical resource version. Invalid values return `400`; missing or inaccessible versions return `404`.

Create Neuron

Create a new neuron.

POST /v1/neurons

Request Body

Field	Type	Required	Description
`name`	string	Yes	Neuron name (normalized to a slug-like identifier)
`brain_id`	string (UUID)	Yes*	Brain ID; may be implied by `X-Brain-Id` when using session auth
`description`	string	No	Neuron description
`neuron_config`	object	No	Neuron configuration (see below)
`is_active`	boolean	No	Active status (default: `true`)
`scope`	string	No	`brain` (default), `workspace`, or `core`. See Neuron scope

Neuron Configuration

The neuron_config object can include:

Field	Type	Description
`recollection_ids`	array	Array of recollection UUIDs for memory access (must be valid UUIDs)
`sub_neuron_ids`	array	Array of neuron UUIDs in the same brain this neuron may delegate to; merged with `subagents` for policy and agent-end dynamic `delegate_*` tools
`model`	string	AI model to use
`temperature`	number	Model temperature
`max_tokens`	number	Maximum tokens

The API may normalize or strip unsupported fields when persisting config. Note: A recollection is auto-created on neuron creation and added to recollection_ids if not provided. recollection_ids is preserved during updates unless explicitly changed.

Example Request

TypeScript
curl

const neuron = await auvy.neurons.create({
  name: 'My Neuron',
  description: 'A sample neuron',
  scope: 'brain',
  neuron_config: {
    model: 'claude-haiku-4-5',
    temperature: 0.7
  },
  is_active: true
})

curl -X POST https://api.auvy.ai/v1/neurons \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Brain-Id: YOUR_BRAIN_ID" \
  -d '{
    "name": "My Neuron",
    "description": "A sample neuron",
    "scope": "brain",
    "neuron_config": {
      "model": "claude-haiku-4-5",
      "temperature": 0.7
    },
    "is_active": true
  }'

Update Neuron

Update an existing neuron.

PUT /v1/neurons/:id

Path Parameters

Parameter	Type	Description
`id`	string	Neuron UUID

Request Body

All fields optional:

Field	Type	Description
`name`	string	Neuron name
`description`	string	Neuron description
`neuron_config`	object	Neuron configuration
`is_active`	boolean	Active status
`scope`	string	`brain`, `workspace`, or `core`

When scope changes, the API syncs the matching receptor row’s scope when a receptor targets this neuron.

Delete Neuron

Removes the neuron via DELETE /v1/neurons/:id (hard remove on the vertical route).

DELETE /v1/neurons/:id

Path Parameters

Parameter	Type	Description
`id`	string	Neuron UUID

Response

{
  "success": true
}

Note: This route performs a hard remove (including cache/search invalidation as implemented server-side). For soft-delete and POST /v1/resources/neurons/:resource_id/restore on the unified spine, use Unified resource catalog (DELETE /v1/resources/neurons/:resource_id).

Invoke neuron

Enqueue an asynchronous run for a neuron (same BullMQ receptor-execution job as receptor invoke).

POST /v1/neurons/:id/invoke

Request body (common fields)

Field	Type	Description
`message`	string	User message (or use `data` for structured neuron request)
`data`	object	Structured invoke payload (alternative / extension to `message`)
`trace_id`	string (UUID)	Optional; thread trace for Trace Chat and engram correlation
`stream`	boolean	When true, consume tokens via job stream
`neuron_task_options`	object	Optional worker merge; see below

`neuron_task_options` (trace persistence)

Merged into the job as neuronTaskOptions. Invalid shapes return 400 with a validation message.

Field	Values	Description
`trace_type`	`"thread"` \| `"system"`	Durable engram listing plane: default `thread` (includes delegated children on a user trace). Use `system` for background or worker-style runs so turns stay out of default Trace Chat / thread-scoped listings. Camel `traceType` is equivalent.

Older payloads may still send persisted_trace_type, persistedTraceType, or systemTrace: true; the server normalizes them to traceType before validation. Pathway: When the job includes pathwayContext, pathway-scoped persistence takes precedence. Completion neurons (neuron_type: completion): off-pathway runs already use system; omit neuron_task_options unless you are also passing pathwayContext or other worker fields. Delegate tools: Native delegate_* tools do not accept this object; child runs stay on the parent thread.

Response

{
  "job_id": "uuid",
  "status": "pending",
  "user_engram_id": null
}

Neuron Reflexes

List Neuron Reflexes

Get all reflexes associated with a neuron.

GET /v1/neurons/:id/reflexes

Path Parameters

Parameter	Type	Description
`id`	string	Neuron UUID

Response

Returns array of reflex objects:

[
  {
    "id": "reflex-uuid",
    "name": "My Reflex",
    "type": "sensory",
    "is_active": true,
    "created_at": "2024-01-01T00:00:00Z"
  }
]

Add Reflex to Neuron

Associate a reflex with a neuron.

POST /v1/neurons/:id/reflexes

Path Parameters

Parameter	Type	Description
`id`	string	Neuron UUID

Request Body

Field	Type	Required	Description
`reflex_id`	string	Yes	Reflex UUID

Example Request

TypeScript
curl

await auvy.neurons.addReflex('neuron-uuid', 'reflex-uuid')

curl -X POST https://api.auvy.ai/v1/neurons/uuid/reflexes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reflex_id": "reflex-uuid"
  }'

Remove Reflex from Neuron

Remove a reflex association from a neuron.

DELETE /v1/neurons/:id/reflexes/:reflexId

Path Parameters

Parameter	Type	Description
`id`	string	Neuron UUID
`reflexId`	string	Reflex UUID

Response

{
  "success": true
}

Error Responses

404 - Neuron or reflex not found
409 - Reflex already assigned to neuron (when adding)

Neuron scope — core, workspace, and brain
Receptors API — gateways that invoke neurons
Reflexes API — tool collections used by neurons
Recollections API — memory scopes for neurons
Search — hybrid keyword + semantic discovery (/v1/search)

Core API

Platform API

Neurons

Neurons API

Unified resource catalog (same spine)

List Neurons

Headers

Query Parameters

Example Request

Get Neuron

Path Parameters

Query Parameters

Create Neuron

Request Body

Neuron Configuration

Example Request

Update Neuron

Path Parameters

Request Body

Delete Neuron

Path Parameters

Response

Invoke neuron

Request body (common fields)

`neuron_task_options` (trace persistence)

Response

Neuron Reflexes

List Neuron Reflexes

Path Parameters

Response

Add Reflex to Neuron

Path Parameters

Request Body

Example Request

Remove Reflex from Neuron

Path Parameters

Response

Error Responses

Core API

Platform API

Documentation Index

​Neurons API

​Unified resource catalog (same spine)

​List Neurons

​Headers

​Query Parameters

​Example Request

​Get Neuron

​Path Parameters

​Query Parameters

​Create Neuron

​Request Body

​Neuron Configuration

​Example Request

​Update Neuron

​Path Parameters

​Request Body

​Delete Neuron

​Path Parameters

​Response

​Invoke neuron

​Request body (common fields)

​neuron_task_options (trace persistence)

​Response

​Neuron Reflexes

​List Neuron Reflexes

​Path Parameters

​Response

​Add Reflex to Neuron

​Path Parameters

​Request Body

​Example Request

​Remove Reflex from Neuron

​Path Parameters

​Response

​Error Responses

​Related

Neurons API

Unified resource catalog (same spine)

List Neurons

Headers

Query Parameters

Example Request

Get Neuron

Path Parameters

Query Parameters

Create Neuron

Request Body

Neuron Configuration

Example Request

Update Neuron

Path Parameters

Request Body

Delete Neuron

Path Parameters

Response

Invoke neuron

Request body (common fields)

`neuron_task_options` (trace persistence)

Response

Neuron Reflexes

List Neuron Reflexes

Path Parameters

Response

Add Reflex to Neuron

Path Parameters

Request Body

Example Request

Remove Reflex from Neuron

Path Parameters

Response

Error Responses

Related