Start an Agent Session

Start a service instance

curl --request POST \
  --url https://api.pipecat.daily.co/v1/public/{agentName}/start \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "createDailyRoom": true,
  "dailyRoomProperties": {
    "enable_recording": "cloud"
  },
  "dailyMeetingTokenProperties": {
    "is_owner": true,
    "start_cloud_recording": true
  },
  "enableDefaultIceServers": true,
  "transport": "webrtc",
  "body": {
    "foo": "bar"
  }
}
'

import requests

url = "https://api.pipecat.daily.co/v1/public/{agentName}/start"

payload = {
    "createDailyRoom": True,
    "dailyRoomProperties": { "enable_recording": "cloud" },
    "dailyMeetingTokenProperties": {
        "is_owner": True,
        "start_cloud_recording": True
    },
    "enableDefaultIceServers": True,
    "transport": "webrtc",
    "body": { "foo": "bar" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    createDailyRoom: true,
    dailyRoomProperties: {enable_recording: 'cloud'},
    dailyMeetingTokenProperties: {is_owner: true, start_cloud_recording: true},
    enableDefaultIceServers: true,
    transport: 'webrtc',
    body: JSON.stringify({foo: 'bar'})
  })
};

fetch('https://api.pipecat.daily.co/v1/public/{agentName}/start', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pipecat.daily.co/v1/public/{agentName}/start",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'createDailyRoom' => true,
    'dailyRoomProperties' => [
        'enable_recording' => 'cloud'
    ],
    'dailyMeetingTokenProperties' => [
        'is_owner' => true,
        'start_cloud_recording' => true
    ],
    'enableDefaultIceServers' => true,
    'transport' => 'webrtc',
    'body' => [
        'foo' => 'bar'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pipecat.daily.co/v1/public/{agentName}/start"

	payload := strings.NewReader("{\n  \"createDailyRoom\": true,\n  \"dailyRoomProperties\": {\n    \"enable_recording\": \"cloud\"\n  },\n  \"dailyMeetingTokenProperties\": {\n    \"is_owner\": true,\n    \"start_cloud_recording\": true\n  },\n  \"enableDefaultIceServers\": true,\n  \"transport\": \"webrtc\",\n  \"body\": {\n    \"foo\": \"bar\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pipecat.daily.co/v1/public/{agentName}/start")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"createDailyRoom\": true,\n  \"dailyRoomProperties\": {\n    \"enable_recording\": \"cloud\"\n  },\n  \"dailyMeetingTokenProperties\": {\n    \"is_owner\": true,\n    \"start_cloud_recording\": true\n  },\n  \"enableDefaultIceServers\": true,\n  \"transport\": \"webrtc\",\n  \"body\": {\n    \"foo\": \"bar\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pipecat.daily.co/v1/public/{agentName}/start")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"createDailyRoom\": true,\n  \"dailyRoomProperties\": {\n    \"enable_recording\": \"cloud\"\n  },\n  \"dailyMeetingTokenProperties\": {\n    \"is_owner\": true,\n    \"start_cloud_recording\": true\n  },\n  \"enableDefaultIceServers\": true,\n  \"transport\": \"webrtc\",\n  \"body\": {\n    \"foo\": \"bar\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "token": "eyJzaCI6Im15LWFnZW50Lm15LW9yZyIsImV4cCI6MTcxMjgwMDAwMCwibm9uY2UiOiJhYmMxMjMifQ.dGVzdC1zaWduYXR1cmU",
  "wsUrl": "wss://us-west.api.pipecat.daily.co/ws/generic/my-agent.my-org",
  "body": "eyJjYWxsZXJfaWQiOiJhYmMxMjMifQ==",
  "dailyRoom": "https://cloud-354b1860310a444ba0f528b6a2f467c4.daily.co/qZbK9nyXCDCmQ0zDDZta",
  "dailyToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "sessionId": "639f91d8-d511-4677-a83b-bd7564d5d92f",
  "iceConfig": {
    "iceServers": [
      {
        "urls": [
          "stun:stun.cloudflare.com:3478",
          "turn:turn.cloudflare.com:3478?transport=udp",
          "turn:turn.cloudflare.com:3478?transport=tcp",
          "turns:turn.cloudflare.com:5349?transport=tcp"
        ],
        "username": "g061f2543c0c7aab7d4b087ad407709...",
        "credential": "e6330e0a539d4cfe9cf9f01b9eb2f..."
      }
    ]
  }
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "Unauthorized / token expired",
  "code": "401"
}

POST

{agentName}

start

Start a service instance

curl --request POST \
  --url https://api.pipecat.daily.co/v1/public/{agentName}/start \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "createDailyRoom": true,
  "dailyRoomProperties": {
    "enable_recording": "cloud"
  },
  "dailyMeetingTokenProperties": {
    "is_owner": true,
    "start_cloud_recording": true
  },
  "enableDefaultIceServers": true,
  "transport": "webrtc",
  "body": {
    "foo": "bar"
  }
}
'

