Skip to main content
POST
/
agents
Create a new agent
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",
  "nodeType": "arm",
  "imagePullSecretSet": "dockerhub-credentials",
  "secretSet": "voice-starter-secrets",
  "autoScaling": {
    "minAgents": 1,
    "maxAgents": 20
  },
  "krispViva": {
    "audioFilter": "tel"
  },
  "agentProfile": "agent-1x",
  "enableManagedKeys": false
}'
{
  "name": "voice-starter",
  "region": "us-west",
  "ready": false,
  "createdAt": "2025-04-19T01:20:27.564Z",
  "updatedAt": "2025-04-19T01:20:27.572Z",
  "activeDeploymentId": "13c0be89-5ae8-4b0b-ad22-79565e11de3b",
  "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",
        "deploymentMode": "keda",
        "clusterLocal": true,
        "image": "your-dockername/voice-starter:0.1",
        "autoScaling": {
          "minReplicas": 1,
          "maxReplicas": 20
        },
        "envFromSecretNames": [
          "voice-starter-secrets"
        ],
        "krispModels": {
          "enabled": false
        },
        "krispViva": {
          "audioFilters": true,
          "version": "20251010",
          "modelVars": {
            "KRISP_VIVA_MODEL_PATH": "audio_filters/krisp-viva-tel-v2.kef"
          }
        },
        "integratedKeysProxy": {
          "enabled": false
        },
        "resources": {
          "cpu": "500m",
          "memory": "1Gi"
        }
      }
    },
    "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.

Example:

"my-voice-agent"

​
image
string
required

The container image to use for the agent

Example:

"your-username/my-agent:latest"

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

​
nodeType
string
default:arm

The type of node to run the agent on. Only arm is supported at this time.

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

​
enableKrisp
boolean
default:false
deprecated

Whether to enable Krisp noise cancellation. Deprecated: Use krispViva instead for the latest Krisp VIVA models.

Example:

false

​
krispViva
object

Krisp VIVA noise cancellation configuration. Learn more.

​
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.
Available options:
agent-1x,
agent-2x,
agent-3x
Example:

"agent-1x"

​
enableManagedKeys
boolean
default:false

Pipecat Cloud provides API keys for some Pipecat services that you can use directly in your applications. Learn more.

Example:

false

Response

Agent created successfully

​
name
string

Name of the agent

​
region
string

The region where the agent is deployed

​
ready
boolean

Whether the agent is ready to accept sessions

​
createdAt
string<date-time>

Creation timestamp of the agent

​
updatedAt
string<date-time>

Last update timestamp

​
activeDeploymentId
string

ID of the active deployment

​
activeDeploymentReady
boolean

Whether the active deployment is ready

​
autoScaling
object
​
activeSessionCount
integer

Number of active sessions

​
deployment
object | null

Details of the current deployment

​
agentProfile
string | null

The agent profile used for resource allocation

​
krispViva
object | null

Krisp VIVA noise cancellation status