diff --git a/api-reference/cli/cloud/deploy.mdx b/api-reference/cli/cloud/deploy.mdx
index ce047c85..41905c8c 100644
--- a/api-reference/cli/cloud/deploy.mdx
+++ b/api-reference/cli/cloud/deploy.mdx
@@ -40,7 +40,9 @@ pipecat cloud deploy [ARGS] [OPTIONS]
Name of the image pull secret to use for accessing private repositories. The
secret must be previously created using the `pipecat cloud secrets
- image-pull-secret` command.
+ image-pull-secret` command, and must be in the
+ [`ready`](/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness)
+ state at deploy time.
@@ -50,7 +52,9 @@ pipecat cloud deploy [ARGS] [OPTIONS]
Name of the secret set to use for the deployment. The secret set must exist in
- the specified organization.
+ the specified organization and must be in the
+ [`ready`](/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness)
+ state — deploys that bind a `pending` or `failed` set are rejected.
@@ -284,7 +288,9 @@ region = "us-east"
Name of the secret set to use for environment variables. The secret set must
-exist in the same region as the agent.
+exist in the same region as the agent and must be in the
+[`ready`](/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness)
+state — deploys that bind a `pending` or `failed` set are rejected.
```toml
secret_set = "my-agent-secrets"
@@ -293,7 +299,7 @@ secret_set = "my-agent-secrets"
-Name of the image pull secret for private registries. The image pull secret must exist in the same region as the agent.
+Name of the image pull secret for private registries. The image pull secret must exist in the same region as the agent and must be in the [`ready`](/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness) state.
```toml
image_credentials = "dockerhub-credentials"
diff --git a/api-reference/cli/cloud/secrets.mdx b/api-reference/cli/cloud/secrets.mdx
index 2c38b5fc..74c2fd99 100644
--- a/api-reference/cli/cloud/secrets.mdx
+++ b/api-reference/cli/cloud/secrets.mdx
@@ -8,8 +8,12 @@ The `secrets` command group helps you manage sensitive information for your agen
## list
List secret sets and image pull secrets for active namespace / organization.
+Each row includes a
+[readiness status](/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness)
+(`ready`, `pending`, or `failed`).
-If provided with a valid secret set name, will show the keys of that set (values are hidden.)
+If provided with a valid secret set name, will show the keys of that set
+alongside its status (values are hidden).
**Usage:**
diff --git a/api-reference/pipecat-cloud/rest-reference/openapi-secret-create-update.json b/api-reference/pipecat-cloud/rest-reference/openapi-secret-create-update.json
index f372228e..1b551ae6 100644
--- a/api-reference/pipecat-cloud/rest-reference/openapi-secret-create-update.json
+++ b/api-reference/pipecat-cloud/rest-reference/openapi-secret-create-update.json
@@ -15,7 +15,7 @@
"/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.",
+ "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` → `ready`). Deploys that bind a secret set whose status is not `ready` are rejected with `409 Conflict`.",
"operationId": "upsertSecretSet",
"security": [
{
@@ -83,8 +83,8 @@
}
},
"responses": {
- "200": {
- "description": "Secret set successfully created or updated",
+ "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": {
@@ -169,6 +169,20 @@
}
}
},
+ "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": {
diff --git a/api-reference/pipecat-cloud/rest-reference/openapi-secret-list-all.json b/api-reference/pipecat-cloud/rest-reference/openapi-secret-list-all.json
index 925f0e55..fe761223 100644
--- a/api-reference/pipecat-cloud/rest-reference/openapi-secret-list-all.json
+++ b/api-reference/pipecat-cloud/rest-reference/openapi-secret-list-all.json
@@ -43,12 +43,14 @@
{
"name": "my-app-secrets",
"type": "secret",
- "region": "us-west"
+ "region": "us-west",
+ "status": "ready"
},
{
"name": "dockerhub-credentials",
"type": "imagePullSecret",
- "region": "us-west"
+ "region": "us-west",
+ "status": "pending"
}
]
}
@@ -120,6 +122,15 @@
"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`."
}
}
}
diff --git a/api-reference/pipecat-cloud/rest-reference/openapi-secret-list-one.json b/api-reference/pipecat-cloud/rest-reference/openapi-secret-list-one.json
index eb8e8e57..5684d419 100644
--- a/api-reference/pipecat-cloud/rest-reference/openapi-secret-list-one.json
+++ b/api-reference/pipecat-cloud/rest-reference/openapi-secret-list-one.json
@@ -38,7 +38,7 @@
],
"responses": {
"200": {
- "description": "Secret set details",
+ "description": "Secret set details, including readiness status",
"content": {
"application/json": {
"schema": {
@@ -48,6 +48,15 @@
"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 — internal diagnostic details are kept in platform logs."
+ },
"secrets": {
"type": "array",
"items": {
@@ -58,6 +67,7 @@
},
"example": {
"region": "us-west",
+ "status": "ready",
"secrets": [
{ "fieldName": "API_KEY" },
{ "fieldName": "DATABASE_URL" },
diff --git a/pipecat-cloud/fundamentals/error-codes.mdx b/pipecat-cloud/fundamentals/error-codes.mdx
index cc5d52b6..4fe870eb 100644
--- a/pipecat-cloud/fundamentals/error-codes.mdx
+++ b/pipecat-cloud/fundamentals/error-codes.mdx
@@ -67,6 +67,23 @@ Indicates an error in your image that prevent your agent from starting. Typicall
This error indicates that the maximum active sessions for your deployment have been reached. You can either increase the maximum active sessions for your deployment (`max-agents`), or place the end-user in a queue until a session becomes available.
+### Deploy rejected — secret set not ready (HTTP 409)
+
+> `Secret set 'my-agent-secrets' is not yet ready. Retry once it has been provisioned.`
+
+A deploy that binds a secret set or image pull secret is rejected if the
+referenced set is not in the `ready` state. This guards against the deploy
+appearing to succeed and then failing once the agent tries to start.
+
+- **`pending`**: provisioning is still in flight. Wait a few seconds and
+ retry.
+- **`failed`**: provisioning could not complete. Re-create the secret set
+ or [contact support](mailto:help@daily.co).
+
+See
+[Provisioning and readiness](./secrets#provisioning-and-readiness) for
+how to inspect the status before deploying.
+
## Enabling extra logs
If you wish to print a summary of the features available in the base image, set the environment variable `PCC_LOG_FEATURES_SUMMARY` to `true`.
diff --git a/pipecat-cloud/fundamentals/secrets.mdx b/pipecat-cloud/fundamentals/secrets.mdx
index c3c8db82..9bfe6e7f 100644
--- a/pipecat-cloud/fundamentals/secrets.mdx
+++ b/pipecat-cloud/fundamentals/secrets.mdx
@@ -34,6 +34,35 @@ pipecat cloud secrets set my-secrets SECRET_NAME_3 secret-value-3
using that set will need to be redeployed to access the new values.
+#### Provisioning and readiness
+
+Creating or updating a secret set is **asynchronous**. The CLI/API returns
+immediately (HTTP `202 Accepted`) once your values have been stored, but the
+set is then provisioned into the target region in the background. Provisioning
+typically completes within a few seconds.
+
+Each secret set has one of three readiness states:
+
+| Status | Meaning |
+| --------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `pending` | The secret has been accepted but is not yet provisioned in the target region. |
+| `ready` | The secret is fully provisioned and safe to bind to a deployment. |
+| `failed` | Provisioning could not complete. Re-create the secret or [contact support](mailto:help@daily.co) if the problem persists. |
+
+Readiness is included in `GET /v1/secrets` (list) and `GET /v1/secrets/{setName}`
+(single) responses on the [REST API](/api-reference/pipecat-cloud/rest-reference/endpoint/secret-list-all).
+Deploys, updates, and any other operation that binds a secret set to an agent
+are gated on the `ready` state — a request to deploy with a `pending` or
+`failed` set is rejected with HTTP `409 Conflict` rather than failing later
+when the agent starts.
+
+
+ In an automated pipeline that creates a secret immediately before deploying
+ (e.g., CI), poll `GET /v1/secrets/{setName}` until `status` is `ready` before
+ triggering the deploy. The window is usually only a few seconds, but guarding
+ the deploy avoids a transient `409`.
+
+
#### Regions
Secret sets are created in a specific region. By default, secrets are created in `us-west` if no region is specified.