Publishing an Agent

Overview

Publish a profile to make it available through an authenticated chat endpoint. This guide covers publishing, issuing keys, calling your agent, and revoking access. See Publishing for the conceptual model.

Prerequisites

An Orca account with the owner or admin role
A profile that runs successfully
Publishing enabled for your deployment

Use the published agent’s publicUrl for chat requests. The agents.example.com host below is a placeholder.

Step 1: Publish a Profile

Publishing is a conductor API call against the public port. The dashboard “Publish” surface wraps the same endpoint; the curl examples below match it byte-for-byte.

curl -X POST https://conductor.example.com/api/profiles/general/publish \
  -H 'Authorization: Bearer ao_...' \
  -H 'Content-Type: application/json' \
  -d '{
        "slug": "general",
        "allowedOrigins": ["https://example.com"],
        "rateLimitRpm": 60,
        "syncMaxDurationSeconds": 90,
        "exposeToolEvents": false
      }'

The response includes the new pub_... row plus the publicUrl derived from CHAT_GATEWAY_PUBLIC_HOST:

{
  "id": "pub_abcd1234",
  "tenantId": "default",
  "profileName": "general",
  "slug": "general",
  "visibility": "private",
  "authMode": "api_key",
  "allowedOrigins": ["https://example.com"],
  "rateLimitRpm": 60,
  "syncMaxDurationSeconds": 90,
  "exposeToolEvents": false,
  "enabled": true,
  "publicUrl": "https://agents.example.com/v1/chat/default/general"
}

Slugs are immutable. To change a slug, unpublish and republish.

Every published agent also carries a monthlyCostCapUsdCents spend cap, defaulting to 5000 ($50/month) if not set at publish time. The conductor enforces this fail-closed: once month-to-date spend for the published agent reaches the cap, chat requests are rejected with 402 Payment Required and {"error": "published_agent_cap_reached", "scope": "published_agent", ...}. Set it explicitly in the publish body, or raise it later with the PATCH call in Step 4.

Step 2: Mint an API Key

API keys are HMAC-hashed with the pepper; the plaintext token is returned exactly once and never recoverable. See API Keys for the auth model.

curl -X POST https://conductor.example.com/api/profiles/general/keys \
  -H 'Authorization: Bearer ao_...' \
  -H 'Content-Type: application/json' \
  -d '{"label": "production website"}'

{
  "id": "key_abcd1234",
  "publishedId": "pub_abcd1234",
  "label": "production website",
  "createdAt": "2026-05-15T10:00:00Z",
  "token": "ao_prod_abcd...22chars..."
}

Persist the token immediately. Re-fetching the keys list returns metadata only.

Step 3: Call the Public Endpoint

Sync Chat

curl -X POST https://agents.example.com/v1/chat/default/general \
  -H 'Authorization: Bearer ao_prod_abcd...' \
  -H 'Content-Type: application/json' \
  -d '{"message": "Hello"}'

{
  "conversation_id": "conv_abcd1234",
  "message": "Hi there.",
  "public_run_id": "prun_abcd1234"
}

Streaming Chat

curl -N -X POST https://agents.example.com/v1/chat/default/general/stream \
  -H 'Authorization: Bearer ao_prod_abcd...' \
  -H 'Content-Type: application/json' \
  -d '{"message": "Stream the answer"}'

event: delta
data: {"text":"Hi"}

event: delta
data: {"text":" there."}

event: done
data: {"conversation_id":"conv_abcd1234","message":"Hi there.","public_run_id":"prun_abcd1234"}

Continuing a Conversation

Thread the conversation_id from any prior response back in the body. The gateway reuses the same runtime session under the hood.

curl -X POST https://agents.example.com/v1/chat/default/general \
  -H 'Authorization: Bearer ao_prod_abcd...' \
  -H 'Content-Type: application/json' \
  -d '{
        "message": "What is my name?",
        "conversation_id": "conv_abcd1234"
      }'

Resume an In-Flight Run

curl -N "https://agents.example.com/v1/chat/default/general/runs/prun_abcd1234/stream" \
  -H 'Authorization: Bearer ao_prod_abcd...'

