Skip to content

Create a studio

POST
/v1/organizations/{org}/studios
curl --request POST \
--url https://api.caller9.app/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/studios \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "name": "example", "hybrid_count": 0, "cid_display_name": "example", "ai_assistant_id": "example" }'

Creates a studio and provisions one SIP endpoint per on-air hybrid. SIP passwords are returned only in this response. Demo and Basic plans are limited to one studio and one hybrid. Requires a full-access key.

org
required
string format: uuid

Organization ID (UUID). Must be the organization that owns the API key.

Media typeapplication/json
object
name
required
string
<= 255 characters
hybrid_count

Number of on-air hybrid SIP endpoints to provision. Maximum 1 on Demo and Basic plans, 4 otherwise.

integer
0 <= 4
cid_display_name

Caller ID name for outbound calls. Normalized to CNAM (uppercase letters, digits, ., , and spaces, max 15 characters). Defaults to the studio name.

string
<= 255 characters
ai_assistant_id

Telnyx AI Assistant ID used for AI screening.

string
<= 255 characters

The created studio and its SIP credentials.

Media typeapplication/json
object
studio
required

A studio and its configuration. Boolean settings are returned as integers (0 / 1). Returned by GET/PATCH /v1/studios/{studio} and by the organization studio list/create endpoints.

object
guid
required

Studio ID.

string
name
required
string
organization_guid
required

Owning organization ID.

string
cid_number_guid
required

Number used as outbound caller ID, if set.

string | null
cid_display_name
required

Outbound caller ID name (CNAM-normalized).

string
<= 15 characters
busy_all
required

Busy / Do-Not-Disturb is on.

integer
Allowed values: 0 1
auto_dnd_when_empty
required

Act as Do-Not-Disturb when no operator has the studio open.

integer
Allowed values: 0 1
ring_time
required

Seconds before the ring-timeout action (5–60).

integer
hotline_ring_time
required

Ring time for hotline calls, in seconds (5–60).

integer
ai_assistant_id
required

AI assistant used for screening.

string | null
ai_screening_enabled
required

AI screening capability is enabled.

integer
Allowed values: 0 1
hybrid_count
required

Number of on-air hybrid SIP endpoints.

integer
<= 4
screen_all
required

Every inbound call is screened by the AI assistant.

integer
Allowed values: 0 1
screen_all_station_name
required
string
screen_all_show_description
required
string
screen_all_station_location
required
string
contest_enabled
required

Contest Mode capability is enabled.

integer
Allowed values: 0 1
contest_mode
required

A contest is currently armed.

integer
Allowed values: 0 1
contest_target
required

Default winning caller number (1–110).

integer
contest_backups
required

Default number of backup winners (0–100).

integer
contest_post_timeout_secs
required

Default post-contest window in seconds (10–3600).

integer
ring_timeout_action
required
string
Allowed values: none voicemail forward
voicemail_greeting_type
required
string
Allowed values: tts file
voicemail_greeting_tts
required

Text-to-speech greeting text.

string
voicemail_greeting_voice
required

TTS voice ID; null means the platform default voice.

string | null
voicemail_greeting_r2_key
required

Storage key of the uploaded greeting file, if any.

string | null
voicemail_tts_r2_key
required

Storage key of the cached synthesized TTS greeting, if any.

string | null
voicemail_max_seconds
required

Maximum voicemail length in seconds (5–600).

integer
voicemail_record_message
required

Record a message after the greeting.

integer
Allowed values: 0 1
email_voicemails_enabled
required
integer
Allowed values: 0 1
voicemail_email
required
string | null
delete_after_email
required
integer
Allowed values: 0 1
forward_dest_type
required

Ring-timeout forwarding destination type.

string | null
Allowed values: sip phone
forward_sip_address
required

Set when forward_dest_type is sip.

string | null
forward_phone_number
required

E.164 number; set when forward_dest_type is phone.

string | null
moh_mode
required
string
Allowed values: library file pgm
moh_library_guid
required

Selected library track; null means the platform default.

string | null
moh_r2_key
required

Storage key of the uploaded custom Music on Hold file, if any.

string | null
created_at
required

Creation timestamp (ISO 8601).

string
updated_at
required

Last update timestamp (ISO 8601).

string
deleted_at
required

Always null for studios returned by the API.

string | null
sip_endpoints
required
Array<object>

SIP credentials for a newly created studio. The password is only returned once.

object
role

Endpoint role, hybrid_1…hybrid_4.

string
sip_username
string
sip_uri
string
sip_password
string

Example

{
"studio": {
"busy_all": 0,
"auto_dnd_when_empty": 0,
"ai_screening_enabled": 0,
"screen_all": 0,
"contest_enabled": 0,
"contest_mode": 0,
"ring_timeout_action": "none",
"voicemail_greeting_type": "tts",
"voicemail_record_message": 0,
"email_voicemails_enabled": 0,
"delete_after_email": 0,
"forward_dest_type": "sip",
"moh_mode": "library"
}
}

The request was invalid.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Missing, invalid, expired or revoked API key.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

The key isn’t allowed to do this (e.g. a read-only key making a change).

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Not found, or belongs to another organization.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Blocked by the organization’s plan.

Media typeapplication/json
object
error
required
string
Allowed value: plan_limit
limit
required

Which cap was hit, e.g. studios, numbers, ai_screening, trunk_channels.

string
message
required
string

Example

{
"error": "plan_limit"
}

Too many requests for this API key. Retry after Retry-After seconds.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}
Retry-After
integer

Seconds until the rate-limit window resets.