Public API Endpoints
Public endpoints let you resolve and invoke shared receptors without a normal API key or JWT-only workflow. They use a receptor-scoped share token.
Share tokens are scoped to a receptor. Public routes use the workspace slug and receptor slug in the path.
Authentication
- Share token: required, passed as
?t=... or share_token in the body for POST routes.
- User authentication: optional, passed as
Authorization: Bearer YOUR_JWT_TOKEN when you want user attribution on the trace.
Authorization: Bearer YOUR_JWT_TOKEN # optional
?t=YOUR_SHARE_TOKEN
Resolve Public Receptor
Get share-safe receptor metadata for a public link.
GET /v1/public/receptors/:workspace/:slug
receptor, allow_files, and customization.
Invoke Public Receptor
Invoke the receptor using a share token.
POST /v1/public/receptors/:workspace/:slug/execute
Path Parameters
| Parameter | Type | Description |
|---|
workspace | string | Workspace slug |
slug | string | Receptor slug (same slug as GET /v1/receptors/:slug) |
Query Parameters
| Parameter | Type | Description |
|---|
t | string | Share token (required) |
Request Body
| Field | Type | Required | Description |
|---|
share_token | string | Yes | Share token (if not provided in query) |
message | string | Yes | User message |
stream | boolean | No | Enable streaming (default: false) |
Example Request
The client uses workspaceSlug from config and sends the share token plus the payload:
import { createAUVYClient } from '@auvy-synapse/client'
const auvy = createAUVYClient({
baseUrl: 'https://api.auvy.ai',
workspaceSlug: 'workspace-slug',
publishableKey: process.env.NUXT_PUBLIC_AUVY_PUBLISHABLE_KEY!,
getAccessToken: async () => {
const session = await authProvider.getSession()
return session?.access_token || null
}
})
const result = await auvy.public.invoke(
{
auth: 'receptor',
workspaceSlug: 'workspace-slug',
receptorSlug: 'receptor-slug',
token: 'share-token',
},
{ message: 'Hello, AUVY!' }
)
curl -X POST "https://api.auvy.ai/v1/public/receptors/workspace-slug/receptor-slug/execute?t=share-token" \
-H "Content-Type: application/json" \
-d '{"message": "Hello, AUVY!"}'
Share token is required. JWT is optional and used for trace attribution when present.
Transcribe with a Public Receptor
POST /v1/public/receptors/:workspace/:slug/transcribe
{
"share_token": "share-token",
"audio_base64": "base64-audio",
"mime_type": "audio/webm"
}
Get Public Trace
Get public trace metadata using a share token plus the related workspace and receptor.
GET /v1/public/traces/:trace_id
Path Parameters
| Parameter | Type | Description |
|---|
trace_id | string | Trace ID |
Query Parameters
| Parameter | Type | Description |
|---|
t | string | Share token (required) |
workspace | string | Workspace slug (required) |
receptor | string | Receptor slug (required) |
Example Request
const trace = await auvy.public.getTrace('trace-id', 'share-token', 'receptor-slug')
curl "https://api.auvy.ai/v1/public/traces/trace-id?t=share-token&workspace=workspace-slug&receptor=receptor-slug"
Share Token Security
Share tokens are:
- Scoped to a receptor - Each token is tied to a specific receptor (one per neuron/pathway)
- Configurable - Can allow or disallow file uploads and customize appearance
- Revocable - Can be revoked or rotated from the receptor share endpoints