{ "openapi": "3.0.0", "info": { "title": "Pipecat Cloud", "version": "1.0.0", "description": "Private API for Pipecat Cloud agent management" }, "servers": [ { "url": "https://api.pipecat.daily.co/v1", "description": "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" } } } } } } } }, "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." } }, "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 agent's connection is forcibly closed — the session is cut off mid-flight with no notice to the bot. 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", "nullable": true, "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. May be null for newly created deployments until the operator processes them." }, "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 replicas" }, "minReplicas": { "type": "integer", "description": "Minimum number of 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" } ] } } }, "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." } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" } } } } }, "security": [ { "PrivateKeyAuth": [] } ] }