import requests

url = "https://api.pipecat.daily.co/v1/public/{agentName}/start"

payload = {
    "createDailyRoom": True,
    "dailyRoomProperties": { "enable_recording": "cloud" },
    "dailyMeetingTokenProperties": {
        "is_owner": True,
        "start_cloud_recording": True
    },
    "enableDefaultIceServers": True,
    "transport": "webrtc",
    "body": { "foo": "bar" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    createDailyRoom: true,
    dailyRoomProperties: {enable_recording: 'cloud'},
    dailyMeetingTokenProperties: {is_owner: true, start_cloud_recording: true},
    enableDefaultIceServers: true,
    transport: 'webrtc',
    body: JSON.stringify({foo: 'bar'})
  })
};

fetch('https://api.pipecat.daily.co/v1/public/{agentName}/start', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pipecat.daily.co/v1/public/{agentName}/start",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'createDailyRoom' => true,
    'dailyRoomProperties' => [
        'enable_recording' => 'cloud'
    ],
    'dailyMeetingTokenProperties' => [
        'is_owner' => true,
        'start_cloud_recording' => true
    ],
    'enableDefaultIceServers' => true,
    'transport' => 'webrtc',
    'body' => [
        'foo' => 'bar'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pipecat.daily.co/v1/public/{agentName}/start"

	payload := strings.NewReader("{\n  \"createDailyRoom\": true,\n  \"dailyRoomProperties\": {\n    \"enable_recording\": \"cloud\"\n  },\n  \"dailyMeetingTokenProperties\": {\n    \"is_owner\": true,\n    \"start_cloud_recording\": true\n  },\n  \"enableDefaultIceServers\": true,\n  \"transport\": \"webrtc\",\n  \"body\": {\n    \"foo\": \"bar\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pipecat.daily.co/v1/public/{agentName}/start")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"createDailyRoom\": true,\n  \"dailyRoomProperties\": {\n    \"enable_recording\": \"cloud\"\n  },\n  \"dailyMeetingTokenProperties\": {\n    \"is_owner\": true,\n    \"start_cloud_recording\": true\n  },\n  \"enableDefaultIceServers\": true,\n  \"transport\": \"webrtc\",\n  \"body\": {\n    \"foo\": \"bar\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pipecat.daily.co/v1/public/{agentName}/start")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"createDailyRoom\": true,\n  \"dailyRoomProperties\": {\n    \"enable_recording\": \"cloud\"\n  },\n  \"dailyMeetingTokenProperties\": {\n    \"is_owner\": true,\n    \"start_cloud_recording\": true\n  },\n  \"enableDefaultIceServers\": true,\n  \"transport\": \"webrtc\",\n  \"body\": {\n    \"foo\": \"bar\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "token": "eyJzaCI6Im15LWFnZW50Lm15LW9yZyIsImV4cCI6MTcxMjgwMDAwMCwibm9uY2UiOiJhYmMxMjMifQ.dGVzdC1zaWduYXR1cmU",
  "wsUrl": "wss://us-west.api.pipecat.daily.co/ws/generic/my-agent.my-org",
  "body": "eyJjYWxsZXJfaWQiOiJhYmMxMjMifQ==",
  "dailyRoom": "https://cloud-354b1860310a444ba0f528b6a2f467c4.daily.co/qZbK9nyXCDCmQ0zDDZta",
  "dailyToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "sessionId": "639f91d8-d511-4677-a83b-bd7564d5d92f",
  "iceConfig": {
    "iceServers": [
      {
        "urls": [
          "stun:stun.cloudflare.com:3478",
          "turn:turn.cloudflare.com:3478?transport=udp",
          "turn:turn.cloudflare.com:3478?transport=tcp",
          "turns:turn.cloudflare.com:5349?transport=tcp"
        ],
        "username": "g061f2543c0c7aab7d4b087ad407709...",
        "credential": "e6330e0a539d4cfe9cf9f01b9eb2f..."
      }
    ]
  }
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "Unauthorized / token expired",
  "code": "401"
}

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:

{ "enable_recording": "cloud" }

dailyMeetingTokenProperties

object

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

See Daily API documentation for supported properties.

Example:

{
  "is_owner": true,
  "start_cloud_recording": true
}

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.

Available options:

daily,

webrtc,

websocket

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" or "webrtc", 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:

{ "foo": "bar" }

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"

iceConfig

object

ICE server configuration (only included when enableDefaultIceServers is true)

Show child attributes

Example:

{
  "iceServers": [
    {
      "urls": [
        "stun:stun.cloudflare.com:3478",
        "turn:turn.cloudflare.com:3478?transport=udp",
        "turn:turn.cloudflare.com:3478?transport=tcp",
        "turns:turn.cloudflare.com:5349?transport=tcp"
      ],
      "username": "g061f2543c0c7aab7d4b087ad407709...",
      "credential": "e6330e0a539d4cfe9cf9f01b9eb2f..."
    }
  ]
}

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Authorizations

Path Parameters

Body

Response