Preview a resolved snapshot

POST /api/v1/agents/preview-snapshot

Resolve an agent to its fully-materialized Agent Config — the exact object a call would snapshot and run with — without spending the cost of a call. Two modes, same as POST /call: a saved agent by agentId, or an inline transient agent.

What this is for

The dashboard's agent editor uses this for its live "what would actually run" JSON view. Use it in your own tooling to verify a config before saving or dialing — the same validation that gates POST /call runs here, every default is materialized, the endCall tool is seeded, and {{variable}} placeholders are substituted so you can see the final prompt text.

Authentication

X-API-Key: zsk_...

Request body

Field	Type	Required	Notes
`agentId`	string (UUID)	exactly one of the two	Resolve a saved agent.
`agent`	object	exactly one of the two	Inline Agent Config — validated exactly like a transient call.
`contextVariables`	`{string: string}`	—	Substituted into `{{key}}` placeholders in the returned snapshot. Precedence matches a real call: saved defaults < these values (non-blank) < system built-ins.

{{current_time}} / {{current_date}} resolve against the config's timezone. {{user_number}} / {{agent_number}} stay literal in the preview — they only exist on a live call with a direction.

Response

{
  "snapshot": {
    "name": "Sales bot",
    "languages": ["en"],
    "systemPrompt": "You qualify inbound leads for Acme…",
    "timezone": "Asia/Kolkata",
    "greeting": { "firstMessages": ["Hi! Are you looking to evaluate our product?"], "interruptible": false, "speakFirst": "agent", "agentDelayS": 0.0, "userTimeoutS": 3.0 },
    "llm": { "provider": "openai", "model": "gpt-5.4-mini", "temperature": 1.0, "maxTokens": 251, "prewarm": true },
    "stt": { "provider": "soniox", "model": null, "interruptionMinWords": 0, "...": "all six per-provider blocks" },
    "tts": { "provider": "elevenlabs", "model": null, "voice": null, "...": "all six per-provider blocks" },
    "tools": [
      { "type": "endCall", "name": "end_call", "description": "…", "config": { "messageType": "custom", "customMessages": ["Goodbye!"], "audioRecordingId": null } }
    ],
    "...": "every other section, fully materialized"
  }
}

The shape is exactly AgentConfig with all defaults filled in — the same thing a call stores as its config_snapshot.

Examples

curl -X POST https://dashboard.zoxa.ai/api/v1/agents/preview-snapshot \
  -H "X-API-Key: zsk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "contextVariables": { "customer_name": "Aman", "order_id": "ORD-42" }
  }'

const res = await fetch("https://dashboard.zoxa.ai/api/v1/agents/preview-snapshot", {
  method: "POST",
  headers: { "X-API-Key": "zsk_...", "Content-Type": "application/json" },
  body: JSON.stringify({
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    contextVariables: { customer_name: "Aman", order_id: "ORD-42" },
  }),
});
const { snapshot } = await res.json();

import httpx

resp = httpx.post(
    "https://dashboard.zoxa.ai/api/v1/agents/preview-snapshot",
    headers={"X-API-Key": "zsk_..."},
    json={
        "agentId": "550e8400-e29b-41d4-a716-446655440000",
        "contextVariables": {"customer_name": "Aman", "order_id": "ORD-42"},
    },
)
snapshot = resp.json()["snapshot"]

Previewing an inline agent instead:

{
  "agent": {
    "name": "Scratch test",
    "systemPrompt": "You are a test agent.",
    "llm": { "provider": "qwen", "model": "qwen-flash" }
  }
}

Errors

Status	`detail`	When
`400`	validation details	The inline `agent` (or stored config) fails schema validation.
`400`	mode-selection message	`agentId` and `agent` both set, or neither set.
`404`	`"Agent not found"`	`agentId` doesn't resolve in your org.

POST /call — place a call with the same resolved config
Agent Config schema — full shape reference
Context variables — substitution precedence