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.

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

See Authentication for JWT details.

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/by-id/:receptor_id/assets?t=...

Behavior matches the workspace+slug routes below; the response still includes the receptor’s 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

Returns receptor, allow_files, and customization.

Invoke Public Receptor

Invoke the receptor using a share token.

POST /v1/public/receptors/:workspace/:slug/execute

Path Parameters

Query Parameters

Request Body

Example Request

The client uses workspaceSlug from config and sends the share token plus the payload:

import { createAUVYClient } from '@auvy-os/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!"}'

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

Query Parameters

The same 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=...

Or by receptor id (no workspace slug):

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-os/client).

Public job stream (Lane B, SSE)

For agent-run 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=...

The job must belong to the same workspace and receptor as the share token, or the server returns 403.

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

Related

• Receptors API for creating, reading, deleting, and rotating share tokens.
• Jobs, streaming, and errors for streamed agent-run execution.
• Authentication for share-token and browser-auth setup.