Documentation Index
Fetch the complete documentation index at: https://docs.auvy.ai/llms.txt
Use this file to discover all available pages before exploring further.
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. You can call public routes by workspace + receptor slug or by receptor id (/v1/public/receptors/by-id/:receptor_id). Same token validates either shape.
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 / execute by receptor id (share token)
For id-based UIs (e.g. dashboard links that carry a receptor UUID), use the same t query param:
GET /v1/public/receptors/by-id/:receptor_id?t=...
POST /v1/public/receptors/by-id/:receptor_id/execute?t=...
POST /v1/public/receptors/transcribe?t=...&receptor_id=...
slug for display and stable URLs. Authenticated dashboard reads use GET /v1/receptors/:workspace_slug/:slug_or_id (no separate authenticated by-id path).
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 (matches authenticated GET /v1/receptors/:workspace_slug/:slug_or_id) |
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
Speech-to-text for share links uses one endpoint; bind the receptor the same way as trace share query params (receptor_id or workspace + receptor), plus t:
POST /v1/public/receptors/transcribe?t=...&receptor_id=<uuid>
# or
POST /v1/public/receptors/transcribe?t=...&workspace=<workspace_slug>&receptor=<receptor_slug>
application/json):
{
"audio_base64": "base64-audio",
"mime_type": "audio/webm"
}
share_token in the body is accepted where other public POST routes allow it but is stripped before the job payload (prefer query t).
The response returns a transcription job id:
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 (use with receptor for slug-based links) |
receptor | string | Receptor slug (use with workspace for slug-based links) |
receptor_id | string | Receptor UUID (alternative: use with t for dashboard / by-id share links) |
t + workspace + receptor or t + receptor_id pattern is used for transcript reads on GET /v1/traces/:trace_id/messages and for streaming endpoints below.
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"
Public trace events (Lane A, SSE)
Multiplexed trace events for shared chat UIs (same t scoping as transcript):
GET /v1/public/traces/:trace_id/events?t=...&workspace=...&receptor=...
GET /v1/public/traces/:trace_id/events?t=...&receptor_id=...
- Response:
text/event-stream (SSE), same event shape as GET /v1/traces/:trace_id/events for authenticated access.
- Optional:
after= query (or Last-Event-ID / last-event-id header) to resume after a prior SSE id.
- The TypeScript client builds this URL with
auvy.traces.eventsStreamUrl(traceId, { shareToken: … }) (see buildTraceEventsStreamUrl in @auvy-synapse/client).
Public job stream (Lane B, SSE)
For receptor-execution jobs created from public invoke, stream tokens with the same receptor share query you used for execute:
GET /v1/public/jobs/:job_id/stream?t=...&workspace=...&receptor=...
GET /v1/public/jobs/:job_id/stream?t=...&receptor_id=...
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