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)
- Get an API key — Sign up at synapse.auvy.ai, then Settings > API Keys > Create API Key.
- Pick an entry point:
REST
TypeScript SDK
CLI
MCP
curl https://api.auvy.ai/v1/receptors -H "Authorization: Bearer YOUR_API_KEY"
npm install @auvy-synapse/client
import { createAUVYClient } from '@auvy-synapse/client'
const auvy = await createAUVYClient.fromApiKey(process.env.AUVY_API_KEY!)
const receptors = await auvy.receptors.list()
npm install -g @auvy-synapse/cli
auvy login --api-key ak_live_...
auvy receptors list
auvy receptors execute YOUR_RECEPTOR_SLUG --message "Hello"
Add https://mcp.auvy.ai/mcp to your MCP client config. See MCP Server.
1. Create an Account and API Key
- Sign up at synapse.auvy.ai.
- Go to Settings > API Keys > Create API Key.
- 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
| Method | Best for | Install |
|---|
| REST API | Any language, curl, custom HTTP clients | None |
| TypeScript SDK | Node/Bun/browser apps with type safety, streaming, retries | npm install @auvy-synapse/client |
| CLI | Terminal workflows, scripting, local testing | npm install -g @auvy-synapse/cli |
| MCP | AI 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
| Issue | What to check |
|---|
| Invalid or missing key | Use Authorization: Bearer YOUR_API_KEY. Key must come from Settings > API Keys. Never use a publishable key for server-side writes. |
| Wrong base URL | Default is https://api.auvy.ai. For self-hosted or local dev, set AUVY_API_URL or SDK baseUrl (no trailing slash). |
| CORS errors | Browser requests need the same origin or a backend proxy. Use publishable key + JWT for frontend, API key for backend. |
| 429 Rate limit | Response includes retryAfter (seconds). Back off and reduce frequency. The SDK retries automatically. |
| 401 / 403 | Verify 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