{ "openapi": "3.0.0", "info": { "title": "Pipecat Cloud", "version": "1.0.0", "description": "REST API for Pipecat Cloud. The public API (`/v1/public`, authenticated with a public API key) starts agent sessions and proxies requests to them. The private API (`/v1`, authenticated with a private API key) manages agents, secrets, builds, regions, and organization settings." }, "servers": [ { "url": "https://api.pipecat.daily.co/v1", "description": "Private API server" } ], "paths": { "/agents": { "post": { "summary": "Create a new agent", "operationId": "createService", "security": [ { "PrivateKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateServiceRequest" }, "example": { "serviceName": "voice-starter", "image": "your-dockername/voice-starter:0.1", "region": "us-west", "nodeType": "arm", "imagePullSecretSet": "dockerhub-credentials", "secretSet": "voice-starter-secrets", "autoScaling": { "minAgents": 1, "maxAgents": 20 }, "krispViva": { "audioFilter": "tel" }, "agentProfile": "agent-1x", "maxSessionDuration": 3600 } } } }, "responses": { "200": { "description": "Agent created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceDetailsResponse" }, "example": { "name": "voice-starter", "region": "us-west", "ready": false, "available": false, "createdAt": "2025-04-19T01:20:27.564Z", "updatedAt": "2025-04-19T01:20:27.572Z", "desiredDeploymentId": "13c0be89-5ae8-4b0b-ad22-79565e11de3b", "activeDeploymentId": "13c0be89-5ae8-4b0b-ad22-79565e11de3b", "reconciledDeploymentId": null, "activeDeploymentReady": false, "autoScaling": { "maxReplicas": 20, "minReplicas": 1 }, "activeSessionCount": 0, "deployment": { "id": "13c0be89-5ae8-4b0b-ad22-79565e11de3b", "manifest": { "apiVersion": "pipecatcloud.daily.co/v1", "kind": "PCService", "metadata": { "name": "voice-starter", "namespace": "tiny-ferret-maroon-123" }, "spec": { "dailyNodeType": "arm", "image": "your-dockername/voice-starter:0.1", "autoScaling": { "minReplicas": 1, "maxReplicas": 20 }, "imagePullSecretName": "dockerhub-credentials", "envFromSecretNames": ["voice-starter-secrets"], "resources": { "cpu": "500m", "memory": "1Gi" }, "krispModels": { "enabled": false }, "krispViva": { "audioFilters": true }, "maxSessionDurationSeconds": 3600 } }, "serviceId": "b59a68ee-61c8-4d99-9ceb-e99a3953bdac", "createdAt": "2025-04-19T01:20:27.569Z", "updatedAt": "2025-04-19T01:20:27.569Z" }, "agentProfile": "agent-1x", "krispViva": { "audioFilter": "tel" } } } } }, "400": { "description": "Invalid request or agent already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "serviceExists": { "summary": "Service already exists", "value": { "error": "Service already exists", "code": "GENERIC_BAD_REQUEST" } }, "secretRegionMismatch": { "summary": "Secret set region mismatch", "value": { "error": "Secret set 'my-secrets' is in region 'us-east' but service will be created in region 'us-west'. Secrets must be in the same region as the service.", "code": "GENERIC_BAD_REQUEST" } }, "imagePullSecretRegionMismatch": { "summary": "Image pull secret region mismatch", "value": { "error": "Image pull secret set 'dockerhub-creds' is in region 'us-east' but service will be created in region 'us-west'. Image pull secrets must be in the same region as the service.", "code": "GENERIC_BAD_REQUEST" } }, "imageOrBuildIdRequired": { "summary": "Neither image nor buildId provided", "value": { "error": "Either image or buildId is required for service creation", "code": "GENERIC_BAD_REQUEST" } }, "imageAndBuildIdConflict": { "summary": "Both image and buildId provided", "value": { "error": "Cannot specify both image and buildId. Use one or the other.", "code": "GENERIC_BAD_REQUEST" } }, "buildNotFound": { "summary": "Build not found", "value": { "error": "Build not found", "code": "GENERIC_BAD_REQUEST" } }, "buildRegionMismatch": { "summary": "Build region mismatch", "value": { "error": "Build is in region 'eu-central' but service is in region 'us-west'. Builds must be in the same region as the service.", "code": "GENERIC_BAD_REQUEST" } }, "buildNotReady": { "summary": "Build not successful", "value": { "error": "Build is not ready (status: building). Only successful builds can be deployed.", "code": "GENERIC_BAD_REQUEST" } } } } } }, "404": { "description": "Secret set or image pull secret set not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Secret set not found", "code": "NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Internal server error", "code": "INTERNAL_SERVER_ERROR" } } } } } }, "get": { "summary": "List all agents", "operationId": "listServices", "security": [ { "PrivateKeyAuth": [] } ], "parameters": [ { "name": "includeActiveDeployment", "in": "query", "required": false, "description": "Whether to include the active deployment details in the response", "schema": { "type": "boolean" } }, { "name": "region", "in": "query", "required": false, "description": "Filter agents by region. If not specified, returns agents from all regions.", "schema": { "type": "string", "example": "us-west" } } ], "responses": { "200": { "description": "List of agents retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "services": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceListItem" } } } }, "example": { "services": [ { "id": "c359e1ea-64d6-4bcf-a7c6-28d3bd1c8909", "name": "voice-starter", "region": "us-west", "desiredDeploymentId": "4cab03c7-8f53-418d-9c3c-91a1265d179e", "activeDeploymentId": "4cab03c7-8f53-418d-9c3c-91a1265d179e", "reconciledDeploymentId": "4cab03c7-8f53-418d-9c3c-91a1265d179e", "organizationId": "7c489df3-7d1d-482f-b1ed-51300f630645", "createdAt": "2025-04-09T15:01:17.414Z", "updatedAt": "2025-04-18T20:29:19.181Z", "deletedAt": null }, { "id": "4e0d1f30-77a8-4283-a054-14a63b06720f", "name": "voice-starter-krisp", "region": "us-west", "desiredDeploymentId": "62e89096-23c6-4265-984b-f419696c58da", "activeDeploymentId": "62e89096-23c6-4265-984b-f419696c58da", "reconciledDeploymentId": "62e89096-23c6-4265-984b-f419696c58da", "organizationId": "7c489df3-7d1d-482f-b1ed-51300f630645", "createdAt": "2025-04-09T15:59:50.465Z", "updatedAt": "2025-04-11T16:54:54.246Z", "deletedAt": null } ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agents/{agentName}": { "delete": { "summary": "Delete an agent", "description": "Permanently removes an agent and its associated Kubernetes resources.", "operationId": "deleteService", "security": [ { "PrivateKeyAuth": [] } ], "parameters": [ { "name": "agentName", "in": "path", "required": true, "description": "Name of the agent to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["OK"], "description": "Status of the deletion operation" } } }, "example": { "status": "OK" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Not found", "code": "NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Internal server error", "code": "INTERNAL_SERVER_ERROR" } } } } } }, "post": { "summary": "Update an agent deployment", "operationId": "updateService", "security": [ { "PrivateKeyAuth": [] } ], "parameters": [ { "name": "agentName", "in": "path", "required": true, "description": "Name of the agent to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateServiceRequest" }, "example": { "image": "your-dockername/voice-starter:0.1", "nodeType": "arm", "imagePullSecretSet": "dockerhub-credentials", "secretSet": "voice-starter-secrets", "autoScaling": { "minAgents": 1, "maxAgents": 10 }, "krispViva": { "audioFilter": "tel" }, "agentProfile": "agent-1x", "maxSessionDuration": 3600 } } } }, "responses": { "200": { "description": "Agent deployment updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceDetailsResponse" }, "example": { "name": "voice-starter", "region": "us-west", "ready": true, "available": true, "createdAt": "2025-04-19T01:20:27.564Z", "updatedAt": "2025-04-19T01:25:47.229Z", "desiredDeploymentId": "19db578d-808c-420a-a047-87edde4410c1", "activeDeploymentId": "19db578d-808c-420a-a047-87edde4410c1", "reconciledDeploymentId": "19db578d-808c-420a-a047-87edde4410c1", "activeDeploymentReady": true, "autoScaling": { "maxReplicas": 10, "minReplicas": 1 }, "activeSessionCount": 0, "deployment": { "id": "19db578d-808c-420a-a047-87edde4410c1", "manifest": { "apiVersion": "pipecatcloud.daily.co/v1", "kind": "PCService", "metadata": { "name": "voice-starter", "namespace": "tiny-ferret-maroon-123" }, "spec": { "dailyNodeType": "arm", "image": "your-dockername/voice-starter:0.1", "autoScaling": { "minReplicas": 1, "maxReplicas": 10 }, "imagePullSecretName": "dockerhub-credentials", "envFromSecretNames": ["voice-starter-secrets"], "resources": { "cpu": "500m", "memory": "1Gi" }, "krispModels": { "enabled": false }, "krispViva": { "audioFilters": true }, "maxSessionDurationSeconds": 3600 } }, "serviceId": "b59a68ee-61c8-4d99-9ceb-e99a3953bdac", "createdAt": "2025-04-19T01:25:47.225Z", "updatedAt": "2025-04-19T01:25:47.225Z" }, "agentProfile": "agent-1x", "krispViva": { "audioFilter": "tel" }, "currentRevision": { "deploymentID": "19db578d-808c-420a-a047-87edde4410c1", "phase": "Active", "readyReplicas": 1, "phaseStartedAt": "2025-04-19T01:26:00.000Z", "health": { "ready": true, "state": "running", "restartCount": 0, "replicasStarted": 1 } }, "previousRevision": null } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidParameters": { "summary": "Invalid parameters", "value": { "error": "Invalid parameters", "code": "GENERIC_BAD_REQUEST" } }, "secretRegionMismatch": { "summary": "Secret set region mismatch", "value": { "error": "Secret set 'my-secrets' is in region 'us-east' but service is in region 'us-west'. Secrets must be in the same region as the service.", "code": "GENERIC_BAD_REQUEST" } }, "imagePullSecretRegionMismatch": { "summary": "Image pull secret region mismatch", "value": { "error": "Image pull secret set 'dockerhub-creds' is in region 'us-east' but service is in region 'us-west'. Image pull secrets must be in the same region as the service.", "code": "GENERIC_BAD_REQUEST" } }, "imageAndBuildIdConflict": { "summary": "Both image and buildId provided", "value": { "error": "Cannot specify both image and buildId. Use one or the other.", "code": "GENERIC_BAD_REQUEST" } }, "buildNotFound": { "summary": "Build not found", "value": { "error": "Build not found", "code": "GENERIC_BAD_REQUEST" } }, "buildRegionMismatch": { "summary": "Build region mismatch", "value": { "error": "Build is in region 'eu-central' but service is in region 'us-west'. Builds must be in the same region as the service.", "code": "GENERIC_BAD_REQUEST" } }, "buildNotReady": { "summary": "Build not successful", "value": { "error": "Build is not ready (status: building). Only successful builds can be deployed.", "code": "GENERIC_BAD_REQUEST" } } } } } }, "404": { "description": "Agent or referenced secret not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Service not found", "code": "NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Internal server error", "code": "INTERNAL_SERVER_ERROR" } } } } } }, "get": { "summary": "Get agent details", "operationId": "getService", "security": [ { "PrivateKeyAuth": [] } ], "parameters": [ { "name": "agentName", "in": "path", "required": true, "description": "Name of the agent to retrieve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceDetailsResponse" }, "example": { "name": "voice-starter", "region": "us-west", "ready": true, "available": true, "createdAt": "2025-04-19T01:20:27.564Z", "updatedAt": "2025-04-19T01:25:47.229Z", "desiredDeploymentId": "19db578d-808c-420a-a047-87edde4410c1", "activeDeploymentId": "19db578d-808c-420a-a047-87edde4410c1", "reconciledDeploymentId": "19db578d-808c-420a-a047-87edde4410c1", "activeDeploymentReady": true, "autoScaling": { "maxReplicas": 10, "minReplicas": 1 }, "activeSessionCount": 0, "agentProfile": "agent-1x", "deployment": { "id": "19db578d-808c-420a-a047-87edde4410c1", "manifest": { "apiVersion": "pipecatcloud.daily.co/v1", "kind": "PCService", "metadata": { "name": "voice-starter", "namespace": "tiny-ferret-maroon-123" }, "spec": { "dailyNodeType": "arm", "image": "your-dockername/voice-starter:0.1", "autoScaling": { "minReplicas": 1, "maxReplicas": 10 }, "imagePullSecretName": "dockerhub-credentials", "envFromSecretNames": ["voice-starter-secrets"], "resources": { "cpu": "500m", "memory": "1Gi" }, "krispModels": { "enabled": false }, "krispViva": { "audioFilters": true }, "maxSessionDurationSeconds": 3600 } }, "serviceId": "b59a68ee-61c8-4d99-9ceb-e99a3953bdac", "createdAt": "2025-04-19T01:25:47.225Z", "updatedAt": "2025-04-19T01:25:47.225Z" }, "krispViva": { "audioFilter": "tel" }, "currentRevision": { "deploymentID": "19db578d-808c-420a-a047-87edde4410c1", "phase": "Active", "readyReplicas": 1, "phaseStartedAt": "2025-04-19T01:26:00.000Z", "health": { "ready": true, "state": "running", "restartCount": 0, "replicasStarted": 1 } }, "previousRevision": null } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Not found", "code": "NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Internal server error", "code": "INTERNAL_SERVER_ERROR" } } } } } } }, "/agents/{agentName}/logs": { "get": { "summary": "Get agent logs", "description": "Retrieves logs for the specified agent with optional filtering and pagination.", "operationId": "getLogs", "security": [ { "PrivateKeyAuth": [] } ], "parameters": [ { "name": "agentName", "in": "path", "required": true, "description": "Name of the agent to retrieve logs for", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of log entries to return", "schema": { "type": "integer", "default": 10 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of log entries to skip", "schema": { "type": "integer", "default": 0 } }, { "name": "deploymentId", "in": "query", "required": false, "description": "Filter logs to a specific deployment ID", "schema": { "type": "string" } }, { "name": "sessionId", "in": "query", "required": false, "description": "Filter logs to a specific session ID", "schema": { "type": "string" } }, { "name": "query", "in": "query", "required": false, "description": "Free-text search query to filter logs", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "Sort order for logs", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" } }, { "name": "startTime", "in": "query", "required": false, "description": "Filter logs to those after this Unix timestamp", "schema": { "type": "integer" } }, { "name": "endTime", "in": "query", "required": false, "description": "Filter logs to those before this Unix timestamp", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Agent logs retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "object", "properties": { "value": { "type": "integer", "description": "Total number of log entries matching the query" }, "relation": { "type": "string", "enum": ["eq", "gte"], "description": "Relation type for the total count (eq = exact, gte = greater than or equal)" } } }, "logs": { "type": "array", "description": "List of log entries", "items": { "type": "object", "properties": { "log": { "type": "string", "description": "Log message content" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp when the log was generated" }, "deploymentId": { "type": "string", "description": "ID of the deployment that generated the log", "nullable": true } } } } } }, "example": { "total": { "value": 79, "relation": "eq" }, "logs": [ { "log": "INFO: Finished server process [1]", "timestamp": "2025-04-18T20:34:17.153744602Z" }, { "log": "INFO: Application shutdown complete.", "timestamp": "2025-04-18T20:34:17.153706059Z" }, { "log": "INFO: Waiting for application shutdown.", "timestamp": "2025-04-18T20:34:17.153611029Z" }, { "log": "INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)", "timestamp": "2025-04-18T20:32:42.246099974Z" }, { "log": "INFO: Application startup complete.", "timestamp": "2025-04-18T20:32:42.245760327Z" } ] } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Invalid timestamp format", "code": "GENERIC_BAD_REQUEST" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Not found", "code": "NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Internal server error", "code": "INTERNAL_SERVER_ERROR" } } } } } } }, "/agents/{agentName}/sessions/{sessionId}": { "get": { "summary": "Get session details", "description": "Retrieves detailed information about a specific session, including resource metrics and meeting IDs.", "operationId": "getSession", "security": [ { "PrivateKeyAuth": [] } ], "parameters": [ { "name": "agentName", "in": "path", "required": true, "description": "Name of the agent", "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "description": "UUID of the session to retrieve", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Session details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" }, "example": { "sessionId": "800d444a-e67e-4686-afb3-b0de509cccb3", "serviceId": "b900ae4a-f710-4ef1-95d8-c5f5b2789da9", "organizationId": "cc71b52d-4271-46c9-87be-cac600fd821a", "deploymentId": "81f4da55-106d-401f-b069-a1f1992f871a", "endedAt": "2025-10-22T08:39:26.000Z", "botStartSeconds": 2, "coldStart": true, "completionStatus": "HTTP_COMPLETED", "createdAt": "2025-10-22T08:39:20.000Z", "updatedAt": "2025-10-22T08:39:26.000Z", "resourceMetrics": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "sessionId": "800d444a-e67e-4686-afb3-b0de509cccb3", "sampleCount": 12, "cpuMillicoresP50": 150, "cpuMillicoresP90": 280, "cpuMillicoresP95": 320, "cpuMillicoresP99": 450, "memoryBytesP50": 134217728, "memoryBytesP90": 201326592, "memoryBytesP95": 234881024, "memoryBytesP99": 268435456, "timeseries": [ { "t": 1729583960, "c": 150, "m": 134217728 }, { "t": 1729583965, "c": 280, "m": 201326592 } ], "eventTs": "2025-10-22T08:39:25.000Z", "createdAt": "2025-10-22T08:39:25.000Z" }, "meetingIds": [ { "participantId": "d4e5f6a7-b8c9-0123-4567-890abcdef012", "meetingId": "f1e2d3c4-b5a6-9780-1234-567890abcdef" } ] } } } }, "404": { "description": "Agent or session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "API endpoint not found / agent deployment not found / Organization not found", "code": "404" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Internal server error. Please check logs for more information or contact support.", "code": "500" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "delete": { "summary": "Stop an agent session", "operationId": "stopSession", "description": "Stops an active session of a deployed agent and cleans up its resources.", "security": [ { "PrivateKeyAuth": [] } ], "parameters": [ { "name": "agentName", "in": "path", "required": true, "description": "Name of the agent", "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "description": "UUID of the session to stop", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Session stopped successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StopResponse" } } } }, "400": { "description": "Invalid request (e.g., invalid session ID format)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Service or session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/agents/{agentName}/sessions": { "get": { "summary": "Get agent sessions", "description": "Retrieves sessions for the specified agent with optional filtering and pagination.", "operationId": "getSessions", "security": [ { "PrivateKeyAuth": [] } ], "parameters": [ { "name": "agentName", "in": "path", "required": true, "description": "Name of the agent to retrieve sessions for", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of sessions to return", "schema": { "type": "integer", "default": 10 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of sessions to skip", "schema": { "type": "integer", "default": 0 } }, { "name": "deploymentId", "in": "query", "required": false, "description": "Filter sessions to a specific deployment ID", "schema": { "type": "string" } }, { "name": "startTime", "in": "query", "required": false, "description": "Filter sessions to those after this Unix timestamp", "schema": { "type": "integer" } }, { "name": "endTime", "in": "query", "required": false, "description": "Filter sessions to those before this Unix timestamp", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "description": "Filter sessions to those with this status", "schema": { "type": "string", "enum": ["active", "ended", "all"], "default": "all" } }, { "name": "startType", "in": "query", "required": false, "description": "Filter sessions to those with this start type", "schema": { "type": "string", "enum": ["cold", "warm", "all"], "default": "all" } }, { "name": "startTimeMin", "in": "query", "required": false, "description": "Filter sessions to those whose start times are greater than this value in seconds", "schema": { "type": "integer", "default": 0 } }, { "name": "startTimeMax", "in": "query", "required": false, "description": "Filter sessions to those whose start times are less than this value in seconds", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Agent sessions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Total number of sessions matching the parameters" }, "sessions": { "type": "array", "description": "List of sessions", "items": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "ID of the session" }, "serviceId": { "type": "string", "description": "ID of the service for this session" }, "organizationId": { "type": "string", "description": "ID of the organization that this session is associated with" }, "deploymentId": { "type": "string", "description": "ID of the deployment that this session is associated with" }, "endedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the log was generated" }, "botStartSeconds": { "type": "integer", "description": "Number of seconds between bot start request and bot start", "nullable": true }, "coldStart": { "type": "boolean", "description": "Whether the bot start was a [cold start](/pipecat-cloud/fundamentals/scaling#cold-starts)", "nullable": true }, "completionStatus": { "type": "string", "description": "The completion status of the session. This can be an http return code or a string like `HTTP_COMPLETED`, `HTTP_ERROR`, `WS_CONNECTION_CLOSED`, among others", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the session was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the session was last updated" } } } } } }, "example": { "total_count": 330, "sessions": [ { "sessionId": "800d444a-e67e-4686-afb3-b0de509cccb3", "serviceId": "b900ae4a-f710-4ef1-95d8-c5f5b2789da9", "organizationId": "cc71b52d-4271-46c9-87be-cac600fd821a", "deploymentId": "81f4da55-106d-401f-b069-a1f1992f871a", "endedAt": "2025-10-22T08:39:26.000Z", "botStartSeconds": 0, "coldStart": false, "completionStatus": "HTTP_COMPLETED", "createdAt": "2025-10-22T08:39:26.000Z", "updatedAt": "2025-10-22T08:39:26.000Z" }, { "sessionId": "803349cc-2ae0-437a-9a72-408817299e43", "serviceId": "b900ae4a-f710-4ef1-95d8-c5f5b2789da9", "organizationId": "cc71b52d-4271-46c9-87be-cac600fd821a", "deploymentId": "81f4da55-106d-401f-b069-a1f1992f871a", "endedAt": "2025-10-22T08:38:09.000Z", "botStartSeconds": 2, "coldStart": true, "completionStatus": "HTTP_COMPLETED", "createdAt": "2025-10-22T08:38:09.000Z", "updatedAt": "2025-10-22T08:38:09.000Z" }, { "sessionId": "44003e83-b679-46ef-88ec-18e9ea9dd81d", "serviceId": "b900ae4a-f710-4ef1-95d8-c5f5b2789da9", "organizationId": "cc71b52d-4271-46c9-87be-cac600fd821a", "deploymentId": "f76bae42-5ce8-4ae3-8a75-0349bfd7ec63", "endedAt": "2025-10-21T08:17:47.000Z", "botStartSeconds": 0, "coldStart": false, "completionStatus": "HTTP_ERROR", "createdAt": "2025-10-21T08:17:22.000Z", "updatedAt": "2025-10-21T08:17:38.000Z" } ] } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Invalid parameters", "err": { "issues": [ { "received": "bad_value", "code": "invalid_enum_value", "options": ["active", "ended", "all"], "path": ["status"], "message": "Invalid enum value. Expected 'active' | 'ended' | 'all', received 'bad_value'" } ], "name": "ZodError" }, "code": "400" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "API endpoint not found / agent deployment not found / Organization not found", "code": "404" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Internal server error. Please check logs for more information or contact support.", "code": "500" } } } } } } }, "/builds": { "post": { "summary": "Create a build", "description": "Create a new build from an uploaded context. If a successful build already exists with the same context hash, region, and Dockerfile path, the cached build is returned instead of triggering a new build.", "operationId": "createBuild", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBuildRequest" } } } }, "responses": { "200": { "description": "Cached build found - no new build triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBuildResponse" } } } }, "201": { "description": "New build created and triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBuildResponse" } } } }, "400": { "description": "Invalid request (e.g., upload not found, cloud build not enabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "summary": "List builds", "description": "List all builds for your organization with optional filters.", "operationId": "listBuilds", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "description": "Filter by build status.", "schema": { "type": "string", "enum": ["pending", "building", "success", "failed", "timeout"] } }, { "name": "region", "in": "query", "description": "Filter by region.", "schema": { "type": "string" }, "example": "us-west" }, { "name": "contextHash", "in": "query", "description": "Filter by context hash.", "schema": { "type": "string" }, "example": "a1b2c3d4e5f6a7b8" }, { "name": "limit", "in": "query", "description": "Maximum number of builds to return.", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of builds to skip for pagination.", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "responses": { "200": { "description": "List of builds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBuildsResponse" } } } } } } }, "/builds/{buildId}": { "get": { "summary": "Get build status", "description": "Get the current status of a build. For builds in progress, this endpoint automatically reconciles the status with the underlying build system to provide the latest information.", "operationId": "getBuild", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "buildId", "in": "path", "required": true, "description": "Unique identifier of the build.", "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "responses": { "200": { "description": "Build details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBuildResponse" } } } }, "400": { "description": "Invalid build ID format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Build not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/builds/{buildId}/logs": { "get": { "summary": "Get build logs", "description": "Retrieve the logs for a specific build. Returns log lines from the build process, useful for monitoring progress or debugging failures.", "operationId": "getBuildLogs", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "buildId", "in": "path", "required": true, "description": "Unique identifier of the build.", "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of log events to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 500 }, "example": 500 } ], "responses": { "200": { "description": "Build logs retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBuildLogsResponse" } } } }, "400": { "description": "Invalid build ID format or invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Build not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/builds/upload-url": { "post": { "summary": "Get upload URL for build context", "description": "Generate a pre-signed URL for uploading your Docker build context (tar.gz archive) to Pipecat Cloud storage. The returned URL expires after 15 minutes.", "operationId": "getBuildUploadUrl", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrlRequest" } } } }, "responses": { "200": { "description": "Upload URL generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrlResponse" } } } }, "400": { "description": "Invalid request (e.g., cloud build not enabled for region)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/properties": { "get": { "summary": "Get organization properties", "description": "Retrieve the current values of all configurable properties for your organization. Returns only public (user-configurable) properties without schema metadata. For schema information including available values and constraints, use the `/properties/schema` endpoint.", "operationId": "getProperties", "security": [ { "PrivateKeyAuth": [] } ], "responses": { "200": { "description": "Properties retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "properties": { "$ref": "#/components/schemas/OrganizationProperties" } } }, "example": { "properties": { "defaultRegion": "us-west" } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Unauthorized", "code": "UNAUTHORIZED" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Internal server error", "code": "INTERNAL_SERVER_ERROR" } } } } } }, "patch": { "summary": "Update organization properties", "description": "Update one or more configurable properties for your organization. Only public (user-configurable) properties can be modified via this endpoint. Properties are validated against their schema and constraints before being applied. Returns the complete property schema including metadata for all properties.", "operationId": "updateProperties", "security": [ { "PrivateKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "defaultRegion": { "type": "string", "description": "Default region for new service deployments. Must be one of the [available regions](/pipecat-cloud/rest-reference/endpoint/regions-list) for your organization.", "example": "us-west" } }, "additionalProperties": false }, "examples": { "updateDefaultRegion": { "summary": "Update default region", "value": { "defaultRegion": "eu-central" } } } } } }, "responses": { "200": { "description": "Properties successfully updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "properties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PropertySchema" } } } }, "example": { "properties": { "defaultRegion": { "description": "Default region for new service deployments", "type": "string", "readOnly": false, "currentValue": "eu-central", "default": "us-west", "availableValues": [ "us-west", "us-east", "eu-central", "ap-south" ] } } } } } }, "400": { "description": "Bad request - Invalid property name, value, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidProperty": { "summary": "Invalid property name", "value": { "error": "Property 'invalidProp' is not a valid property", "code": "GENERIC_BAD_REQUEST" } }, "invalidRegion": { "summary": "Invalid region value", "value": { "error": "Region 'invalid-region' is not available. Available regions: us-west, us-east, eu-central", "code": "GENERIC_BAD_REQUEST" } }, "emptyUpdate": { "summary": "No properties provided", "value": { "error": "No properties provided", "code": "GENERIC_BAD_REQUEST" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Unauthorized", "code": "UNAUTHORIZED" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Internal server error", "code": "INTERNAL_SERVER_ERROR" } } } } } } }, "/properties/schema": { "get": { "summary": "Get organization properties schema", "description": "Retrieve metadata about all configurable properties for your organization, including type information, constraints, current values, default values, and dynamically available values (e.g., available regions).", "operationId": "getPropertiesSchema", "security": [ { "PrivateKeyAuth": [] } ], "responses": { "200": { "description": "Properties schema retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "properties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PropertySchema" } } } }, "example": { "properties": { "defaultRegion": { "type": "string", "description": "Default region for new service deployments", "default": "us-west", "currentValue": "us-west", "availableValues": [ "us-west", "us-east", "eu-central", "ap-south" ] } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Unauthorized", "code": "UNAUTHORIZED" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Internal server error", "code": "INTERNAL_SERVER_ERROR" } } } } } } }, "/regions": { "get": { "summary": "List available regions", "description": "Retrieve a list of all regions available for deploying agents and storing secrets. This endpoint can be accessed using either Clerk authentication or a Private API key.", "operationId": "listRegions", "security": [ { "PrivateKeyAuth": [] } ], "responses": { "200": { "description": "List of available regions", "content": { "application/json": { "schema": { "type": "object", "properties": { "regions": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } } } }, "example": { "regions": [ { "code": "us-west", "display_name": "US West (Oregon)" }, { "code": "us-east", "display_name": "US East (Virginia)" }, { "code": "eu-central", "display_name": "Europe (Frankfurt)" }, { "code": "ap-south", "display_name": "Asia Pacific (Mumbai)" } ] } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Unauthorized", "code": "UNAUTHORIZED" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Internal server error", "code": "INTERNAL_SERVER_ERROR" } } } } } } }, "/secrets/{setName}": { "put": { "summary": "Create or update a secret set", "description": "Create a new secret set or update an existing one. Supports both regular secrets (multiple key-value pairs) and image pull secrets.\n\nProvisioning is **asynchronous**: the response is `202 Accepted` once the values have been stored, and the secret set is then provisioned into the target region in the background. Use `GET /secrets/{setName}` to observe the readiness status (`pending` \u2192 `ready`). Deploys that bind a secret set whose status is not `ready` are rejected with `409 Conflict`.", "operationId": "upsertSecretSet", "security": [ { "PrivateKeyAuth": [] } ], "parameters": [ { "name": "setName", "in": "path", "required": true, "description": "Name of the secret set to create or update", "schema": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "minLength": 3, "maxLength": 63 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RegularSecretsRequest" }, { "$ref": "#/components/schemas/ImagePullSecretRequest" } ] }, "examples": { "regularSecrets": { "summary": "Regular secrets", "description": "Create or update a set with multiple key-value pairs", "value": { "secrets": [ { "secretKey": "API_KEY", "secretValue": "your-api-key" }, { "secretKey": "DATABASE_URL", "secretValue": "postgresql://user:pass@host:5432/db" } ], "region": "us-west" } }, "imagePullSecret": { "summary": "Image pull secret", "description": "Create or update an image pull secret", "value": { "isImagePullSecret": true, "host": "https://index.docker.io/v1/", "secretValue": "your-docker-auth-token", "region": "us-west" } } } } } }, "responses": { "202": { "description": "Secret set accepted. Values have been stored and the set is being provisioned into the target region in the background. Poll `GET /secrets/{setName}` until `status` is `ready` before binding it to a deploy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["OK"] }, "region": { "type": "string", "description": "The region where the secret set was created or exists" } }, "required": ["status", "region"] }, "example": { "status": "OK", "region": "us-west" } } } }, "400": { "description": "Bad request - Invalid parameters or operation not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidImagePullSecretUpdate": { "summary": "Invalid image pull secret update", "value": { "error": "Must provide isImagePullSecret, host, and secretValue to update an image pull secret", "code": "GENERIC_BAD_REQUEST" } }, "cannotChangeSecretType": { "summary": "Cannot change secret type", "value": { "error": "Cannot update existing regular secrets to image pull secrets", "code": "GENERIC_BAD_REQUEST" } }, "regionMismatch": { "summary": "Region mismatch", "value": { "error": "Secret already exists in region 'us-west'. Cannot change region to 'us-east'.", "code": "GENERIC_BAD_REQUEST" } }, "invalidRegion": { "summary": "Invalid region access", "value": { "error": "Invalid region or organization does not have access", "code": "GENERIC_BAD_REQUEST" } }, "validationError": { "summary": "Validation error", "value": { "error": "Invalid request format", "code": "GENERIC_BAD_REQUEST" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Unauthorized", "code": "UNAUTHORIZED" } } } }, "409": { "description": "Conflict - Another request is modifying this secret set concurrently. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Secret set 'my-secrets' was modified concurrently. Please retry.", "code": "CONFLICT" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "summary": "Delete an entire secret set", "description": "Permanently removes a secret set and all its associated secrets.", "operationId": "deleteSecretSet", "security": [ { "PrivateKeyAuth": [] } ], "parameters": [ { "name": "setName", "in": "path", "required": true, "description": "Name of the secret set to delete", "schema": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "minLength": 3, "maxLength": 63 } } ], "responses": { "200": { "description": "Secret set successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["OK"] } } }, "example": { "status": "OK" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Unauthorized", "code": "UNAUTHORIZED" } } } }, "404": { "description": "Secret set not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Set not found", "code": "NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "summary": "Get a specific secret set", "description": "Retrieve the keys (not values) of a specific secret set. Image pull secrets cannot be retrieved.", "operationId": "getSecretSet", "security": [ { "PrivateKeyAuth": [] } ], "parameters": [ { "name": "setName", "in": "path", "required": true, "description": "Name of the secret set to retrieve", "schema": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "minLength": 3, "maxLength": 63 } } ], "responses": { "200": { "description": "Secret set details, including readiness status", "content": { "application/json": { "schema": { "type": "object", "properties": { "region": { "type": "string", "description": "The region where the secret set is stored" }, "status": { "type": "string", "enum": ["pending", "ready", "failed"], "description": "Readiness state. `pending` while provisioning is in flight, `ready` once the set can be bound to a deploy, `failed` if provisioning could not complete." }, "errorMessage": { "type": "string", "description": "Customer-facing message returned only when `status` is `failed`. Generic by design \u2014 internal diagnostic details are kept in platform logs." }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretKey" } } } }, "example": { "region": "us-west", "status": "ready", "secrets": [ { "fieldName": "API_KEY" }, { "fieldName": "DATABASE_URL" }, { "fieldName": "JWT_SECRET" } ] } } } }, "400": { "description": "Bad request - Cannot retrieve image pull secrets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Cannot retrieve image pull secrets by name", "code": "GENERIC_BAD_REQUEST" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Unauthorized", "code": "UNAUTHORIZED" } } } }, "404": { "description": "Secret set not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Set not found", "code": "NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/secrets/{setName}/{secretKey}": { "delete": { "summary": "Delete a specific secret from a set", "description": "Remove a specific secret key from a secret set. Cannot be used with image pull secrets.", "operationId": "deleteSecretFromSet", "security": [ { "PrivateKeyAuth": [] } ], "parameters": [ { "name": "setName", "in": "path", "required": true, "description": "Name of the secret set", "schema": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "minLength": 3, "maxLength": 63 } }, { "name": "secretKey", "in": "path", "required": true, "description": "Name of the secret key to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Secret successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["OK"] } } }, "example": { "status": "OK" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Unauthorized", "code": "UNAUTHORIZED" } } } }, "404": { "description": "Secret not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Secret not found", "code": "NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/secrets": { "get": { "summary": "List all secret sets", "description": "Retrieve a list of all secret sets for the organization.", "operationId": "listSecretSets", "security": [ { "PrivateKeyAuth": [] } ], "responses": { "200": { "description": "List of secret sets", "content": { "application/json": { "schema": { "type": "object", "properties": { "sets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretSetSummary" } } } }, "example": { "sets": [ { "name": "my-app-secrets", "type": "secret", "region": "us-west", "status": "ready" }, { "name": "dockerhub-credentials", "type": "imagePullSecret", "region": "us-west", "status": "pending" } ] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Unauthorized", "code": "UNAUTHORIZED" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/{serviceName}/sessions/{sessionId}/{path}": { "get": { "summary": "Send GET request to session", "operationId": "sessionProxyGet", "description": "Proxies a GET request to an endpoint defined in your running bot. The response is returned directly from the bot.", "security": [ { "PublicKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ServiceName" }, { "$ref": "#/components/parameters/SessionId" }, { "$ref": "#/components/parameters/Path" } ], "responses": { "200": { "description": "Successful response from the bot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxiedResponse" } } } }, "400": { "$ref": "#/components/responses/ServiceNotAvailable" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "summary": "Send POST request to session", "operationId": "sessionProxyPost", "description": "Proxies a POST request to an endpoint defined in your running bot. The request body and response are passed through directly.", "security": [ { "PublicKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ServiceName" }, { "$ref": "#/components/parameters/SessionId" }, { "$ref": "#/components/parameters/Path" } ], "requestBody": { "description": "Request body to pass to the bot endpoint", "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "Arbitrary JSON data to send to your bot endpoint", "example": { "user_name": "Alice", "preferences": { "language": "Spanish" } } } } } }, "responses": { "200": { "description": "Successful response from the bot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxiedResponse" } } } }, "400": { "$ref": "#/components/responses/ServiceNotAvailable" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "summary": "Send PUT request to session", "operationId": "sessionProxyPut", "description": "Proxies a PUT request to an endpoint defined in your running bot.", "security": [ { "PublicKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ServiceName" }, { "$ref": "#/components/parameters/SessionId" }, { "$ref": "#/components/parameters/Path" } ], "requestBody": { "description": "Request body to pass to the bot endpoint", "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "Arbitrary JSON data to send to your bot endpoint" } } } }, "responses": { "200": { "description": "Successful response from the bot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxiedResponse" } } } }, "400": { "$ref": "#/components/responses/ServiceNotAvailable" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "summary": "Send PATCH request to session", "operationId": "sessionProxyPatch", "description": "Proxies a PATCH request to an endpoint defined in your running bot.", "security": [ { "PublicKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ServiceName" }, { "$ref": "#/components/parameters/SessionId" }, { "$ref": "#/components/parameters/Path" } ], "requestBody": { "description": "Request body to pass to the bot endpoint", "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "Arbitrary JSON data to send to your bot endpoint" } } } }, "responses": { "200": { "description": "Successful response from the bot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxiedResponse" } } } }, "400": { "$ref": "#/components/responses/ServiceNotAvailable" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "summary": "Send DELETE request to session", "operationId": "sessionProxyDelete", "description": "Proxies a DELETE request to an endpoint defined in your running bot.", "security": [ { "PublicKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ServiceName" }, { "$ref": "#/components/parameters/SessionId" }, { "$ref": "#/components/parameters/Path" } ], "responses": { "200": { "description": "Successful response from the bot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxiedResponse" } } } }, "400": { "$ref": "#/components/responses/ServiceNotAvailable" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "options": { "summary": "Send OPTIONS request to session", "operationId": "sessionProxyOptions", "description": "Proxies an OPTIONS request to an endpoint defined in your running bot.", "security": [ { "PublicKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ServiceName" }, { "$ref": "#/components/parameters/SessionId" }, { "$ref": "#/components/parameters/Path" } ], "responses": { "200": { "description": "Successful response from the bot" }, "400": { "$ref": "#/components/responses/ServiceNotAvailable" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "head": { "summary": "Send HEAD request to session", "operationId": "sessionProxyHead", "description": "Proxies a HEAD request to an endpoint defined in your running bot.", "security": [ { "PublicKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ServiceName" }, { "$ref": "#/components/parameters/SessionId" }, { "$ref": "#/components/parameters/Path" } ], "responses": { "200": { "description": "Successful response from the bot" }, "400": { "$ref": "#/components/responses/ServiceNotAvailable" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "servers": [ { "url": "https://api.pipecat.daily.co/v1/public", "description": "Public API server" } ] }, "/{agentName}/start": { "post": { "summary": "Start a service instance", "operationId": "startService", "security": [ { "PublicKeyAuth": [] } ], "parameters": [ { "name": "agentName", "in": "path", "required": true, "description": "Name of the agent to start", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartRequest" } } } }, "responses": { "200": { "description": "Service started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "servers": [ { "url": "https://api.pipecat.daily.co/v1/public", "description": "Public API server" } ] } }, "components": { "securitySchemes": { "PrivateKeyAuth": { "type": "http", "scheme": "bearer", "description": "Authentication requires a Pipecat Cloud Private API token.\n\nGenerate a Private API key from your Dashboard (Settings > API Keys > Private > Create key) and include it as a Bearer token in the Authorization header." }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Authentication using a Pipecat Cloud API token." }, "PublicKeyAuth": { "type": "http", "scheme": "bearer", "description": "Authentication using a Pipecat Cloud public API key.\n\nGenerate a public API key from your Dashboard (Settings > API Keys > Public > Create key) and include it as a Bearer token in the Authorization header." } }, "schemas": { "CreateServiceRequest": { "type": "object", "required": ["serviceName"], "properties": { "serviceName": { "type": "string", "description": "Name of the agent to create.\n\nMust start with a lowercase letter or number, can include hyphens, and must end with a lowercase letter or number. No uppercase letters or special characters allowed. Maximum 54 characters.", "example": "my-voice-agent", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])$", "maxLength": 54 }, "image": { "type": "string", "description": "The container image to use for the agent. Either `image` or `buildId` must be provided, but not both.", "example": "your-username/my-agent:latest" }, "buildId": { "type": "string", "format": "uuid", "description": "The ID of a successful cloud build to deploy. Either `image` or `buildId` must be provided, but not both. The build must be in the same region as the agent.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "region": { "type": "string", "description": "The region where the agent will be deployed. If not specified, defaults to `us-west`. All secrets and image pull secrets referenced by this agent must be in the same region.", "default": "us-west", "example": "us-west" }, "nodeType": { "type": "string", "description": "The type of node to run the agent on. Only `arm` is supported at this time.", "default": "arm", "example": "arm" }, "imagePullSecretSet": { "type": "string", "description": "The name of the image pull secret set to use", "example": "dockerhub-credentials" }, "secretSet": { "type": "string", "description": "The name of the secret set to use", "example": "my-agent-secrets" }, "autoScaling": { "type": "object", "description": "Auto-scaling configuration for the agent", "properties": { "minAgents": { "type": "integer", "description": "Minimum number of agents", "example": 1 }, "maxAgents": { "type": "integer", "description": "Maximum number of agents (Default: 50)", "example": 20 } } }, "krispViva": { "type": "object", "description": "Krisp VIVA noise cancellation configuration. [Learn more](/pipecat-cloud/guides/krisp-viva).", "properties": { "audioFilter": { "type": "string", "nullable": true, "description": "The Krisp VIVA audio filter model to use:\n\n- `tel`: Optimized for telephony, cellular, landline, mobile, desktop, and browser (up to 16kHz)\n- `pro`: Optimized for mobile, desktop, and browser with WebRTC (up to 32kHz)\n- `null`: Disables Krisp VIVA\n\nBy default, Pipecat processes input audio at 16kHz, making `tel` appropriate for most use cases.", "enum": ["tel", "pro", null], "example": "tel" } } }, "agentProfile": { "type": "string", "description": "The agent profile to use for resource allocation. Valid values are:\n\n- `agent-1x`: 0.5 vCPU and 1 GB of memory. Best for voice agents.\n- `agent-2x`: 1 vCPU and 2 GB of memory. Well suited for voice and video agents or voice agents requiring extra processing.\n- `agent-3x`: 1.5 vCPU and 3 GB of memory. Best for voice and video agents requiring extra processing or multiple video inputs.", "enum": ["agent-1x", "agent-2x", "agent-3x"], "default": "agent-1x", "example": "agent-1x" }, "maxSessionDuration": { "type": "integer", "description": "Maximum session duration in seconds. When a session reaches this limit, the session is stopped: the bot is cancelled, with no opportunity for it to say goodbye first. Valid range: 60 to 14400 (4 hours). Defaults to 7200 (2 hours) when unset.", "minimum": 60, "maximum": 14400, "default": 7200, "example": 3600 } } }, "RevisionInfo": { "type": "object", "properties": { "deploymentID": { "type": "string", "description": "ID of the deployment for this revision" }, "phase": { "type": "string", "enum": ["Creating", "Validating", "Active", "Draining", "Failed"], "description": "Current phase of the revision" }, "readyReplicas": { "type": "integer", "description": "Number of ready replicas for this revision" }, "phaseStartedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the current phase started" }, "health": { "$ref": "#/components/schemas/RevisionHealth" }, "hasInfrastructureIssue": { "type": "boolean", "description": "Set to true when an internal infrastructure component is experiencing issues. If absent, infrastructure is healthy. Contact support if this flag appears." } } }, "RevisionHealth": { "type": "object", "description": "Health summary for the agent's code. Present once replicas have started running.", "properties": { "ready": { "type": "boolean", "description": "Whether the agent code is passing readiness checks" }, "state": { "type": "string", "enum": ["running", "waiting", "terminated"], "description": "Current state of the agent code" }, "restartCount": { "type": "integer", "description": "Total number of restarts across all replicas" }, "replicasStarted": { "type": "integer", "description": "Number of replicas that have been started (may or may not be ready)" }, "reason": { "type": "string", "description": "Reason for the current state (e.g., CrashLoopBackOff, ImagePullBackOff, OOMKilled, Error)" }, "lastExitCode": { "type": "integer", "description": "Exit code from the most recent crash (e.g., 1 for application error, 137 for out-of-memory)" }, "lastTerminationReason": { "type": "string", "description": "Why the agent code last exited. When reason is CrashLoopBackOff, this reveals the underlying cause (e.g., OOMKilled, Error)" }, "message": { "type": "string", "description": "Detailed error output from the crash, such as a Python traceback. Captured from the agent's stderr/stdout on non-zero exit." } } }, "SessionResponse": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "ID of the session" }, "serviceId": { "type": "string", "description": "ID of the service for this session" }, "organizationId": { "type": "string", "description": "ID of the organization that this session is associated with" }, "deploymentId": { "type": "string", "description": "ID of the deployment that this session is associated with" }, "endedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the session ended", "nullable": true }, "botStartSeconds": { "type": "integer", "description": "Number of seconds between bot start request and bot start", "nullable": true }, "coldStart": { "type": "boolean", "description": "Whether the bot start was a [cold start](/pipecat-cloud/fundamentals/scaling#cold-starts)", "nullable": true }, "completionStatus": { "type": "string", "description": "The completion status of the session. This can be an http return code or a string like `HTTP_COMPLETED`, `HTTP_ERROR`, `WS_CONNECTION_CLOSED`, among others", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the session was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the session was last updated" }, "resourceMetrics": { "type": "object", "nullable": true, "description": "Resource usage metrics for the session, if available", "properties": { "id": { "type": "string", "description": "ID of the metrics record" }, "sessionId": { "type": "string", "description": "ID of the session these metrics belong to" }, "sampleCount": { "type": "integer", "description": "Number of metric samples collected" }, "cpuMillicoresP50": { "type": "integer", "description": "CPU usage at the 50th percentile (in millicores)" }, "cpuMillicoresP90": { "type": "integer", "description": "CPU usage at the 90th percentile (in millicores)" }, "cpuMillicoresP95": { "type": "integer", "description": "CPU usage at the 95th percentile (in millicores)" }, "cpuMillicoresP99": { "type": "integer", "description": "CPU usage at the 99th percentile (in millicores)" }, "memoryBytesP50": { "type": "integer", "description": "Memory usage at the 50th percentile (in bytes)" }, "memoryBytesP90": { "type": "integer", "description": "Memory usage at the 90th percentile (in bytes)" }, "memoryBytesP95": { "type": "integer", "description": "Memory usage at the 95th percentile (in bytes)" }, "memoryBytesP99": { "type": "integer", "description": "Memory usage at the 99th percentile (in bytes)" }, "timeseries": { "type": "array", "description": "Time-series data of resource usage", "items": { "type": "object", "properties": { "t": { "type": "integer", "description": "Unix timestamp (seconds)" }, "c": { "type": "integer", "description": "CPU usage (millicores)" }, "m": { "type": "integer", "description": "Memory usage (bytes)" } } } }, "eventTs": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent metrics event" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the metrics record was created" } } }, "meetingIds": { "type": "array", "description": "Daily meeting IDs associated with this session", "items": { "type": "object", "properties": { "participantId": { "type": "string", "description": "Daily participant ID" }, "meetingId": { "type": "string", "description": "Daily meeting ID" } } } } } }, "ServiceListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the agent" }, "name": { "type": "string", "description": "Name of the agent" }, "region": { "type": "string", "description": "The region where the agent is deployed" }, "desiredDeploymentId": { "type": "string", "description": "ID of the deployment that was requested. Use this to track which deployment should be running." }, "activeDeploymentId": { "type": "string", "description": "**Deprecated**: Use `desiredDeploymentId` instead. ID of the requested deployment.", "deprecated": true }, "reconciledDeploymentId": { "type": "string", "description": "ID of the deployment that the operator has actually reconciled. Compare with `desiredDeploymentId` to determine if a deployment update has been processed." }, "organizationId": { "type": "string", "description": "Organization ID this agent belongs to" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp of the agent" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "deletedAt": { "type": "string", "format": "date-time", "description": "Deletion timestamp, if the agent has been deleted", "nullable": true }, "deployment": { "type": "object", "description": "Details of the active deployment (only included when includeActiveDeployment=true)", "properties": { "id": { "type": "string", "description": "Deployment ID" }, "serviceId": { "type": "string", "description": "Service ID" }, "manifest": { "type": "object", "description": "Kubernetes manifest for the deployment" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp of the deployment" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp of the deployment" } } } } }, "UpdateServiceRequest": { "type": "object", "properties": { "image": { "type": "string", "description": "The container image to use for the agent. Cannot be specified together with `buildId`.", "example": "your-username/my-agent:latest" }, "buildId": { "type": "string", "format": "uuid", "description": "The ID of a successful cloud build to deploy. Cannot be specified together with `image`. The build must be in the same region as the agent.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "nodeType": { "type": "string", "description": "The type of node to run the agent on. Only `arm` is supported at this time.", "default": "arm", "example": "arm" }, "imagePullSecretSet": { "type": "string", "description": "The name of the image pull secret set to use", "example": "dockerhub-credentials" }, "secretSet": { "type": "string", "description": "The name of the secret set to use", "example": "my-agent-secrets" }, "autoScaling": { "type": "object", "description": "Auto-scaling configuration for the agent", "properties": { "minAgents": { "type": "integer", "description": "Minimum number of agents", "example": 1 }, "maxAgents": { "type": "integer", "description": "Maximum number of agents (Default: 50)", "example": 10 } } }, "krispViva": { "type": "object", "description": "Krisp VIVA noise cancellation configuration. [Learn more](/pipecat-cloud/guides/krisp-viva).", "properties": { "audioFilter": { "type": "string", "nullable": true, "description": "The Krisp VIVA audio filter model to use:\n\n- `tel`: Optimized for telephony, cellular, landline, mobile, desktop, and browser (up to 16kHz)\n- `pro`: Optimized for mobile, desktop, and browser with WebRTC (up to 32kHz)\n- `null`: Disables Krisp VIVA\n\nBy default, Pipecat processes input audio at 16kHz, making `tel` appropriate for most use cases.", "enum": ["tel", "pro", null], "example": "tel" } } }, "agentProfile": { "type": "string", "description": "The agent profile to use for resource allocation. Valid values are:\n\n- `agent-1x`: 0.5 vCPU and 1 GB of memory. Best for voice agents.\n- `agent-2x`: 1 vCPU and 2 GB of memory. Well suited for voice and video agents or voice agents requiring extra processing.\n- `agent-3x`: 1.5 vCPU and 3 GB of memory. Best for voice and video agents requiring extra processing or multiple video inputs.", "enum": ["agent-1x", "agent-2x", "agent-3x"], "default": "agent-1x", "example": "agent-1x" }, "forceRedeploy": { "type": "boolean", "description": "Force a new deployment even if the configuration hasn't changed. Useful for picking up updated container images when using mutable tags like `latest`, or for refreshing modified secret values.", "default": false, "example": true }, "maxSessionDuration": { "type": "integer", "description": "Maximum session duration in seconds. When a session reaches this limit, the session is stopped: the bot is cancelled, with no opportunity for it to say goodbye first. Valid range: 60 to 14400 (4 hours). Defaults to 7200 (2 hours) when unset.", "minimum": 60, "maximum": 14400, "default": 7200, "example": 3600 } } }, "ServiceDetailsResponse": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the agent" }, "region": { "type": "string", "description": "The region where the agent is deployed" }, "ready": { "type": "boolean", "description": "Whether the latest deployment has passed validation and is ready. For scale-to-zero agents, this is true even when scaled down to zero replicas." }, "available": { "type": "boolean", "description": "Whether the agent can accept new sessions. True when any pods are ready to handle traffic, or when scaled to zero but healthy (requests will queue and trigger scale-up). During rolling updates, this may be true even if `ready` is false, as old pods continue serving while new ones validate." }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp of the agent" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "desiredDeploymentId": { "type": "string", "description": "ID of the deployment that was requested. Use this to track which deployment should be running." }, "activeDeploymentId": { "type": "string", "description": "**Deprecated**: Use `desiredDeploymentId` instead. ID of the requested deployment.", "deprecated": true }, "reconciledDeploymentId": { "type": "string", "description": "ID of the deployment that the operator has actually reconciled. Compare with `desiredDeploymentId` to determine if a deployment update has been processed. When these match and `ready` is true, the deployment is fully complete." }, "activeDeploymentReady": { "type": "boolean", "description": "**Deprecated**: Use `ready` instead. Whether the active deployment is ready. This field is redundant with `ready` and will be removed in a future version.", "deprecated": true }, "autoScaling": { "type": "object", "properties": { "maxReplicas": { "type": "integer", "description": "Maximum number of agent replicas" }, "minReplicas": { "type": "integer", "description": "Minimum number of agent replicas" } } }, "activeSessionCount": { "type": "integer", "description": "Number of active sessions" }, "deployment": { "type": "object", "nullable": true, "description": "Details of the current deployment", "properties": { "id": { "type": "string", "description": "Unique identifier for the deployment" }, "manifest": { "type": "object", "description": "Kubernetes manifest for the deployment", "properties": { "apiVersion": { "type": "string", "description": "API version of the manifest" }, "kind": { "type": "string", "description": "Kind of Kubernetes resource" }, "metadata": { "type": "object", "description": "Metadata for the resource", "properties": { "name": { "type": "string", "description": "Name of the agent" }, "namespace": { "type": "string", "description": "Kubernetes namespace" } } }, "spec": { "type": "object", "description": "Specification for the agent deployment", "properties": { "dailyNodeType": { "type": "string", "description": "Type of node to run on" }, "image": { "type": "string", "description": "Container image used. Redacted when deployed via a build." }, "autoScaling": { "type": "object", "description": "Auto-scaling configuration", "properties": { "minReplicas": { "type": "integer", "description": "Minimum number of replicas" }, "maxReplicas": { "type": "integer", "description": "Maximum number of replicas" } } }, "imagePullSecretName": { "type": "string", "description": "Name of the image pull secret used" }, "envFromSecretNames": { "type": "array", "description": "Names of secrets to use as environment variables", "items": { "type": "string" } }, "resources": { "type": "object", "description": "Resource allocation for the agent", "properties": { "cpu": { "type": "string", "description": "CPU allocation" }, "memory": { "type": "string", "description": "Memory allocation" } } }, "krispViva": { "type": "object", "description": "Krisp VIVA configuration", "properties": { "audioFilters": { "type": "boolean", "description": "Whether Krisp VIVA audio filters are enabled" } } }, "maxSessionDurationSeconds": { "type": "integer", "description": "Maximum session duration in seconds configured for this service. Absent when the service is using the platform default." } } } } }, "serviceId": { "type": "string", "description": "ID of the service this deployment belongs to" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp of the deployment" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp of the deployment" } } }, "agentProfile": { "type": "string", "description": "The agent profile used for resource allocation", "nullable": true }, "krispViva": { "type": "object", "nullable": true, "description": "Krisp VIVA status", "properties": { "audioFilter": { "type": "string", "nullable": true, "description": "The currently configured Krisp VIVA audio filter model (tel, pro, or null if disabled)" } } }, "currentRevision": { "description": "Status of the current (latest) deployment revision", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RevisionInfo" } ] }, "previousRevision": { "description": "Status of the previous deployment revision (present during rolling updates)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/RevisionInfo" } ] } } }, "CreateBuildRequest": { "type": "object", "required": ["uploadId", "region"], "properties": { "uploadId": { "type": "string", "format": "uuid", "description": "The upload ID returned from the upload-url endpoint.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "region": { "type": "string", "description": "Target region for the build. Must match the region used when getting the upload URL.", "example": "us-west" }, "dockerfilePath": { "type": "string", "default": "Dockerfile", "description": "Path to the Dockerfile within the context archive.", "example": "Dockerfile" } } }, "CreateBuildResponse": { "type": "object", "properties": { "build": { "$ref": "#/components/schemas/Build" }, "contextHash": { "type": "string", "description": "Hash of the uploaded context. Used for build caching.", "example": "a1b2c3d4e5f6a7b8" }, "cached": { "type": "boolean", "description": "Whether this response uses a cached build (true) or triggered a new build (false).", "example": false } } }, "GetBuildResponse": { "type": "object", "properties": { "build": { "$ref": "#/components/schemas/Build" } } }, "Build": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the build.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "organizationId": { "type": "string", "description": "Organization that owns this build.", "example": "org_abc123" }, "status": { "type": "string", "enum": ["pending", "building", "success", "failed", "timeout"], "description": "Current status of the build.", "example": "success" }, "region": { "type": "string", "description": "Region where the build ran.", "example": "us-west" }, "contextHash": { "type": "string", "description": "Hash of the build context.", "example": "a1b2c3d4e5f6a7b8" }, "dockerfilePath": { "type": "string", "description": "Path to the Dockerfile used for this build.", "example": "Dockerfile" }, "imageUri": { "type": "string", "description": "URI of the built image. Use this value when deploying an agent. Only present when status is 'success'.", "example": "123456789.dkr.ecr.us-west-2.amazonaws.com/pipecat-cloud/org_abc123:a1b2c3d4e5f6a7b8" }, "logsUrl": { "type": "string", "format": "uri", "description": "URL to view build logs in the cloud console.", "example": "https://console.aws.amazon.com/codebuild/..." }, "errorMessage": { "type": "string", "description": "Detailed error message if the build failed. Includes information from the build phases to help diagnose issues.", "example": "Docker build failed: COPY failed - file not found: requirements.txt" }, "contextSizeBytes": { "type": "integer", "description": "Size of the uploaded context in bytes.", "example": 10485760 }, "imageSizeBytes": { "type": "integer", "description": "Size of the built Docker image in bytes. Only present for successful builds.", "example": 524288000 }, "buildDurationSeconds": { "type": "integer", "description": "Total build duration in seconds. Only present when build is complete.", "example": 120 }, "startedAt": { "type": "string", "format": "date-time", "description": "When the build started executing.", "example": "2026-02-20T12:00:00.000Z" }, "completedAt": { "type": "string", "format": "date-time", "description": "When the build completed (success, failed, or timeout).", "example": "2026-02-20T12:02:00.000Z" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the build record was created.", "example": "2026-02-20T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the build record was last updated.", "example": "2026-02-20T12:02:00.000Z" } } }, "GetBuildLogsResponse": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "string" }, "description": "Array of log lines from the build process. May be empty if the build hasn't started generating logs yet.", "example": [ "[Container] 2026/03/04 10:00:00 Entering phase: INSTALL", "[Container] 2026/03/04 10:00:01 Running command pip install -r requirements.txt", "[Container] 2026/03/04 10:00:05 Successfully installed pipecat-ai-0.1.0" ] }, "nextToken": { "type": "string", "description": "Pagination token for retrieving additional logs. Present when more logs are available.", "example": "eyJuZXh0VG9rZW4iOiAiYWJjMTIzIn0=" } }, "required": ["logs"] }, "ListBuildsResponse": { "type": "object", "properties": { "builds": { "type": "array", "items": { "$ref": "#/components/schemas/Build" }, "description": "Array of build objects." }, "total": { "type": "integer", "description": "Total number of builds matching the filters.", "example": 42 }, "limit": { "type": "integer", "description": "Maximum number of builds returned.", "example": 20 }, "offset": { "type": "integer", "description": "Number of builds skipped.", "example": 0 } } }, "UploadUrlRequest": { "type": "object", "required": ["region"], "properties": { "region": { "type": "string", "description": "Target region for the build. Must be a region where cloud builds are enabled.", "example": "us-west" } } }, "UploadUrlResponse": { "type": "object", "properties": { "uploadId": { "type": "string", "format": "uuid", "description": "Unique identifier for this upload. Use this when creating the build.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "uploadUrl": { "type": "string", "format": "uri", "description": "Pre-signed URL to upload your context archive. Use HTTP POST with form-data.", "example": "https://daily-co-pcc-build-context.s3.amazonaws.com" }, "uploadFields": { "type": "object", "description": "Form fields that must be included when uploading to the pre-signed URL.", "additionalProperties": { "type": "string" }, "example": { "key": "org-123/550e8400-e29b-41d4-a716-446655440000.tar.gz", "bucket": "daily-co-pcc-build-context-qa-us-west-2", "Content-Type": "application/gzip", "Policy": "eyJleHBpcmF0aW9uIjoi...", "X-Amz-Algorithm": "AWS4-HMAC-SHA256", "X-Amz-Credential": "ASIA.../us-west-2/s3/aws4_request", "X-Amz-Date": "20260220T120000Z", "X-Amz-Security-Token": "FwoGZXIvYXdzE...", "X-Amz-Signature": "abc123..." } }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the upload URL expires. Upload must complete before this time.", "example": "2026-02-20T12:15:00.000Z" } } }, "OrganizationProperties": { "type": "object", "description": "Organization configuration properties", "properties": { "defaultRegion": { "type": "string", "description": "Default region for new service deployments", "example": "us-west" } } }, "PropertySchema": { "type": "object", "description": "Schema information for a single property", "properties": { "type": { "type": "string", "description": "Property data type (string, number, boolean, array, etc.)", "example": "string" }, "description": { "type": "string", "description": "Human-readable description of the property", "example": "Default region for new service deployments" }, "default": { "description": "Default value when property is not set" }, "currentValue": { "description": "Current value of the property for this organization" }, "readOnly": { "type": "boolean", "description": "Whether this property is read-only (cannot be modified via API)", "example": false }, "availableValues": { "type": "array", "description": "List of valid values for this property (if applicable)", "items": {} } }, "required": [ "type", "description", "default", "currentValue", "readOnly" ] }, "Region": { "type": "object", "properties": { "code": { "type": "string", "description": "Region code identifier (e.g., 'us-west', 'eu-central')", "example": "us-west" }, "display_name": { "type": "string", "description": "Human-readable region name", "example": "US West (Oregon)" } }, "required": ["code", "display_name"] }, "RegularSecretsRequest": { "type": "object", "properties": { "secrets": { "type": "array", "items": { "type": "object", "properties": { "secretKey": { "type": "string", "description": "Name of the secret key" }, "secretValue": { "type": "string", "description": "Value of the secret" } }, "required": ["secretKey", "secretValue"] }, "minItems": 1, "description": "Array of secret key-value pairs" }, "region": { "type": "string", "description": "The region where the secret set will be created. If not specified, defaults to the organization's default region. Secrets must be in the same region as the agents that use them. Cannot be changed after creation.", "example": "us-west" } }, "required": ["secrets"] }, "ImagePullSecretRequest": { "type": "object", "properties": { "isImagePullSecret": { "type": "boolean", "enum": [true], "description": "Must be true for image pull secrets" }, "host": { "type": "string", "format": "uri", "description": "Host URL. A trailing slash will be added automatically if not present.", "example": "https://index.docker.io/v1/" }, "secretValue": { "type": "string", "description": "Authentication token or credentials" }, "region": { "type": "string", "description": "The region where the secret set will be created. If not specified, defaults to the organization's default region. Secrets must be in the same region as the agents that use them.", "example": "us-west" } }, "required": ["isImagePullSecret", "host", "secretValue"] }, "SecretSetSummary": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the secret set" }, "type": { "type": "string", "enum": ["secret", "imagePullSecret"], "description": "Type of the secret set" }, "region": { "type": "string", "description": "The region where the secret set is stored" }, "status": { "type": "string", "enum": ["pending", "ready", "failed"], "description": "Readiness state. `pending` while provisioning is in flight, `ready` once the set can be bound to a deploy, `failed` if provisioning could not complete." }, "errorMessage": { "type": "string", "description": "Customer-facing message returned only when `status` is `failed`." } } }, "SecretKey": { "type": "object", "properties": { "fieldName": { "type": "string", "description": "Name of the secret key (values are not returned for security)" } } }, "ProxiedResponse": { "type": "object", "description": "Response from your bot endpoint. The schema depends on what your bot returns.", "additionalProperties": true, "example": { "status": "active", "message_count": 5, "user_name": "Alice" } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing what went wrong" }, "code": { "type": "string", "description": "Error code for programmatic handling. Deployment-related codes (PCC-*) are documented at https://docs.pipecat.ai/pipecat-cloud/fundamentals/error-codes" } }, "required": ["error", "code"] }, "StartRequest": { "type": "object", "properties": { "createDailyRoom": { "type": "boolean", "default": false, "description": "Whether to create a Daily room for the service instance", "example": true }, "dailyRoomProperties": { "type": "object", "description": "Optional configuration for the Daily room. Only used when createDailyRoom is true.\n\nSee [Daily API documentation](https://docs.daily.co/reference/rest-api/rooms/config) for supported properties.", "example": { "enable_recording": "cloud" } }, "dailyMeetingTokenProperties": { "type": "object", "description": "Optional configuration for the Daily meeting token. Only used when createDailyRoom is true.\n\nSee [Daily API documentation](https://docs.daily.co/reference/rest-api/meeting-tokens/config) for supported properties.", "example": { "is_owner": true, "start_cloud_recording": true } }, "enableDefaultIceServers": { "type": "boolean", "default": false, "description": "Whether to use the default STUN/TURN ICE servers provided by Pipecat Cloud.", "example": true }, "transport": { "type": "string", "description": "Explicitly specify which transport the bot should use.", "enum": ["daily", "webrtc", "websocket"], "example": "webrtc" }, "body": { "type": "object", "description": "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](/pipecat-cloud/fundamentals/active-sessions#passing-data) for details.", "example": { "foo": "bar" } } } }, "StartResponse": { "type": "object", "properties": { "token": { "type": "string", "description": "HMAC session token for WebSocket authentication (only when transport is \"websocket\")", "example": "eyJzaCI6Im15LWFnZW50Lm15LW9yZyIsImV4cCI6MTcxMjgwMDAwMCwibm9uY2UiOiJhYmMxMjMifQ.dGVzdC1zaWduYXR1cmU" }, "wsUrl": { "type": "string", "description": "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": { "type": "string", "description": "Base64-encoded JSON body for the bot (only when transport is \"websocket\" and the request included a `body`). Append to `wsUrl` as a `?body=` query parameter when connecting.", "example": "eyJjYWxsZXJfaWQiOiJhYmMxMjMifQ==" }, "dailyRoom": { "type": "string", "description": "URL of the created Daily room (if createDailyRoom was set to true)", "example": "https://cloud-354b1860310a444ba0f528b6a2f467c4.daily.co/qZbK9nyXCDCmQ0zDDZta" }, "dailyToken": { "type": "string", "description": "Token to access the Daily room (if createDailyRoom was set to true)", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "sessionId": { "type": "string", "description": "Session ID for the created session", "example": "639f91d8-d511-4677-a83b-bd7564d5d92f" }, "iceConfig": { "type": "object", "description": "ICE server configuration (only included when enableDefaultIceServers is true)", "properties": { "iceServers": { "type": "array", "items": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string" }, "description": "Array of STUN/TURN server URLs" }, "username": { "type": "string", "description": "Authentication username for TURN servers" }, "credential": { "type": "string", "description": "Authentication credential for TURN servers" } } } } }, "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..." } ] } } } }, "StopResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the stop operation", "example": "terminated" }, "session_id": { "type": "string", "format": "uuid", "description": "Session ID of the stopped session", "example": "639f91d8-d511-4677-a83b-bd7564d5d92f" } } } }, "parameters": { "ServiceName": { "name": "serviceName", "in": "path", "required": true, "description": "Name of the deployed agent", "schema": { "type": "string" }, "example": "my-agent" }, "SessionId": { "name": "sessionId", "in": "path", "required": true, "description": "Session ID returned from the start endpoint", "schema": { "type": "string", "format": "uuid" }, "example": "57af5437-97a2-4646-9873-a5c5935bd705" }, "Path": { "name": "path", "in": "path", "required": true, "description": "The endpoint path defined in your bot using the `@app` decorator", "schema": { "type": "string" }, "example": "status" } }, "responses": { "ServiceNotAvailable": { "description": "Service deployment is not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Attempt to start agent when deployment is not in ready state. Is your image pull secret valid?", "code": "PCC-1001" } } } }, "Unauthorized": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Unauthorized / token expired", "code": "401" } } } }, "NotFound": { "description": "Service or session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Service not found", "code": "404" } } } }, "InternalServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Internal server error. Please check logs for more information or contact support.", "code": "500" } } } } } } }