Get an agent

GET /api/v1/agents/{agent_uuid}

Fetch one saved agent by its uuid.

One identifier: the UUID

Agents are addressed by uuid everywhere — in this path, in every other CRUD path (PATCH, DELETE, duplicate, test-call), and as agentId in POST /call. There is no integer id in the API surface.

Authentication

X-API-Key: zsk_...

Path parameters

Param	Type	Description
`agent_uuid`	string (UUID)	The agent's `uuid`.

Response

Returns an AgentEnvelope — server-managed metadata wrapping the full validated config:

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "createdAt": "2026-06-01T10:00:00Z",
  "updatedAt": "2026-08-06T09:30:00Z",
  "config": {
    "name": "Sales bot",
    "description": "Qualifies B2B SaaS leads.",
    "languages": ["en"],
    "systemPrompt": "You qualify inbound leads...",
    "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, "...": "per-provider tuning blocks" },
    "tts": { "provider": "elevenlabs", "model": null, "voice": null, "...": "per-provider tuning blocks" },
    "noiseGate": { "enabled": true, "model": "voice-focus", "enhancementLevel": 0.8 },
    "backgroundSound": { "enabled": false, "sound": "library", "volume": 0.08 },
    "taskSound": { "enabled": false, "sound": "typing", "volume": 0.35, "startAfterMs": 800 },
    "acknowledgeSounds": { "enabled": false, "words": "hmm, hm hmm, okay", "wordOrder": "round-robin", "volume": 1.0, "thresholdS": 3.0, "probability": 0.8 },
    "fillerWords": { "enabled": false, "words": "so, yeah, okay", "wordOrder": "round-robin", "thresholdMs": 300, "probability": 0.75 },
    "maxCallDurationS": 610,
    "userIdleTimeoutS": 7,
    "userIdleMessages": ["Are you still there?"],
    "userIdleMaxRetries": 2,
    "tools": [
      "abc12345-6789-0123-4567-89abcdef0123",
      {
        "type": "endCall",
        "name": "end_call",
        "description": "End the call when the user says goodbye, asks to stop, or the conversation is clearly finished.",
        "config": { "messageType": "custom", "customMessages": ["Goodbye!"], "audioRecordingId": null }
      }
    ],
    "voicemailDetection": true,
    "webhook": null,
    "enableSummarization": false,
    "recordInProviderConsole": null,
    "contextVariables": {}
  }
}

Field	Notes
`uuid`	The agent's stable identifier — used in every CRUD path and as `agentId` in `POST /call`.
`status`	`"active"` or `"archived"`. Archived agents 404 on this endpoint and are hidden from default lists.
`config.tools`	Mixed array: saved-tool UUID strings and inline tool objects. Every stored config contains at least the `endCall` tool (auto-seeded).
`config.webhook`	`null` or `{ "url": "…", "headers": { … } }`. The write-only `webhookSecret` is never returned.

Full nested shape: Agent Config schema.

Examples

curl https://dashboard.zoxa.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: zsk_..."

const res = await fetch(`https://dashboard.zoxa.ai/api/v1/agents/${agentUuid}`, {
  headers: { "X-API-Key": "zsk_..." },
});
const agent = await res.json();

import httpx
agent = httpx.get(
    f"https://dashboard.zoxa.ai/api/v1/agents/{agent_uuid}",
    headers={"X-API-Key": "zsk_..."},
).json()

Errors

Status	`detail`	When
`400`	`"No organization selected"`	Auth missing org.
`404`	`"Agent not found"`	UUID doesn't exist in your org, or the agent is archived.

Authentication

Path parameters

Response

Examples

Errors

Related

On this page