{
  "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/{agentName}": {
      "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-09T15:01:17.414Z",
                  "updatedAt": "2025-04-18T20:29:19.181Z",
                  "desiredDeploymentId": "4cab03c7-8f53-418d-9c3c-91a1265d179e",
                  "activeDeploymentId": "4cab03c7-8f53-418d-9c3c-91a1265d179e",
                  "reconciledDeploymentId": "4cab03c7-8f53-418d-9c3c-91a1265d179e",
                  "activeDeploymentReady": true,
                  "autoScaling": {
                    "maxReplicas": 10,
                    "minReplicas": 1
                  },
                  "activeSessionCount": 0,
                  "deployment": {
                    "id": "4cab03c7-8f53-418d-9c3c-91a1265d179e",
                    "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
                        }
                      }
                    },
                    "serviceId": "c359e1ea-64d6-4bcf-a7c6-28d3bd1c8909",
                    "createdAt": "2025-04-18T20:29:19.177Z",
                    "updatedAt": "2025-04-18T20:29:19.177Z"
                  },
                  "agentProfile": "agent-1x",
                  "currentRevision": {
                    "deploymentID": "4cab03c7-8f53-418d-9c3c-91a1265d179e",
                    "phase": "Active",
                    "readyReplicas": 1,
                    "phaseStartedAt": "2025-04-18T20:30: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"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "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": {
      "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 replicas"
              },
              "minReplicas": {
                "type": "integer",
                "description": "Minimum number of replicas"
              }
            }
          },
          "activeSessionCount": {
            "type": "integer",
            "description": "Number of active sessions"
          },
          "deployment": {
            "type": "object",
            "description": "Details of the current deployment",
            "properties": {
              "id": {
                "type": "string",
                "description": "Deployment ID"
              },
              "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"
                          }
                        }
                      }
                    }
                  }
                }
              },
              "serviceId": {
                "type": "string",
                "description": "Service ID"
              },
              "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
          },
          "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": []
    }
  ]
}