Hosted REST control API (Bearer-token authenticated) for deploying and operating Pipecat agents on Pipecat Cloud - create/list/update/delete agents, start and stop agent sessions, manage builds, secrets, and organization properties.
openapi: 3.0.1
info:
title: Pipecat Cloud API
description: >-
REST control API for Pipecat Cloud, the hosted platform for deploying and
operating agents built with the open-source Pipecat Python framework. The
Pipecat framework itself is an SDK (the pipecat-ai Python library) and does
not expose a REST API; its interface is Python Pipelines, Frames,
FrameProcessors, Services, and Transports (Daily WebRTC, SmallWebRTC,
LiveKit, FastAPI WebSocket, and telephony serializers). This document models
only the documented Pipecat Cloud REST control plane - managing agents,
starting and stopping sessions, builds, secrets, organization properties,
and regions. Realtime media (audio/video) flows over WebRTC/WebSocket
transports negotiated out of band and is not modeled as REST here.
termsOfService: https://www.daily.co/legal/terms-of-service/
contact:
name: Pipecat / Daily Support
email: help@daily.co
license:
name: BSD-2-Clause (Pipecat framework)
url: https://github.com/pipecat-ai/pipecat/blob/main/LICENSE
version: '1.0'
servers:
- url: https://api.pipecat.daily.co/v1
description: Pipecat Cloud REST control API
security:
- bearerAuth: []
tags:
- name: Agents
description: Create, list, update, and delete deployed agents and inspect logs and sessions.
- name: Sessions
description: Start, stop, and proxy requests to running agent sessions.
- name: Builds
description: Build container images for agent deployments.
- name: Secrets
description: Manage secret sets and individual secrets used by agents.
- name: Organization
description: Organization properties and available regions.
paths:
/agents:
get:
operationId: listAgents
tags:
- Agents
summary: List all agents in the organization.
responses:
'200':
description: A list of agents.
post:
operationId: createAgent
tags:
- Agents
summary: Create a new agent from a container image and configuration.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentCreateRequest'
responses:
'201':
description: Agent created.
/agents/{id}:
get:
operationId: getAgent
tags:
- Agents
summary: Get details for a single agent.
parameters:
- $ref: '#/components/parameters/AgentId'
responses:
'200':
description: Agent details.
patch:
operationId: updateAgent
tags:
- Agents
summary: Update an existing agent's configuration.
parameters:
- $ref: '#/components/parameters/AgentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentCreateRequest'
responses:
'200':
description: Agent updated.
delete:
operationId: deleteAgent
tags:
- Agents
summary: Delete an agent.
parameters:
- $ref: '#/components/parameters/AgentId'
responses:
'204':
description: Agent deleted.
/agents/{id}/logs:
get:
operationId: getAgentLogs
tags:
- Agents
summary: Retrieve logs for an agent.
parameters:
- $ref: '#/components/parameters/AgentId'
responses:
'200':
description: Agent logs.
/agents/{id}/sessions:
get:
operationId: listAgentSessions
tags:
- Agents
summary: List sessions for an agent.
parameters:
- $ref: '#/components/parameters/AgentId'
responses:
'200':
description: A list of sessions.
/agents/{id}/sessions/{session_id}:
get:
operationId: getAgentSession
tags:
- Agents
summary: Get details for a specific agent session.
parameters:
- $ref: '#/components/parameters/AgentId'
- name: session_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Session details.
/sessions/start:
post:
operationId: startSession
tags:
- Sessions
summary: Start an agent session on demand.
description: >-
Starts a new session for a deployed agent. The public per-agent form
of this operation is also exposed as
POST /public/{agentName}/start.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SessionStartRequest'
responses:
'200':
description: Session started.
/sessions/stop:
post:
operationId: stopSession
tags:
- Sessions
summary: Stop a running agent session.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SessionStopRequest'
responses:
'200':
description: Session stopped.
/sessions/{id}/proxy:
post:
operationId: proxySession
tags:
- Sessions
summary: Proxy an HTTP request to a running session (Session API).
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Proxied response from the running session.
/builds:
get:
operationId: listBuilds
tags:
- Builds
summary: List builds.
responses:
'200':
description: A list of builds.
post:
operationId: createBuild
tags:
- Builds
summary: Create a new build.
responses:
'201':
description: Build created.
/builds/{id}:
get:
operationId: getBuild
tags:
- Builds
summary: Get build status.
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Build status.
/builds/{id}/logs:
get:
operationId: getBuildLogs
tags:
- Builds
summary: Get build logs.
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Build logs.
/builds/upload-url:
get:
operationId: getBuildUploadUrl
tags:
- Builds
summary: Get a pre-signed URL for uploading build context.
responses:
'200':
description: Pre-signed upload URL.
/secrets:
get:
operationId: listSecrets
tags:
- Secrets
summary: List secret sets.
responses:
'200':
description: A list of secret sets.
post:
operationId: createSecret
tags:
- Secrets
summary: Create or update a secret set.
responses:
'200':
description: Secret set created or updated.
/secrets/{name}:
get:
operationId: getSecret
tags:
- Secrets
summary: Get details for a secret set.
parameters:
- $ref: '#/components/parameters/SecretName'
responses:
'200':
description: Secret set details.
delete:
operationId: deleteSecret
tags:
- Secrets
summary: Delete an entire secret set.
parameters:
- $ref: '#/components/parameters/SecretName'
responses:
'204':
description: Secret set deleted.
/secrets/{name}/{key}:
delete:
operationId: deleteSecretKey
tags:
- Secrets
summary: Delete a specific secret from a set.
parameters:
- $ref: '#/components/parameters/SecretName'
- name: key
in: path
required: true
schema:
type: string
responses:
'204':
description: Secret deleted.
/properties:
get:
operationId: getProperties
tags:
- Organization
summary: Get organization properties.
responses:
'200':
description: Organization properties.
patch:
operationId: updateProperties
tags:
- Organization
summary: Update organization properties.
responses:
'200':
description: Organization properties updated.
/regions:
get:
operationId: listRegions
tags:
- Organization
summary: List available regions.
responses:
'200':
description: A list of regions.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Private API key from the Pipecat Cloud dashboard, sent as a Bearer token.
parameters:
AgentId:
name: id
in: path
required: true
schema:
type: string
SecretName:
name: name
in: path
required: true
schema:
type: string
schemas:
AgentCreateRequest:
type: object
properties:
name:
type: string
description: Agent name.
image:
type: string
description: Container image reference for the agent.
secretSet:
type: string
description: Name of the secret set to attach.
profile:
type: string
description: Compute profile (e.g., agent-1x, agent-2x, agent-3x).
SessionStartRequest:
type: object
properties:
agentName:
type: string
description: Name of the deployed agent to start.
body:
type: object
description: Arbitrary JSON payload passed to the agent at session start.
SessionStopRequest:
type: object
properties:
sessionId:
type: string
description: Identifier of the running session to stop.