Create a new assistant

  • Updated on Jan 7, 2026
  • Published on Jan 7, 2026
  • 3 minute(s) read
  • RK
 Prev Next
Post
/assistants

Creates a new assistant in the Edmo platform and persists a copy to the local database.

Typical flow:

  1. Your app sends a configuration payload.
  2. Edmo provisions the assistant with the underlying AI/voice providers.
  3. Edmo stores the assistant locally for display and future management.
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.

Body parameters
Expand All
object

Payload used to create a new assistant.

Example{ "name": "Enrollment Assistant", "firstMessage": "Hi, I'm your enrollment assistant. How can I help today?", "firstMessageMode": "assistant-speaks-first", "model": { "provider": "openai", "model": "gpt-4o", "temperature": 0.6 }, "voice": { "provider": "openai", "voiceId": "alloy" }, "maxDurationSeconds": 1800 }
name
string

Assistant display name.

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

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 Required
Valid values[ "openai", "anthropic" ]
model
string Required

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) Required

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
Responses
201

Assistant created successfully.

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 create agents.

object

Standard error response envelope.

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

Human-readable error message.

500

Creation failed due to configuration or provider issues.

object

Standard error response envelope.

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

Human-readable error message.