Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.auvy.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Integrate the API

This is the canonical onboarding guide: from account creation to production-ready API usage with error handling and streaming. It focuses on the API-key-controlled surface. Platform shape: durable objects (neurons, pathways, documents, …) live on the unified resource spine—use Browse, Search, Resources, and Assets and Artifacts for discovery and knowledge. Execution is receptor- or neuron-first: configure neurons (and optionally pathways), expose them through receptors when you need a stable HTTP surface, share links, or channel triggers. Most “run this agent” flows end at POST /v1/receptors/:workspace_slug/:slug_or_id/invoke. See Neuron scope for core / workspace / brain. For server-side or cron neuron runs that should not clutter the user’s default thread history, pass neuron_task_options: { trace_type: "system" } on POST /v1/neurons/:id/invoke or on receptor invoke (same object). neuron_type: completion neurons already persist off the default thread plane when not inside a pathway—see Neurons — Invoke neuron.

​
Quick start (under 2 minutes)

  1. Get an API key — Sign up in the dashboard, then Settings > API Keys > Create API Key.
  2. Pick an entry point:
curl https://api.auvy.ai/v1/receptors -H "Authorization: Bearer YOUR_API_KEY"

​
1. Create an Account and API Key

  1. Sign up at cortex.auvy.ai.
  2. Go to Settings > API Keys > Create API Key.
  3. Copy the key immediately — it is shown only once.
Use an API key issued from the dashboard and send it as Authorization: Bearer YOUR_API_KEY.

​
2. Choose Your Integration Method

MethodBest forInstall
REST APIAny language, curl, custom HTTP clientsNone
TypeScript SDKNode/Bun/browser apps with type safety, streaming, retriesnpm install @auvy-synapse/client
CLITerminal workflows, scripting, local testingnpm install -g @auvy-synapse/cli
MCPAI assistants (Cursor, Claude, ChatGPT)Add server URL to MCP config

​
3. Make Your First Request

​
REST (curl)

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

​
TypeScript SDK

The simplest setup uses fromApiKey — it resolves the base URL and workspace from your key: 
import { fromApiKey } from '@auvy-synapse/client'

const auvy = await fromApiKey(process.env.AUVY_API_KEY!)
// or: await fromApiKey() when AUVY_API_KEY is set
const receptors = await auvy.receptors.list()
Advanced: manual configuration with createAUVYClient (baseUrl defaults to https://api.auvy.ai): 
import { createAUVYClient } from '@auvy-synapse/client'

const auvy = createAUVYClient({
  baseUrl: 'https://api.auvy.ai', // optional
  apiKey: process.env.AUVY_API_KEY!,
})
Environment variables: AUVY_API_URL is optional (default https://api.auvy.ai): 
AUVY_API_KEY=ak_live_...
# Optional: AUVY_API_URL=https://api.auvy.ai

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

const auvy = await fromApiKey()
For the full SDK surface, including public, config, health, and advanced backend helpers, see the TypeScript SDK docs.

​
Invoke a Receptor

Receptors are the entry points for neurons and pathways. You need the workspace slug and receptor slug: 
const { job_id } = await auvy.receptors.invoke('my-workspace', 'my-receptor', {
  message: 'Hello',
})

const status = await auvy.jobs.getStatus(job_id)
console.log(status.result)
REST equivalent: POST /v1/receptors/:workspace_slug/:slug_or_id/invoke — see Receptors API.

​
4. Handle Errors

All API errors return a consistent JSON shape: 
{
  "message": "Human-readable error message",
  "code": "ERROR_CODE"
}
With the SDK, catch AUVYError for typed error handling: 
import { AUVYError, ERROR_CODES } from '@auvy-synapse/client'

try {
  await auvy.receptors.get('my-workspace', 'my-receptor')
} catch (error) {
  if (error instanceof AUVYError) {
    console.error(error.message)
    console.log(error.getRecoverySuggestion())

    if (error.code === ERROR_CODES.NOT_FOUND) {
      // receptor doesn't exist
    }
    if (AUVYError.isRateLimitError(error)) {
      // back off and retry
    }
  }
}
See Integration patterns for recovery patterns and retry strategies.

​
5. Add Streaming

For long-running executions, request a token stream: 
import { fromApiKey, createStream } from '@auvy-synapse/client'

const auvy = await fromApiKey(process.env.AUVY_API_KEY!)

const { job_id } = await auvy.receptors.invoke('my-workspace', 'my-receptor', {
  message: 'Analyze this document',
  stream: true,
})

for await (const chunk of createStream(auvy, job_id)) {
  if (chunk.type === 'token' && chunk.token) {
    process.stdout.write(chunk.token)
  }
  if (chunk.type === 'complete') {
    console.log('\nDone:', chunk.result)
  }
}
See Integration patterns for SSE details and advanced patterns.

​
6. Use the OpenAPI Spec

The full OpenAPI 3.1 specification is available at: Import it into Postman, Insomnia, or use it with code generators to produce clients in any language.

​
Troubleshooting

IssueWhat to check
Invalid or missing keyUse Authorization: Bearer YOUR_API_KEY. Key must come from Settings > API Keys. Never use a publishable key for server-side writes.
Wrong base URLDefault is https://api.auvy.ai. For self-hosted or local dev, set AUVY_API_URL or SDK baseUrl (no trailing slash).
CORS errorsBrowser requests need the same origin or a backend proxy. Use publishable key + JWT for frontend, API key for backend.
429 Rate limitResponse includes retryAfter (seconds). Back off and reduce frequency. The SDK retries automatically.
401 / 403Verify the API key has access to the target workspace and that any required X-Brain-Id context is set.
403 trial_expiredFree workspace trial ended; upgrade in dashboard Workspace Settings → Subscription.
403 cost_capMonthly included spend (USD) for the plan is exceeded; upgrade or wait for the next period.
For SDK-specific help, use error.getRecoverySuggestion() and Integration patterns.

​
Next Steps