Create an Agent

POST /agents creates a Pipecat Cloud agent from a container image with deployment configuration settings.

POST /agents

Create a new agent

cURL

curl --request POST \
  --url https://api.pipecat.daily.co/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "serviceName": "voice-starter",
  "image": "your-dockername/voice-starter:0.1",
  "region": "us-west",
  "architecture": "arm64",
  "imagePullSecretSet": "dockerhub-credentials",
  "secretSet": "voice-starter-secrets",
  "autoScaling": {
    "minAgents": 1,
    "maxAgents": 20
  },
  "krispViva": {
    "audioFilter": "tel"
  },
  "agentProfile": "agent-1x",
  "maxSessionDuration": 3600
}
'

200

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"
  }
}

Authorizations

Authorization · string · header · required

Authentication requires a Pipecat Cloud Private API token.

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

Body

application/json

serviceName · string · required

Name of the agent to create.

Must 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.

Maximum string length: 54

Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])$

Example:

"my-voice-agent"

image · string

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 · string<uuid>

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 · string · default: us-west

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.

Example:

"us-west"

architecture · enum<string>

Target CPU architecture for the agent's containers: amd64 or arm64. Must be one of the architectures the target region supports (see the supported_architectures field on List available regions). If omitted, the region's default architecture is used. Daily-hosted regions currently support arm64 only. Set this explicitly when your image is built for a single architecture so it schedules on matching nodes instead of failing at startup.

Available options: amd64, arm64

Example:

"arm64"

nodeType · enum<string> · deprecated

Deprecated: use architecture instead. Legacy alias where arm maps to arm64 and amd maps to amd64. Ignored when architecture is present.

Available options: arm, amd

Example:

"arm"

imagePullSecretSet · string

The name of the image pull secret set to use

Example:

"dockerhub-credentials"

secretSet · string

The name of the secret set to use

Example:

"my-agent-secrets"

autoScaling · object

Auto-scaling configuration for the agent

Show child attributes

krispViva · object

Krisp VIVA noise cancellation configuration. Learn more.

Show child attributes

agentProfile · enum<string> · default: agent-1x

The agent profile to use for resource allocation. Valid values are:

• agent-1x: 0.5 vCPU and 1 GB of memory. Best for voice agents.
• agent-2x: 1 vCPU and 2 GB of memory. Well suited for voice and video agents or voice agents requiring extra processing.
• agent-3x: 1.5 vCPU and 3 GB of memory. Best for voice and video agents requiring extra processing or multiple video inputs.

In a self-hosted region, this may also name one of your organization's own profiles, or be omitted in favour of resources.

Available options: agent-1x, agent-2x, agent-3x

Example:

"agent-1x"

resources · object

Explicit sizing for agents in self-hosted regions, using Kubernetes quantities (e.g. cpu: "1", memory: "2Gi"). Mutually exclusive with agentProfile; accepted only when the target region is self-hosted.

Show child attributes

maxSessionDuration · integer · default: 7200

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.

Required range: 60 <= x <= 14400

Example:

3600

Response

200

application/json

Agent created successfully

name · string

Name of the agent

region · string

The region where the agent is deployed

ready · boolean

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 · boolean

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 · string<date-time>

Creation timestamp of the agent

updatedAt · string<date-time>

Last update timestamp

desiredDeploymentId · string

ID of the deployment that was requested. Use this to track which deployment should be running.

activeDeploymentId · string · deprecated

Deprecated: Use desiredDeploymentId instead. ID of the requested deployment.

reconciledDeploymentId · string

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 · boolean · deprecated

Deprecated: Use ready instead. Whether the active deployment is ready. This field is redundant with ready and will be removed in a future version.

autoScaling · object

Show child attributes

activeSessionCount · integer

Number of active sessions

deployment · object | null

Details of the current deployment

Show child attributes

agentProfile · string | null

The agent profile used for resource allocation

krispViva · object | null

Krisp VIVA status

Show child attributes

currentRevision · object | null

Status of the current (latest) deployment revision

Show child attributes

previousRevision · object | null

Status of the previous deployment revision (present during rolling updates)

Show child attributes