Quickstart

1. Get an API key

Create an account at app.epho.io, open the API keys page, and create a team key. Copy the plain-text key immediately; it is only shown when created.

Keep these two credentials separate:

• The Epho API key authenticates requests to Epho.
• The provider API key lets the selected harness call OpenAI, Anthropic, or OpenCode Zen.

2. Start a streaming run

This request creates a new chat and streams the turn until it finishes:

curl -N https://app.epho.io/api/v1/chat \
  -H "Authorization: Bearer $EPHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a small HTTP health endpoint and add a test.",
    "harness": "codex",
    "model": "gpt-5.5",
    "provider_api_key": "'"$OPENAI_API_KEY"'"
  }'

-N disables curl's output buffering so SSE frames appear immediately.

The first frame contains the identifiers you need for later reads:

data: {"type":"chat","chat_id":"01K...","turn_id":"01K..."}

Lifecycle and agent events follow:

data: {"type":"event","event":{"type":"status","phase":"provisioning","message":"Creating a new sandbox…"}}
data: {"type":"event","event":{"type":"status","phase":"starting","message":"Starting the agent…"}}

The stream ends with one done frame:

data: {"type":"done","status":"completed","output":"Added /health and its test.","error":null,"artifacts":[]}

3. Queue work instead

For jobs that should survive a client disconnect, use the asynchronous endpoint:

curl https://app.epho.io/api/v1/chat/async \
  -H "Authorization: Bearer $EPHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a small HTTP health endpoint and add a test.",
    "harness": "codex",
    "model": "gpt-5.5",
    "provider_api_key": "'"$OPENAI_API_KEY"'"
  }'

It returns immediately with 202 Accepted:

{
  "chat_id": "01K...",
  "turn_id": "01K..."
}

Read that turn later:

curl https://app.epho.io/api/v1/chat/$CHAT_ID/turns/$TURN_ID/response \
  -H "Authorization: Bearer $EPHO_API_KEY"

Or reconnect to its event stream:

curl -N https://app.epho.io/api/v1/chat/$CHAT_ID/events/subscribe \
  -H "Authorization: Bearer $EPHO_API_KEY"

4. Continue the conversation

Pass the returned chat_id with a new prompt. The chat keeps its harness, model, system prompt, MCP configuration, and sandbox size:

curl -N https://app.epho.io/api/v1/chat \
  -H "Authorization: Bearer $EPHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"$CHAT_ID"'",
    "prompt": "Now add a readiness endpoint.",
    "provider_api_key": "'"$OPENAI_API_KEY"'"
  }'

Only one turn may be active in a chat at a time. Use separate chats for work that needs to run concurrently.