Speko Docs
API Reference

Get agent

Fetch a single agent by id. Scoped to the authenticated organization — agents owned by another org always return 404.

GET
/v1/agents/{id}

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Agent id, prefixed agent_.

Response Body

application/json

application/json

application/json

{
  "id": "agent_01HW...",
  "organizationId": "string",
  "name": "string",
  "systemPrompt": "string",
  "voice": "string",
  "intent": {
    "language": "en-US",
    "optimizeFor": "latency"
  },
  "llmOptions": {
    "temperature": 0,
    "maxTokens": 1,
    "model": "string"
  },
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "stackPreferences": {
    "allowedProviders": {
      "stt": [
        "deepgram"
      ],
      "llm": [
        "openai"
      ],
      "tts": [
        "elevenlabs"
      ],
      "s2s": [
        "openai:gpt-realtime-2.1"
      ]
    }
  },
  "turnHandling": {
    "profile": "conversational",
    "endpointing": {
      "minDelay": 0,
      "maxDelay": 0
    },
    "interruption": {
      "mode": "adaptive",
      "minDuration": 0,
      "minWords": 0
    },
    "turnDetection": true,
    "contextThreshold": true,
    "dtmfToolDescription": "string",
    "amdPrompt": "string",
    "waitForCallee": true,
    "onMachine": "hangup",
    "voicemailMessage": "string"
  }
}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
{
  "error": "not found",
  "code": "NOT_FOUND"
}

Create agent

Persists a reusable voice persona — `systemPrompt`, optional `voice`, routing `intent`, and optional `llmOptions` — keyed by `name` within the authenticated organization. Pass the returned `id` as `agentId` on `POST /v1/sessions` to seed a session from this agent.

Update agent

Partial update — every field on the body is optional and only supplied keys are written.