API Reference

The AUVY API is a REST API for invoking receptors and managing core resources. This reference focuses on endpoints you can drive with an API key or share token. All endpoints return JSON, use standard HTTP methods, and follow consistent patterns for authentication, pagination, and error handling. For a step-by-step walkthrough, see Integrate the API.

Base URL and version

The API base URL is https://api.auvy.ai. The current API version is v1 (all paths are under /v1/). The SDK uses this by default; you can override baseUrl for self-hosted or local dev and optionally set apiVersion if a future version is introduced.

Authentication

This reference primarily uses:

Credential	Header	Use case
API Key	`Authorization: Bearer ak_live_...`	Server-to-server, CLI, scripts
Share token	`?t=...` or body field	Public receptor and trace flows

JWT-only workspace-management routes are intentionally excluded from this API-key-focused reference set.

TypeScript SDK
curl

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

// API key (server)
const auvy = await createAUVYClient.fromApiKey(process.env.AUVY_API_KEY!)

// JWT (browser); baseUrl optional (default https://api.auvy.ai)
const auvy = createAUVYClient({
  publishableKey: 'pk_...',
  getAccessToken: () => getSessionToken(),
})

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

See Authentication Guide for the full credential matrix.

Request & Response Format

All request bodies and responses use JSON. Set Content-Type: application/json for POST/PATCH/PUT requests. Success response:

{
  "id": "uuid",
  "slug": "my-receptor",
  "type": "completion",
  "created_at": "2025-01-01T00:00:00Z"
}

Error response:

{
  "message": "Human-readable error message",
  "code": "ERROR_CODE"
}

Code	Status	Meaning
`AUTH_REQUIRED`	401	Missing or invalid credentials
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource does not exist
`VALIDATION_ERROR`	400	Invalid request data
`RATE_LIMIT`	429	Too many requests (check `retryAfter`)

See Integration patterns — Error handling for recovery patterns.

Pagination

List endpoints accept limit and offset query parameters:

TypeScript SDK
curl

const page = await auvy.receptors.list({ limit: 20, offset: 0 })

// Auto-paginate
for await (const receptor of auvy.receptors.paginate({ pageSize: 20 })) {
  console.log(receptor.slug)
}

curl "https://api.auvy.ai/v1/receptors?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response includes pagination metadata:

{
  "data": [],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 100,
    "has_more": true
  }
}

See Integration patterns — Pagination.

Rate Limiting

Requests are rate-limited per API key or user. Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

On 429 responses, back off for retryAfter seconds. The SDK handles this automatically with configurable retry options.

Streaming

Invoke a receptor with stream: true to receive tokens in real time:

TypeScript SDK
curl

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

for await (const chunk of createStream(auvy, job_id)) {
  if (chunk.type === 'token') process.stdout.write(chunk.token)
  if (chunk.type === 'complete') console.log(chunk.result)
}

curl -N -X POST https://api.auvy.ai/v1/receptors/workspace/receptor/invoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "stream": true}'