Neurons API

Neurons are the agents you configure: model, instructions, direct knowledge resources, 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 Scope and visibility below.

Role definition & memory lanes

Neurons are instructions-first roles on the resource spine. Charter lives in neuron_config.system_prompt with four sections: Purpose, Domain, Ownership, and Delegation. Mechanical execution config (vault_path, resource_ids, tools, neuron_type) is separate from charter prose.

Lane	Field / store	Purpose
Instructions	`system_prompt`	Accountability charter
Domain	`vault_path`, `resource_ids` → search index chunks	Semantic RAG scope
Episodes	`engrams` (`source_type` / `target_type` = `neuron`)	Prior trace episodes

Engagement (cortex_engagement) is not neuron run context — never pass engagement_resource_id in neuron config or invoke. Engagement canvases are a separate surface; neurons may patch engagements via tools as an action, not receive graph context as input. List episode traces: GET /v1/traces?neuron_id=<neuron_uuid> (requires X-Brain-Id). See NEURON_DEFINITION in the monorepo for the full builder contract.

Catalog vs vertical routes

Neurons are workspace resources with kind neuron. Alongside /v1/neurons below, use the Resources catalog for 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 (catalog); 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 Scope and visibility

Neuron Configuration

The neuron_config object can include:

Field	Type	Description
`resource_ids`	array	Complete array of explicit asset/artifact resource UUIDs available to the neuron
`vault_path`	string	Optional vault folder scope, such as `/policies/eu`, used alongside `resource_ids`
`sub_neuron_ids`	array	Neuron UUIDs in the same brain this neuron may delegate to; merged with `subagents` for policy and 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.

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 search index updates as implemented server-side). For soft-delete and POST /v1/resources/neurons/:resource_id/restore on the workspace catalog, use Catalog vs vertical routes (DELETE /v1/resources/neurons/:resource_id).

Scope and visibility

Every neuron has a scope field: core, workspace, or brain. Scope describes how broadly a neuron is shared and which admin rules apply.

Scope	Meaning
`brain`	Default. Neuron belongs to a single brain; listed and edited in normal brain-scoped flows.
`workspace`	Workspace-wide visibility. Changing to `workspace` requires workspace admin on the tenant.
`core`	Curated platform neurons (e.g. templates, defaults). Creating or promoting to `core` requires core admin validation on the API.

Receptors that target a neuron use the same scope on the receptor row: when you update a neuron’s scope, the API syncs the matching receptor’s scope so triggers stay aligned.

Completion type and trace persistence

Neurons with neuron_type: completion are optimized for structured, single-shot outputs. When executed outside a pathway graph, async execution stores messages as trace_type: "system" so they do not appear in default thread listings—you typically omit neuron_task_options for that behavior. For standard or agentic neurons invoked from cron, tools, or other background jobs, pass neuron_task_options: { trace_type: "system" } on POST /v1/neurons/:id/invoke or receptor invoke when you want the same hygiene. pathwayContext on the job still wins for pathway-scoped runs.

Invoke neuron

Enqueue an asynchronous run for a neuron. This is the direct neuron invoke path — use it for Trace Chat, ad-hoc runs, and SDK automation. Receptor fire is for ingress gates (Slack, email, cron); when a receptor targets a neuron, dashboard test UIs resolve the receptor once then call this route via neurons.invoke.

POST /v1/neurons/:id/invoke

SDK: auvy.neurons.invoke(neuronId, body, options?) — optional third argument passes brainId, signal, or timeoutMs (transport sends X-Brain-Id from client context or per-call brainId).

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 execution options; 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"`	Message listing scope: default `thread` (includes delegated children on a user trace). Use `system` for background runs so turns stay out of default thread listings. Camel `traceType` is equivalent.

Use trace_type (HTTP snake case) or traceType (SDK camel case). Other persistence aliases are rejected by 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 execution 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)

Receptors API — triggers that dispatch neurons
Reflexes API — tool collections used by neurons
Resources — Search — hybrid keyword + semantic discovery

​Neurons API

​Role definition & memory lanes

​Catalog vs vertical routes

​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

​Scope and visibility

​Completion type and trace persistence

​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

Role definition & memory lanes

Catalog vs vertical routes

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

Scope and visibility

Completion type and trace persistence

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