Get a specific assistant

  • Updated on Jan 7, 2026
  • Published on Jan 7, 2026
  • 2 minute(s) read
  • RK
 Prev Next
Get
/assistants/{id}

Fetches a single assistant from the local database by either its external provider ID or internal database ID.

Security
API Key: CookieAuth
Cookie parameter nameauth-token

Authentication is handled via an auth-token HTTP-only cookie set by the /auth/login endpoint.

  • In a browser, you typically call /auth/login once and the cookie will be stored and automatically sent on subsequent API requests.
  • In API tools (Postman, curl, etc.) you can manually capture the cookie from the Set-Cookie header or configure cookie handling.

This spec models the cookie using apiKey-style auth for documentation purposes.

Path parameters
id
stringRequired

Assistant identifier (external provider ID or local DB ID).

Responses
200

Assistant details.

Expand All
object

A voice/chat agent configuration that defines how the assistant behaves and which model, voice and tools it uses.

Example{ "id": "asst_123", "orgId": "org_abc", "createdAt": "2024-01-01T10:00:00Z", "updatedAt": "2024-01-02T12:00:00Z", "name": "Enrollment Assistant", "firstMessage": "Hi, I'm here to help with your enrollment questions.", "firstMessageMode": "assistant-speaks-first", "model": { "provider": "openai", "model": "gpt-4o", "temperature": 0.7 }, "voice": { "provider": "openai", "voiceId": "alloy" }, "maxDurationSeconds": 1800 }
id
string

Assistant identifier.

orgId
string

Owning organization identifier.

createdAt
string (date-time)
updatedAt
string (date-time)
name
string | null

Human-friendly assistant name shown in the dashboard.

firstMessage
string | null

First message sent by the assistant when a call/chat starts.

firstMessageMode
string | null
Valid values[ "assistant-speaks-first", "assistant-waits-for-user", "assistant-speaks-first-with-model-generated-message" ]
model
object (ModelConfig)

Configuration for the underlying language model (OpenAI / Anthropic).

For non-technical readers, you can think of this as picking which "brain" the agent uses and how creative it should be.

provider
string
Valid values[ "openai", "anthropic" ]
model
string

Model name from the chosen provider.

Examplegpt-4o
temperature
number

Controls creativity. Lower values are more deterministic, higher values more creative and varied.

Minimum0.0
Maximum2.0
Example0.7
maxTokens
integer

Maximum number of tokens the model can generate for a response.

Example1024
voice
object (VoiceConfig)

Voice configuration for spoken responses when used in calls.

provider
string

Voice provider identifier.

Valid values[ "11labs", "azure", "cartesia", "deepgram", "playht", "openai", "edmo" ]
voiceId
string

Voice identifier within the chosen provider.

Examplealloy
transcriber
object (TranscriberConfig)

Speech-to-text configuration used to transcribe calls.

provider
string
Valid values[ "deepgram", "assemblyai", "whisper" ]
model
string | null

Optional model identifier, depending on the provider.

voicemailMessage
string | null
endCallMessage
string | null
endCallPhrases
Array of string | null
string
metadata
object | null
maxDurationSeconds
integer | null
401

Not authenticated or lacking permission to read agents.

object

Standard error response envelope.

Example{ "error": "Failed to load agents. Please try again." }
error
string

Human-readable error message.

404

Assistant not found.

object

Standard error response envelope.

Example{ "error": "Failed to load agents. Please try again." }
error
string

Human-readable error message.

500

Error fetching assistant.

object

Standard error response envelope.

Example{ "error": "Failed to load agents. Please try again." }
error
string

Human-readable error message.