Pathways API

Pathways are visual workflows that connect neurons and receptors to create complex automation flows.

List Pathways

Get a list of pathways with optional filtering.

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

GET /v1/pathways

Headers

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

Query Parameters

Parameter	Type	Description
`createdBy`	string	Filter by creator UUID
`search`	string	Search by name
`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 pathways = await auvy.pathways.list({})

curl https://api.auvy.ai/v1/pathways \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Brain-Id: YOUR_BRAIN_ID"

Get Pathway

Get a single pathway by ID.

GET /v1/pathways/:id

Path Parameters

Parameter	Type	Description
`id`	string	Pathway UUID

Create Pathway

Create a new pathway.

POST /v1/pathways

Request Body

Field	Type	Required	Description
`name`	string	Yes	Pathway name
`description`	string	No	Pathway description
`pathway_graph`	object	No	Execution graph structure
`pathway_data`	object	No	Design graph structure
`is_active`	boolean	No	Active status (default: `true`)

Example Request

TypeScript
curl

const pathway = await auvy.pathways.create({
  name: 'My Pathway',
  description: 'A sample pathway',
  is_active: true,
})

curl -X POST https://api.auvy.ai/v1/pathways \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Pathway",
    "description": "A sample pathway",
    "is_active": true,
  }'

Update Pathway

Update an existing pathway.

PUT /v1/pathways/:id

Path Parameters

Parameter	Type	Description
`id`	string	Pathway UUID

Request Body

All fields are optional:

Field	Type	Description
`name`	string	Pathway name
`description`	string	Pathway description
`pathway_graph`	object	Execution graph structure
`pathway_data`	object	Design graph structure
`is_active`	boolean	Active status

Delete Pathway

Delete a pathway.

DELETE /v1/pathways/:id

Path Parameters

Parameter	Type	Description
`id`	string	Pathway UUID

Response

{
  "success": true
}

Run a pathway

Start a run in one of two ways:

POST /v1/pathways/:id/execute — pathway ID in path, optional body { "input": { ... }, "trace_id": "<uuid optional>", "pathway_version": <number optional> }. Use pathway_version to run a specific stored version (see Pathway version history below). Omit trace_id to create a new thread trace for this run (engrams, job stream, and tool approval use that id). Returns 202 with { "job_id", "status": "pending" }.
POST /v1/jobs — body { "pathway_id": "<uuid>", "input": { ... } } or { "data": { ... } }. Returns 200 with { "job_id", "status": "pending" }.

Then poll GET /v1/jobs/:jobId/status or consume GET /v1/jobs/:jobId/stream (SSE). For cancel, resume, or submitting input to a waiting run: POST /v1/jobs/:jobId/cancel, POST /v1/jobs/:jobId/resume, POST /v1/jobs/:jobId/input — see Jobs API.

Pathway version history

Each pathway keeps a capped version history on the head document. List summaries: GET /v1/pathways/:id/versions — Fetch one version’s graph: GET /v1/pathways/:id/versions/:version — Promote a past version to the new tip (new version entry): POST /v1/pathways/:id/versions/:version/promote (body optional; workspace_id must match auth if sent). Single-pathway responses include latest_version and version (current tip).

Execute by pathway ID

POST /v1/pathways/:id/execute

Parameter	Type	Description
`id`	path	Pathway UUID

Body (optional): { "input": { ... }, "trace_id": "<uuid>" } — optional trace_id pins engrams and interventions to an existing thread trace; if omitted, the server assigns a new UUID. Response (202): { "job_id", "status": "pending" }.

curl -X POST https://api.auvy.ai/v1/pathways/PATHWAY_ID/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Brain-Id: YOUR_BRAIN_ID" \
  -d '{"input": {"query": "Hello"}}'

Execute via Jobs API (pathway_id in body)

const { job_id } = await auvy.jobs.execute({ pathway_id: 'pathway-uuid', input: { query: 'Hello' } })
const status = await auvy.jobs.getStatus(job_id)

Alternatively, invoke by receptor: POST /v1/receptors/:workspace_slug/:slug_or_id/invoke when the receptor target is a pathway; response includes job_id.

Validate Pathway

Validate a pathway graph structure. Returns validation errors and warnings.

POST /v1/pathways/validate

Request Body

Field	Type	Required	Description
`nodes`	array	No	Nodes array (each with `id`, `type`, `data`)
`edges`	array	No	Edges array (each with `id`, `source`, `target`)

The request body is the pathway graph object. Pass { nodes: [...], edges: [...] } directly.

Response

{
  "valid": true,
  "errors": ["optional array of error strings"],
  "warnings": ["optional array of warning strings"]
}

Example Request

curl -X POST https://api.auvy.ai/v1/pathways/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Brain-Id: YOUR_BRAIN_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [...],
    "edges": [...]
  }'

Compile Pathway

Compile a pathway to an execution graph. Supports both ID-based and DSL formats.

POST /v1/pathways/compile

Request Body

Field	Type	Required	Description
`pathway`	object	Yes	Pathway object with `nodes` and `edges`
`payload`	object	No	Optional input payload for preview
`overrides`	object	No	Optional overrides for compile

Response

Field	Type	Description
`compiled`	object	Execution graph `{ nodes, edges }`
`preview`	object	Optional. When `payload` is provided, `{ input: payload }`
`errors`	string[]	Optional. Compile error messages

{
  "compiled": {
    "nodes": [...],
    "edges": [...]
  },
  "preview": { "input": {} },
  "errors": ["optional array of error strings"]
}

Example Request

curl -X POST https://api.auvy.ai/v1/pathways/compile \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Brain-Id: YOUR_BRAIN_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "pathway": {
      "nodes": [...],
      "edges": [...]
    }
  }'

Pathway Participants

Pathways support multi-user collaboration through participants with different roles.

List Participants

Get all participants for a pathway.

GET /v1/pathways/:id/participants

Path Parameters

Parameter	Type	Description
`id`	string	Pathway UUID

Response

{
  "participants": [
    {
      "id": "participant-uuid",
      "pathway_id": "pathway-uuid",
      "user_id": "user-uuid",
      "role": "editor",
      "added_by": "user-uuid",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Add Participant

Add a user as a participant to a pathway.

POST /v1/pathways/:id/participants

Path Parameters

Parameter	Type	Description
`id`	string	Pathway UUID

Request Body

Field	Type	Required	Description
`user_id`	string	Yes	User UUID to add
`role`	string	No	Role: `owner`, `editor`, or `viewer` (default: `viewer`)

Response

{
  "participant": {
    "id": "participant-uuid",
    "pathway_id": "pathway-uuid",
    "user_id": "user-uuid",
    "role": "editor",
    "added_by": "user-uuid",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Update Participant Role

Update a participant’s role.

PUT /v1/pathways/participants/:participantId

Path Parameters

Parameter	Type	Description
`participantId`	string	Participant UUID

Request Body

Field	Type	Required	Description
`role`	string	Yes	New role: `owner`, `editor`, or `viewer`

Response

{
  "participant": {
    "id": "participant-uuid",
    "pathway_id": "pathway-uuid",
    "user_id": "user-uuid",
    "role": "editor",
    "added_by": "user-uuid",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Remove Participant (by User ID)

Remove a participant from a pathway by user ID.

DELETE /v1/pathways/:id/participants/:userId

Path Parameters

Parameter	Type	Description
`id`	string	Pathway UUID
`userId`	string	User UUID

Response

{
  "success": true
}

Remove Participant (by Participant ID)

Remove a participant from a pathway by participant ID.

DELETE /v1/pathways/participants/:participantId

Path Parameters

Parameter	Type	Description
`participantId`	string	Participant UUID

Response

{
  "success": true
}

Check Participant Role

Check if a user has a specific role on a pathway.

GET /v1/pathways/:id/participants/check-role

Path Parameters

Parameter	Type	Description
`id`	string	Pathway UUID

Query Parameters

Parameter	Type	Required	Description
`user_id`	string	Yes	User UUID to check
`role`	string	Yes	Role to check: `owner`, `editor`, or `viewer`

Response

{
  "hasRole": true
}

Pathway Graph Structure

Pathways use graph structures to define workflows. Two formats are supported:

ID-based Format (persistence, UI)

Nodes and edges use string IDs. Use for stored pathways and the visual editor:

{
  "nodes": [
    {
      "id": "node-1",
      "type": "neuron",
      "data": { "neuron_id": "neuron-uuid" }
    }
  ],
  "edges": [
    { "id": "e1", "source": "node-1", "target": "node-2" }
  ]
}

DSL Format (LLM, inline)

Index-based, no IDs. Node index = array position. Use -1 as edge target for terminal. Branching handles: "true"/"false" (if), "body"/"done" (while), or category name (classify).

{
  "nodes": [
    { "type": "neuron", "data": { "neuron_id": "uuid-here" } },
    { "type": "classify", "data": { "categories": ["urgent", "normal"] } }
  ],
  "edges": [
    [0, 1],
    [1, -1, "urgent"],
    [1, -1, "normal"]
  ]
}

Design Graph (`pathway_data`)

Defines the visual design structure for the UI:

{
  "nodes": [
    {
      "id": "node-1",
      "position": { "x": 100, "y": 100 },
      "data": {}
    }
  ],
  "edges": []
}

Troubleshooting: Pathway not found

When a pathway run or load fails with “Pathway not found”, check the following:

Check	Description
workspace_id	The pathway must belong to the workspace implied by your auth (API key or session). Every pathway row is scoped by `workspace_id`.
Brain scope	Pathway list and create require a brain. For invoke, include the `X-Brain-Id` header. Pathway access uses core access filter (workspace + brain).
is_active	When loading a pathway for execution by `pathway_id`, the loader uses `is_active: true` by default. If the pathway was set inactive, runs will not find it unless a specific version is requested.
pathway_version	Pass it on `POST /v1/pathways/:id/execute` (job invoke payload). The worker loads that version’s graph from Mongo; if omitted, it loads the current head.

Where this applies: loadPathwayGraph (agent-end) loads by pathway_id and workspace_id; list/get in the API use applyCoreAccessFilter with workspace and brain. Verify the pathway exists in the database for the given workspace and brain, and that is_active matches how you are invoking.

Receptors API - Create receptors that route to pathways
Neurons API - Manage neurons used in pathways
API Reference - Start from the focused public API surface

Core API

Platform API

Documentation Index

​Pathways API

​List Pathways

​Headers

​Query Parameters

​Example Request

​Get Pathway

​Path Parameters

​Create Pathway

​Request Body

​Example Request

​Update Pathway

​Path Parameters

​Request Body

​Delete Pathway

​Path Parameters

​Response

​Run a pathway

​Pathway version history

​Execute by pathway ID

​Execute via Jobs API (pathway_id in body)

​Validate Pathway

​Request Body

​Response

​Example Request

​Compile Pathway

​Request Body

​Response

​Example Request

​Pathway Participants

​List Participants

​Path Parameters

​Response

​Add Participant

​Path Parameters

​Request Body

​Response

​Update Participant Role

​Path Parameters

​Request Body

​Response

​Remove Participant (by User ID)

​Path Parameters

​Response

​Remove Participant (by Participant ID)

​Path Parameters

​Response

​Check Participant Role

​Path Parameters

​Query Parameters

​Response

​Pathway Graph Structure

​ID-based Format (persistence, UI)

​DSL Format (LLM, inline)

​Design Graph (pathway_data)

​Troubleshooting: Pathway not found

​Related

Pathways API

List Pathways

Headers

Query Parameters

Example Request

Get Pathway

Path Parameters

Create Pathway

Request Body

Example Request

Update Pathway

Path Parameters

Request Body

Delete Pathway

Path Parameters

Response

Run a pathway

Pathway version history

Execute by pathway ID

Execute via Jobs API (pathway_id in body)

Validate Pathway

Request Body

Response

Example Request

Compile Pathway

Request Body

Response

Example Request

Pathway Participants

List Participants

Path Parameters

Response

Add Participant

Path Parameters

Request Body

Response

Update Participant Role

Path Parameters

Request Body

Response

Remove Participant (by User ID)

Path Parameters

Response

Remove Participant (by Participant ID)

Path Parameters

Response

Check Participant Role

Path Parameters

Query Parameters

Response

Pathway Graph Structure

ID-based Format (persistence, UI)

DSL Format (LLM, inline)

Design Graph (`pathway_data`)

Troubleshooting: Pathway not found

Related