Skip to main content
POST
Start a service instance
This endpoint starts a new instance of a deployed agent. You can optionally create a Daily room for the service to connect to.

Authorizations

Authorization
string
header
required

Authentication using a Pipecat Cloud public API key.

Generate a public API key from your Dashboard (Settings > API Keys > Public > Create key) and include it as a Bearer token in the Authorization header.

Path Parameters

agentName
string
required

Name of the agent to start

Body

application/json
createDailyRoom
boolean
default:false

Whether to create a Daily room for the service instance

Example:

true

dailyRoomProperties
object

Optional configuration for the Daily room. Only used when createDailyRoom is true.

See Daily API documentation for supported properties.

Example:
dailyMeetingTokenProperties
object

Optional configuration for the Daily meeting token. Only used when createDailyRoom is true.

See Daily API documentation for supported properties.

Example:
enableDefaultIceServers
boolean
default:false

Whether to use the default STUN/TURN ICE servers provided by Pipecat Cloud.

Example:

true

transport
enum<string>

Explicitly specify which transport the bot should use. moq starts a Media over QUIC session: the response's moq field carries what the browser transport needs, and createDailyRoom and enableDefaultIceServers cannot be set to true with it. Around a deploy, a moq start can get 409 Conflict; see the 409 response. See the Media over QUIC guide.

Available options:
daily,
webrtc,
websocket,
moq
Example:

"webrtc"

body
object

Arbitrary user data / configuration object to pass to the service instance. Accessible as the first parameter of the bot method or custom entry point. Maximum size: 1 MB for transport: "daily", "webrtc" or "moq", 4 KB for "websocket". For transport: "websocket", the body is returned in the response's body field base64-encoded; the service must be deployed with websocket_auth = "token" to use this encoding convenience. See the Starting Sessions docs for details.

Example:

Response

Service started successfully

token
string

HMAC session token for WebSocket authentication (only when transport is "websocket")

Example:

"eyJzaCI6Im15LWFnZW50Lm15LW9yZyIsImV4cCI6MTcxMjgwMDAwMCwibm9uY2UiOiJhYmMxMjMifQ.dGVzdC1zaWduYXR1cmU"

wsUrl
string

WebSocket URL to connect to (only when transport is "websocket")

Example:

"wss://us-west.api.pipecat.daily.co/ws/generic/my-agent.my-org"

body
string

Base64-encoded JSON body for the bot (only when transport is "websocket" and the request included a body). URL-encode it and append it to wsUrl as the ?body= query parameter when connecting.

Example:

"eyJjYWxsZXJfaWQiOiJhYmMxMjMifQ=="

dailyRoom
string

URL of the created Daily room (if createDailyRoom was set to true)

Example:

"https://cloud-354b1860310a444ba0f528b6a2f467c4.daily.co/qZbK9nyXCDCmQ0zDDZta"

dailyToken
string

Token to access the Daily room (if createDailyRoom was set to true)

Example:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

sessionId
string

Session ID for the created session

Example:

"639f91d8-d511-4677-a83b-bd7564d5d92f"

moq
object

What @pipecat-ai/moq-transport needs to join the session (only when transport is "moq"). Pass the whole response to the transport's connect(), which startBotAndConnect() does for you, and the transport reads this field itself. See the Media over QUIC guide.

iceConfig
object

ICE server configuration (only included when enableDefaultIceServers is true)

Example: