Skip to main content

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.

Quick start (under 2 minutes)

  1. Get an API keySign up at synapse.auvy.ai, 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 synapse.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 automatically:
import { createAUVYClient } from '@auvy-synapse/client'

const auvy = await createAUVYClient.fromApiKey(process.env.AUVY_API_KEY!)
const receptors = await auvy.receptors.list()
Or with explicit configuration (baseUrl is optional; it defaults to https://api.auvy.ai):
const auvy = createAUVYClient({
  baseUrl: 'https://api.auvy.ai', // optional
  apiKey: process.env.AUVY_API_KEY!,
})
Or from 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
const auvy = createAUVYClient.fromEnv()
For the full SDK surface, including public, config, health, stakeholderMap, 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/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 { createAUVYClient, createStream } from '@auvy-synapse/client'

const auvy = await createAUVYClient.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.
For SDK-specific help, use error.getRecoverySuggestion() and Integration patterns.

Next Steps