Skip to main content

​
Integration Patterns

Common patterns when integrating the AUVY API: streaming, pagination, and error handling. For setup, see Authentication.

​
Streaming

Stream receptor execution in real time via Server-Sent Events. Invoke with stream: true, then consume the job stream.

​
Setup

npm install @auvy-synapse/client

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

const auvy = createAUVYClient({
  baseUrl: process.env.AUVY_API_URL ?? 'https://api.auvy.ai',
  apiKey: process.env.AUVY_API_KEY!
})

​
Invoke with stream, then consume

import { isTokenChunk, isErrorChunk } from '@auvy-synapse/client'

const { job_id } = await auvy.receptors.invoke('my-workspace', 'my-receptor', {
  message: 'Tell me a story',
  stream: true,
})

const stream = auvy.receptors.createStream(job_id)
for await (const chunk of stream) {
  if (isTokenChunk(chunk) && chunk.token) {
    process.stdout.write(chunk.token)
  } else if (isErrorChunk(chunk)) {
    console.error('Error:', chunk.error)
    break
  }
}

​
Stream until complete (callbacks)

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

const result = await auvy.receptors.streamJobUntilComplete(job_id, {
  onToken: (chunk) => process.stdout.write(chunk),
  onComplete: (finalResult) => console.log('Complete:', finalResult),
  onError: (error) => console.error('Error:', error),
})

​
Event types

  • token – Individual tokens
  • content_block – Structured content blocks
  • reflex_call – When a reflex (tool) is called
  • signal – System signals
  • state_update – Trace state updates
  • error – Execution errors
  • complete – Execution completed

​
Cancellation

const controller = new AbortController()
setTimeout(() => controller.abort(), 5000)

const { job_id } = await auvy.receptors.invoke('my-workspace', 'my-receptor', { message: 'Long task', stream: true })
const stream = auvy.receptors.createStream(job_id, { signal: controller.signal })
for await (const chunk of stream) { /* ... */ }

​
Best practices

  1. Handle error events and use AbortController for user cancellation.
  2. Abort streams on component unmount or when done.
  3. Invoke with stream: true, then use receptors.createStream(job_id) or streamJobUntilComplete(job_id, callbacks).

​
Pagination

List endpoints support limit and offset. The SDK provides paginate() and listAll().

​
Async iterable (paginate())

Best for memory-efficient iteration. 
for await (const receptor of auvy.receptors.paginate({ pageSize: 20 })) {
  console.log(receptor.slug, receptor.target_type)
}

​
Fetch all (listAll())

Best when you need the full set in memory (small to medium datasets). 
const allReceptors = await auvy.receptors.listAll({ target_type: 'neuron' })

​
Response shape

{
  "data": [],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 100,
    "has_more": true
  }
}
See API Reference — Pagination.

​
Error handling

Use AUVYError for typed handling, retries, and rate limits.

​
Catching and classifying errors

import { AUVYError, ERROR_CODES } from '@auvy-synapse/client'

try {
  await auvy.receptors.get('my-workspace', 'my-receptor-slug')
} catch (error) {
  if (error instanceof AUVYError) {
    if (AUVYError.isAuthError(error)) await reauthenticate()
    else if (AUVYError.isRateLimitError(error)) await waitForRateLimit(error)
    else if (AUVYError.isRetryableError(error)) await retryOperation()
    console.log(error.getRecoverySuggestion())
    const requestId = error.getRequestId()
    if (requestId) console.log('Request ID (for support):', requestId)
  }
}

​
Error type helpers

AUVYError.isAuthError(error)      // 401, 403
AUVYError.isRateLimitError(error) // 429
AUVYError.isRetryableError(error) // Network, timeout, 5xx
AUVYError.isNetworkError(error)   // Network connection

​
Automatic retry

const auvy = createAUVYClient({
  baseUrl: process.env.AUVY_API_URL ?? 'https://api.auvy.ai',
  apiKey: process.env.AUVY_API_KEY!,
  retry: {
    maxRetries: 3,
    retryDelay: 1000,
    maxRetryDelay: 60000,
  },
})

​
Rate limiting

On 429, use retryAfter or headers to back off: 
if (AUVYError.isRateLimitError(error)) {
  const resetTime = error.headers?.['x-ratelimit-reset']
  const waitTime = resetTime ? Math.max(0, parseInt(resetTime) * 1000 - Date.now()) : 60000
  await new Promise(resolve => setTimeout(resolve, waitTime))
}

​
Common issues

IssueWhat to do
Invalid or missing key (401)Use a valid API key from Settings → API Keys; send as Authorization: Bearer KEY.
Wrong base URLDefault https://api.auvy.ai. Override with AUVY_API_URL or baseUrl (no trailing slash).
CORS in browserCall API from backend or allow your origin.
429 Rate limitBack off; use SDK retry options.
Endpoint requires JWTSome routes (e.g. integrations) need user session; see Authentication.
Full checklist: Integrate the API — Troubleshooting.