API Reference

Forwards any request to the specified AI provider. Replace [provider] with one of: openai, anthropic, google, openrouter.

The proxy accepts your Arkna credentials two ways. Both record the run; the first needs no Arkna-specific headers and works with every provider.

Recommended: key in the URL path

Put your Arkna API key and agent name directly in the proxy URL: /proxy/[arkna-key]/[agent-name]/[provider]/*. Your agent keeps sending its own provider key exactly as before; Arkna reads its key from the path and never touches your provider headers. This is the only form that works cleanly with Anthropic (whose own x-api-key header would otherwise collide with Arkna's).

curl -X POST https://api.arkna.com.au/proxy/ark_live_…/my-agent/openai/v1/chat/completions \
  -H "Authorization: Bearer sk-your-openai-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

The Arkna key is stripped from the path before the request is forwarded; the provider never sees it. The response is identical to what the provider would return.

Alternative: Arkna key in a header

If you prefer to keep the provider-style base URL (/proxy/[provider]/*), pass your Arkna key in the X-Api-Key header instead. Use this only for providers that authenticate via Authorization (OpenAI, OpenRouter). Do not use it for Anthropic: its provider key also lives in x-api-key, so the two collide. For Anthropic, use the key-in-path form above.

curl -X POST https://api.arkna.com.au/proxy/openai/v1/chat/completions \
  -H "Authorization: Bearer sk-your-openai-key" \
  -H "X-Api-Key: ark_live_…" \
  -H "X-Agent-Name: my-agent" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Provider URLs

Base paths per provider. Prefix with /proxy/[arkna-key]/[agent-name] for the recommended form, or /proxy for the header form.

Verifies that a proxy connection is working. Sends a simple test request to the specified provider and confirms that the API key is valid.

Request Body

curl -X POST https://api.arkna.com.au/proxy/test \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "apiKey": "sk-your-key"}'

Response (200):

{
  "success": true,
  "provider": "openai",
  "message": "Connection verified"
}

Create a session to group related runs together (e.g., a multi-turn conversation).

Request Body

curl -X POST https://api.arkna.com.au/api/v1/sessions \
  -H "X-Api-Key: ark_live_..." \
  -H "X-Agent-Name: my-agent" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"user_id": "u_123"}}'

Response (201):

{
  "session_id": "sess_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Start recording a new agent run. Returns a run_id you'll use for all subsequent calls in this run.

Request Body

curl -X POST https://api.arkna.com.au/api/v1/runs \
  -H "X-Api-Key: ark_live_..." \
  -H "X-Agent-Name: my-agent" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_type": "api",
    "input": "Summarize the Q4 sales report"
  }'

Response (201):

{
  "run_id": "run_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "running",
  "started_at": "2026-03-18T12:00:00.000Z"
}

Record a step within a run. Steps are automatically hash-chained for tamper-proof integrity (see Hash Chain).

Request Body

Response (201):

{
  "step_id": "step_a1b2c3d4-...",
  "sequence": 1,
  "step_hash": "a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0"
}

Record an external tool call (database query, API call, file read, etc.). If no step_id is provided, Arkna attaches it to the latest step or auto-creates one.

Request Body

Response (201):

{
  "tool_call_id": "tc_a1b2c3d4-..."
}

Capture a snapshot of what the agent knew at a specific point. This powers the "context at this step" feature when you replay a run.

Request Body

Response (201):

{
  "context_packet_id": "ctx_a1b2c3d4-..."
}

Mark a run as completed, failed, or timed out. This triggers hash chain computation and anomaly detection.

Request Body

Response (200):

{
  "run_id": "run_a1b2c3d4-...",
  "status": "completed",
  "duration_ms": 4230,
  "chain_hash": "e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8"
}

List all recorded runs, with optional filtering by agent, status, or time range.

Returns a paginated list of runs with their status, duration, and cost.

Get detailed information about a specific run, including its steps, tool calls, context snapshots, and integrity check results.

Get an enhanced replay of a run with human-readable narratives, anomaly badges, and a summary of what happened. This is what powers the replay view in the dashboard.

Get a simplified event timeline for a run: just the key events in order, without the full replay detail.

Get what the agent knew at a specific step: its system prompt, active instructions, and any documents it had retrieved.

List all API keys for your account. Requires dashboard authentication.

Create a new API key. The full key is only shown once in the response. Save it somewhere secure.