Skip to main content
POST
/
v1
/
agents
Create an agent
curl --request POST \
  --url https://api.speko.dev/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "systemPrompt": "<string>",
  "intent": {
    "language": "<string>",
    "optimizeFor": "latency"
  },
  "voice": "<string>",
  "llmOptions": {
    "temperature": 1,
    "maxTokens": 2,
    "model": "<string>"
  },
  "stackPreferences": {
    "allowedProviders": {
      "stt": [
        "<string>"
      ],
      "llm": [
        "<string>"
      ],
      "tts": [
        "<string>"
      ]
    }
  }
}
'
{
  "id": "<string>",
  "organizationId": "<string>",
  "name": "<string>",
  "systemPrompt": "<string>",
  "voice": "<string>",
  "intent": {
    "language": "<string>",
    "optimizeFor": "latency"
  },
  "llmOptions": {
    "temperature": 1,
    "maxTokens": 2,
    "model": "<string>"
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "stackPreferences": {
    "allowedProviders": {
      "stt": [
        "<string>"
      ],
      "llm": [
        "<string>"
      ],
      "tts": [
        "<string>"
      ]
    }
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.speko.dev/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
name
string
required

Human-readable name. Must be unique within the organization — duplicates return 409.

Required string length: 1 - 120
​
systemPrompt
string
required

Initial agent instructions used as the session-level systemPrompt default.

Minimum string length: 1
​
intent
object
required

Routing defaults stored on an agent row. Hydrated into a session's RoutingIntent when the session is created with agentId and no inline intent. Note: agents accept a smaller optimizeFor enum than the per-session RoutingIntent.

​
voice
string

Default TTS voice id. Omit to let the router pick per provider.

​
llmOptions
object

Optional LLM tuning defaults stored on an agent. Strict object — only these three keys are accepted.

​
stackPreferences
object

Per-agent stack preferences. Empty / missing layers leave the router unconstrained for that layer; failover stays active within the allowed set.

Response

Agent created

Reusable voice persona — systemPrompt + optional voice + routing intent defaults, plus optional llmOptions. Pass the id as agentId on POST /v1/sessions to seed a session from this agent.

​
id
string
required

Agent id, prefixed agent_.

Example:

"agent_01HW..."

​
organizationId
string
required

Owning organization. Always equal to the authenticated org — agents are never visible across orgs.

​
name
string
required

Human-readable name. Unique within an organization.

Required string length: 1 - 120
​
systemPrompt
string
required

Initial agent instructions. Hydrated as the session's systemPrompt default when no per-call value is supplied.

Minimum string length: 1
​
voice
string | null
required

Default TTS voice id. null when unset — the router picks a sane default per provider.

​
intent
object
required

Routing defaults stored on an agent row. Hydrated into a session's RoutingIntent when the session is created with agentId and no inline intent. Note: agents accept a smaller optimizeFor enum than the per-session RoutingIntent.

​
llmOptions
object
required

Optional LLM tuning defaults. null when unset.

​
createdAt
string<date-time>
required
​
updatedAt
string<date-time>
required
​
stackPreferences
object
required

Per-agent stack preferences. null when the agent has no preferences set.