Skip to main content

​
Integrate the API

Canonical onboarding: API key → first request → invoke → streaming. Prefer the TypeScript SDK; this guide shows SDK and HTTP side by side. Platform shape: browse and search workspace data with auvy.resources; store documents with auvy.resourceStore. Execution: configure neurons (and pathways), invoke via receptors or auvy.neurons.invoke. See Neurons — Scope and visibility and SDK source of truth. 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, then Admin → API keys → Create API Key.
  2. Pick an entry point (SDK recommended):
npm install @auvy-synapse/client

import { fromApiKey } from '@auvy-synapse/client'
const auvy = await fromApiKey(process.env.AUVY_API_KEY!)
const receptors = await auvy.receptors.list()

​
1. Create an Account and API Key

  1. Sign up at cortex.auvy.ai.
  2. Open Admin → API keys and click 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.

​
Run execution

Ad-hoc neuron runs (scripts, tools, direct agent calls): 
const { job_id } = await auvy.neurons.invoke('neuron-uuid-or-name', {
  message: 'Hello',
})
REST: POST /v1/neurons/:id/invoke — see Neurons API. Receptor triggers (channel ingress, cron, manual test fire): 
const { receptor } = await auvy.receptors.get('my-workspace', 'my-receptor')
const { job_id } = await auvy.receptors.fire(receptor.id, { message: 'Hello' })
REST: POST /v1/receptors/:id/fire — see Receptors API. 
const status = await auvy.jobs.getStatus(job_id)
console.log(status.result)

​
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 Jobs, streaming, and errors 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 { receptor } = await auvy.receptors.get('my-workspace', 'my-receptor')
const { job_id } = await auvy.receptors.fire(receptor.id, {
  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 Jobs, streaming, and errors for SSE details.

​
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 Admin → 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 Admin → 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 Jobs, streaming, and errors.

​
Next Steps