API Reference

The AUVY API is a REST API layered on a unified resource spine: materialized heads, versions, content for large bodies, and chunks for lexical and hybrid search. /v1/browse, /v1/search, /v1/resources/..., and /v1/assets / /v1/artifacts are the main ways to read and mutate durable workspace data. Neurons, pathways, receptors, and reflexes are the same resources under the hood; many also expose vertical routes (/v1/neurons, /v1/receptors, …) for product-shaped CRUD and invoke. This reference focuses on endpoints you can drive with an API key or share token. All endpoints return JSON, use standard HTTP methods, and follow consistent patterns for authentication, pagination, and error handling. For a step-by-step walkthrough, see Integrate the API.

Spine vs vertical routes

Pattern	Purpose
Spine / catalog	Cross-kind browse, symmetric `GET /v1/resources/{catalog}/:id`, history, soft-delete + restore, vault trees — Resources
Document lane	Asset ingest, artifact bodies and patches — Assets and Artifacts
Discovery	`POST /v1/browse`, `POST /v1/browse/resource-tree`, `POST /v1/search` — Browse, Search
Vertical	Slug neurons, receptor invoke/share, pathway execute, reflex CRUD — kind-specific references below

Prefer spine operations when you need one consistent id space and soft-delete semantics; use vertical routes when the request/response shape matches your integration (especially invoke and slug resolution).

Base URL and version

The API base URL is https://api.auvy.ai. The current API version is v1 (all paths are under /v1/). The SDK uses this by default; you can override baseUrl for self-hosted or local dev and optionally set apiVersion if a future version is introduced.

Authentication

This reference primarily uses:

Credential	Header	Use case
API Key	`Authorization: Bearer ak_live_...`	Server-to-server, CLI, scripts
Share token	`?t=...` or body field	Public receptor and trace flows

JWT-only workspace-management routes are intentionally excluded from this API-key-focused reference set.

TypeScript SDK
curl

import { fromApiKey, createAUVYClient } from '@auvy-synapse/client'

// API key (server) — recommended
const auvy = await fromApiKey(process.env.AUVY_API_KEY!)

// JWT (browser); baseUrl optional (default https://api.auvy.ai)
const browser = createAUVYClient({
  publishableKey: 'pk_...',
  getAccessToken: () => getSessionToken(),
})

curl https://api.auvy.ai/v1/receptors \
  -H "Authorization: Bearer YOUR_API_KEY"

See Authentication Guide for the full credential matrix.

Request & Response Format

All request bodies and responses use JSON. Set Content-Type: application/json for POST/PATCH/PUT requests. Success response:

{
  "id": "uuid",
  "slug": "my-receptor",
  "type": "neuron",
  "created_at": "2025-01-01T00:00:00Z"
}

Error response:

{
  "message": "Human-readable error message",
  "code": "ERROR_CODE"
}

Code	Status	Meaning
`AUTH_REQUIRED`	401	Missing or invalid credentials
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource does not exist
`VALIDATION_ERROR`	400	Invalid request data
`RATE_LIMIT`	429	Too many requests (check `retryAfter`)

See Integration patterns — Error handling for recovery patterns.

Pagination

List endpoints accept limit and offset query parameters:

TypeScript SDK
curl

const page = await auvy.receptors.list({ limit: 20, offset: 0 })

// Auto-paginate
for await (const receptor of auvy.receptors.paginate({ pageSize: 20 })) {
  console.log(receptor.slug)
}

curl "https://api.auvy.ai/v1/receptors?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response includes pagination metadata:

{
  "data": [],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 100,
    "has_more": true
  }
}

See Integration patterns — Pagination.

Rate Limiting

Requests are rate-limited per API key or user. Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

On 429 responses, back off for retryAfter seconds. The SDK handles this automatically with configurable retry options.

Streaming

Invoke a receptor with stream: true to receive tokens in real time:

TypeScript SDK
curl

const { job_id } = await auvy.receptors.invoke('workspace', 'receptor', {
  message: 'Hello',
  stream: true,
})

for await (const chunk of createStream(auvy, job_id)) {
  if (chunk.type === 'token') process.stdout.write(chunk.token)
  if (chunk.type === 'complete') console.log(chunk.result)
}

curl -N -X POST https://api.auvy.ai/v1/receptors/workspace/receptor/invoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "stream": true}'

See Integration patterns — Streaming.

OpenAPI Specification

Download OpenAPI Spec

OpenAPI 3.1 specification — import into Postman, Insomnia, or code generators.

Endpoints

Health

Liveness plus optional authenticated workspace and brain context.

Config

Active model metadata, embedding settings, and cost estimates.

Neurons

Agents: model config, prompts, memory, scope, and tool access.

Pathways

Visual workflows connecting neurons and execution steps.

Reflexes

Tool collections from integrations and built-in tools.

Receptors

Gateways: invoke neurons and pathways; list, manage, and share.

Public

Public share endpoints for receptors and traces.

Traces

Execution history and conversation contexts.

Jobs

Job status, results, and streaming.

Resources

Spine hub: browse trees, catalog lists/reads, central patch, resource events.

Assets and Artifacts

Immutable ingested assets and mutable versioned artifacts.

Search

Hybrid keyword + semantic search over spine chunks (/v1/search).

Tools

Native tool metadata and input schemas.

Recollections

Memory scopes attached to traces and neurons.

Meetings

Meeting objects, live transcription, and transcript artifacts.

Stakeholders

Stakeholder map snapshots and briefings.

Usage

Usage statistics and analytics.

Activity

Workspace activity feed.

Core API

Platform API

API Reference

API Reference

Spine vs vertical routes

Base URL and version

Authentication

Request & Response Format

Rate Limiting

Streaming

OpenAPI Specification

Download OpenAPI Spec

Endpoints

Health

Config

Neurons

Pathways

Reflexes

Receptors

Public

Traces

Jobs

Resources

Assets and Artifacts

Search

Tools

Recollections

Meetings

Stakeholders

Usage

Activity

Core API

Platform API

Documentation Index

​API Reference

​Spine vs vertical routes

​Base URL and version

​Authentication

​Request & Response Format

​Pagination

​Rate Limiting

​Streaming

​OpenAPI Specification

Download OpenAPI Spec

​Endpoints

Health

Config

Neurons

Pathways

Reflexes

Receptors

Public

Traces

Jobs

Resources

Assets and Artifacts

Search

Tools

Recollections

Meetings

Stakeholders

Usage

Activity

API Reference

Spine vs vertical routes

Base URL and version

Authentication

Request & Response Format

Pagination

Rate Limiting

Streaming

OpenAPI Specification

Endpoints