This /stream endpoint always responds 200 OK with Content-Type: text/event-stream. If the run is still in flight, it forwards live SSE frames as they arrive; if the run already finished, it replays a single reconstructed terminal frame (event: done or event: error) instead. There is also a plain JSON variant without the /stream suffix, GET /v1/chat/default/general/runs/prun_abcd1234, for polling instead of streaming. It returns 202 Accepted with {"public_run_id": ..., "status": ...} while the run is still dispatching or running, 200 OK with the message once it succeeds, 502 Bad Gateway on an upstream error, and 410 Gone if the run was lost.

Step 4: Update or Disable a Published Agent

PATCH /api/profiles/{name}/published accepts any subset of the published knobs plus enabled. Operators can toggle tool-event streaming on an already-published agent with exposeToolEvents, or raise the spend cap (or set monthlyCostCapUsdCents to 0 for uncapped) once it starts blocking traffic. Setting enabled: false is a fast kill switch that survives without losing history.

curl -X PATCH https://conductor.example.com/api/profiles/general/published \
  -H 'Authorization: Bearer ao_...' \
  -H 'Content-Type: application/json' \
  -d '{"rateLimitRpm": 30, "exposeToolEvents": true, "monthlyCostCapUsdCents": 20000, "enabled": true}'

Full unpublish is DELETE /api/profiles/{name}/published. The row is soft-deleted with unpublished_at so the slug becomes immediately reusable for a different profile.

Step 5: Revoke or Rotate Keys

Revoke One Key

curl -X DELETE https://conductor.example.com/api/profiles/general/keys/key_abcd1234 \
  -H 'Authorization: Bearer ao_...'

The gateway returns 401 unauthorized on the very next request that uses the revoked bearer.

Rotate the Bearer Without Downtime

Issue a new key
Roll the new token out to every client
Revoke the old key

The two keys are accepted in parallel; revoke only after every client carries the new bearer.

Common Smoke Test

After deploy, this five-command sequence proves the surface end-to-end:

# 1. Healthcheck
curl -s https://agents.example.com/healthz

# 2. Publish
curl -s -X POST https://conductor.example.com/api/profiles/general/publish \
  -H 'Authorization: Bearer ao_...' -H 'Content-Type: application/json' -d '{}'

# 3. Mint a key
TOKEN=$(curl -s -X POST https://conductor.example.com/api/profiles/general/keys \
  -H 'Authorization: Bearer ao_...' -H 'Content-Type: application/json' \
  -d '{"label":"smoke"}' | jq -r .token)

# 4. Sync chat
curl -s -X POST https://agents.example.com/v1/chat/default/general \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"message":"hello"}'

# 5. Stream chat
curl -N -X POST https://agents.example.com/v1/chat/default/general/stream \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"message":"stream it"}'

See Chat Gateway API for full request and response schemas, and Conductor publish endpoints for every conductor route this guide touches.

Get Started

Core Concepts

Guides

Runbooks

Publishing an Agent

Overview

Prerequisites

Step 1: Publish a Profile

Step 2: Mint an API Key

Step 3: Call the Public Endpoint

Sync Chat

Streaming Chat

Continuing a Conversation

Resume an In-Flight Run

Step 4: Update or Disable a Published Agent

Step 5: Revoke or Rotate Keys

Revoke One Key

Rotate the Bearer Without Downtime

Common Smoke Test

​Overview

​Prerequisites

​Step 1: Publish a Profile

​Step 2: Mint an API Key

​Step 3: Call the Public Endpoint

​Sync Chat

​Streaming Chat

​Continuing a Conversation

​Resume an In-Flight Run

​Step 4: Update or Disable a Published Agent

​Step 5: Revoke or Rotate Keys

​Revoke One Key

​Rotate the Bearer Without Downtime

​Common Smoke Test

Overview

Prerequisites

Step 1: Publish a Profile

Step 2: Mint an API Key

Step 3: Call the Public Endpoint

Sync Chat

Streaming Chat

Continuing a Conversation

Resume an In-Flight Run

Step 4: Update or Disable a Published Agent

Step 5: Revoke or Rotate Keys

Revoke One Key

Rotate the Bearer Without Downtime

Common Smoke Test