{ "openapi": "3.0.0", "info": { "title": "Cerebrium REST API", "description": "REST API for interacting with Cerebrium. This API is mainly used by the Cerebrium CLI client, please run `pip install cerebrium` to install it.", "version": "1.0.0", "license": { "name": "Proprietary", "url": "https://www.cerebrium.ai/terms-of-service" } }, "servers": [ { "url": "https://rest.cerebrium.ai" } ], "paths": { "/v2/build-service/status": { "get": { "operationId": "checkBuildServiceStatus", "summary": "Health Check", "description": "Check if the build service is operational.", "responses": { "200": { "description": "Plain-text status message describing build service health." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [], "tags": ["Builds"] } }, "/v2/projects": { "get": { "operationId": "listProjects", "summary": "List Projects", "description": "Retrieve a list of projects.", "responses": { "200": { "description": "A list of projects the caller has access to.", "content": { "application/json": { "schema": { "items": { "properties": { "id": { "description": "Unique identifier of the project.", "type": "string" }, "name": { "description": "Name of the project.", "type": "string" }, "role": { "description": "The caller's role on the project.", "type": "string" } }, "type": "object" }, "type": "array" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Projects"] }, "post": { "operationId": "createProject", "summary": "Create Project", "description": "Create a new project.", "responses": { "200": { "description": "The ID of the newly created project, returned as a plain text string." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Projects"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "description": "The name of the project. Must be between 2 and 50 characters.", "type": "string" } }, "required": ["name"], "type": "object" } } } } } }, "/v2/projects/{project_id}": { "delete": { "operationId": "deleteProject", "summary": "Delete Project", "description": "Remove a specific project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirmation that the project was deleted.", "content": { "application/json": { "schema": { "properties": { "id": { "description": "ID of the deleted project.", "type": "string" }, "message": { "description": "Confirmation message.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Projects"] }, "get": { "operationId": "getProject", "summary": "Get Project", "description": "Retrieve details of a specific project by its ID.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Details of the requested project.", "content": { "application/json": { "schema": { "properties": { "alertAmountDollars": { "description": "Monthly spend amount in US dollars at which a usage alert is sent.", "type": "integer" }, "availableRuntimeVersions": { "description": "The runtime versions offered for pinning, newest first.", "items": { "properties": { "description": { "description": "What the version changes.", "type": "string" }, "state": { "description": "Either \"stable\" or \"beta\".", "type": "string" }, "version": { "description": "The cortex-worker version.", "type": "string" } }, "type": "object" }, "type": "array" }, "basePlanAmountCents": { "description": "Base subscription plan amount in US cents.", "type": "integer" }, "createdAt": { "description": "Timestamp when the project was created, in RFC3339 format.", "type": "string" }, "createdByUserId": { "description": "ID of the user who created the project.", "type": "string" }, "defaultRuntimeVersion": { "description": "The runtime version an unpinned project builds against. A frozen backstop, not a pointer that tracks the newest release.", "type": "string" }, "effectiveLimits": { "description": "Resource limits in effect for the project's plan tier, including logRetentionDays, the most the project may keep.", "type": "object" }, "effectiveLogRetentionDays": { "description": "The log retention in effect, in days, the lower of the chosen value and the plan maximum.", "type": "integer" }, "hardwareCosts": { "description": "Compute pricing entries for the project.", "items": { "properties": { "amountPerSecond": { "description": "Price per second in US dollars.", "type": "number" }, "billableMetricCode": { "description": "The billable metric this rate applies to.", "type": "string" }, "type": { "description": "The hardware type the rate covers.", "type": "string" } }, "type": "object" }, "type": "array" }, "id": { "description": "Unique identifier of the project.", "type": "string" }, "logRetentionDays": { "description": "The log retention the project has chosen, in days. Omitted when the project uses its plan default.", "type": "integer" }, "name": { "description": "Name of the project.", "type": "string" }, "onboarding": { "description": "Onboarding answers for the project, with intent, companyWebsite, useCases, and otherUseCaseReason keys. Omitted when the project has none.", "type": "object" }, "ownerEmailAddress": { "description": "Email address of the project owner.", "type": "string" }, "protected": { "description": "Whether the project runs on the protected compute tier. Omitted when false.", "type": "boolean" }, "requiresPaymentMethod": { "description": "Whether a payment method must be added before deploying.", "type": "boolean" }, "runtimeVersion": { "description": "The cortex-worker version the project's app builds are pinned to. Omitted when the project is unpinned and tracks defaultRuntimeVersion.", "type": "string" }, "updatedAt": { "description": "Timestamp when the project was last updated, in RFC3339 format.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Projects"] }, "patch": { "operationId": "updateProject", "summary": "Modify Project", "description": "Update the configuration or metadata of a specific project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A plain text confirmation message that the project was updated." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Projects"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "alertAmountDollars": { "description": "Monthly spend amount in US dollars at which a usage alert is sent.", "type": "integer" }, "logRetentionDays": { "description": "How many days of app logs stay retrievable: one of 3, 7, 14, 30, 60 or 90, up to the maximum your plan allows. Send 0 to return to the plan default; omit to leave it unchanged. Raising it applies to new logs; lowering it hides older logs immediately.", "type": "integer" }, "name": { "description": "The name of the project.", "type": "string" }, "runtimeVersion": { "description": "The cortex-worker version to pin the project's app builds to, from the availableRuntimeVersions of the get-project response. Send an empty string to unpin and track the default; omit to leave the pin unchanged. The floating \"latest\" tag is still accepted for projects already pinned to it, but is no longer offered.", "type": "string" } }, "required": ["name", "alertAmountDollars"], "type": "object" } } } } } }, "/v2/projects/{project_id}/api-keys": { "get": { "operationId": "listProjectApiKeys", "summary": "List API Keys", "description": "List all API keys for a project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The project's API keys, sorted by expiration date in ascending order.", "content": { "application/json": { "schema": { "items": { "properties": { "apiKey": { "description": "The API key value.", "type": "string" }, "createdAt": { "description": "Creation timestamp in RFC 3339 format.", "type": "string" }, "description": { "description": "Description of the API key.", "type": "string" }, "expiresAt": { "description": "Expiration timestamp in RFC 3339 format, or \"never\" if the key does not expire.", "type": "string" }, "id": { "description": "Unique identifier of the API key.", "type": "string" }, "name": { "description": "Name of the API key.", "type": "string" }, "principalId": { "description": "Principal the API key belongs to, if it was created for a service account.", "type": "string" }, "projectId": { "description": "ID of the project the API key belongs to.", "type": "string" }, "source": { "description": "Origin of the API key.", "type": "string" }, "status": { "description": "Status of the API key.", "type": "string" }, "updatedAt": { "description": "Last update timestamp in RFC 3339 format.", "type": "string" } }, "type": "object" }, "type": "array" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["API Keys"] }, "post": { "operationId": "createProjectApiKey", "summary": "Create API Key", "description": "Create a new API key for a project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "required": false, "description": "Name of the API key (max 50 characters). Defaults to 'API Key'.", "schema": { "type": "string" } }, { "name": "description", "in": "query", "required": false, "description": "Description of the API key (max 255 characters).", "schema": { "type": "string" } }, { "name": "expiresAt", "in": "query", "required": false, "description": "Expiration date in YYYY-MM-DD format. Must be in the future. If omitted, the key never expires.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The created API key, including its secret value.", "content": { "application/json": { "schema": { "properties": { "apiKey": { "description": "The API key value.", "type": "string" }, "createdAt": { "description": "Creation timestamp in RFC 3339 format.", "type": "string" }, "description": { "description": "Description of the API key.", "type": "string" }, "expiresAt": { "description": "Expiration timestamp in RFC 3339 format, or \"never\" if the key does not expire.", "type": "string" }, "id": { "description": "Unique identifier of the API key.", "type": "string" }, "name": { "description": "Name of the API key.", "type": "string" }, "projectId": { "description": "ID of the project the API key belongs to.", "type": "string" }, "source": { "description": "Origin of the API key.", "type": "string" }, "status": { "description": "Status of the API key.", "type": "string" }, "updatedAt": { "description": "Last update timestamp in RFC 3339 format.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["API Keys"] } }, "/v2/projects/{project_id}/api-keys/{api_key_id}": { "delete": { "operationId": "deleteProjectApiKey", "summary": "Delete API Key", "description": "Delete an API key and permanently deny its token. Inference requests using the key start failing within a few seconds. This cannot be undone: the key is not recoverable and the token stays denied. The caller must be an owner on the project. Service account keys are rejected here — delete the service account instead.\n", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api_key_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirmation that the API key was deleted.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Confirmation message.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["API Keys"] } }, "/v2/projects/{project_id}/apps": { "get": { "operationId": "listApps", "summary": "List Apps", "description": "Retrieve a list of apps for a specific project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "includeEphemeral", "in": "query", "required": false, "description": "Include ephemeral apps created by one-off runs. Set to true to include them.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A list of apps in the project with current-month usage metrics.", "content": { "application/json": { "schema": { "items": { "properties": { "cost_metrics": { "description": "Cost and usage metrics for the current month, including CPU, GPU, and memory cost and usage figures.", "type": "object" }, "createdAt": { "description": "Timestamp when the app was created.", "type": "string" }, "ephemeral": { "description": "Whether the app is an ephemeral app created by a one-off run. Omitted when false.", "type": "boolean" }, "hardware": { "description": "Compute type the app runs on.", "type": "string" }, "hardwareProvider": { "description": "Cloud provider the app is deployed on.", "type": "string" }, "id": { "description": "Unique identifier of the app.", "type": "string" }, "name": { "description": "Name of the app.", "type": "string" }, "projectId": { "description": "ID of the project the app belongs to.", "type": "string" }, "region": { "description": "Region the app is deployed in.", "type": "string" }, "request_metrics": { "description": "Request counts for the current month, including successful, errored, and total requests.", "type": "object" }, "status": { "description": "Current status of the app.", "type": "string" }, "updatedAt": { "description": "Timestamp when the app was last updated.", "type": "string" } }, "type": "object" }, "type": "array" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Apps"] }, "post": { "operationId": "createApp", "summary": "Create App", "description": "Create a new app for a specific project using manual upload.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Details of the created app deployment and where to upload the source archive.", "content": { "application/json": { "schema": { "properties": { "buildId": { "description": "ID of the build created for this deployment.", "type": "string" }, "dashboardUrl": { "description": "URL of the app in the dashboard.", "type": "string" }, "internalEndpoint": { "description": "Base URL for invoking the app.", "type": "string" }, "keyName": { "description": "Name of the uploaded source archive.", "type": "string" }, "status": { "description": "Current status of the build.", "type": "string" }, "uploadUrl": { "description": "Presigned URL to upload the app source archive to.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Apps"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "baseImage": { "description": "Base Docker image for the app. Default: debian:bookworm-slim.", "type": "string" }, "cerebrium_toml": { "description": "Verbatim contents of the cerebrium.toml configuration file.", "type": "string" }, "cliVersion": { "description": "Version of the client initiating the deployment.", "type": "string" }, "compute": { "description": "Compute type(s) for the app, in priority order. A single value or a list of up to 5. Valid values: ADA_L4, ADA_L40, AMPERE_A10, AMPERE_A100_40GB, AMPERE_A100_80GB, HOPPER_H100, HOPPER_H200, BLACKWELL_B200, BLACKWELL_RTX6000, CPU, INF2, TRN1, TURING_T4. Default: CPU.", "type": "array" }, "computeTier": { "description": "Compute tier for the app. Valid values: interruptible, protected.", "type": "string" }, "containerRuntime": { "description": "Container runtime version. Valid values: v1, v2.", "type": "string" }, "cooldownPeriodSeconds": { "description": "Cooldown period in seconds before an idle replica scales down. Range: 0-3600. Default: 10.", "type": "integer" }, "cpu": { "description": "Number of CPU cores to allocate. Range: 0.25-192. Default: 2.", "type": "number" }, "deploymentInitializationTimeout": { "description": "Maximum time in seconds to wait for a deployment to initialize. Range: 60-7200. Default: 600.", "type": "integer" }, "disableAuth": { "description": "Disable authentication on the app endpoint. Default: true.", "type": "boolean" }, "dockerAuth": { "description": "Credentials for pulling the base image from a private Docker registry.", "type": "string" }, "dockerfilePath": { "description": "Path to a Dockerfile to build the app from.", "type": "string" }, "entrypoint": { "description": "Command to start a custom runtime app, as a list of strings.", "type": "array" }, "evaluationIntervalSeconds": { "description": "Interval in seconds between autoscaling evaluations. Range: 6-300. Default: 30.", "type": "integer" }, "gpuCount": { "description": "Number of GPUs to allocate. Range: 0-16. Default: 0.", "type": "integer" }, "healthcheckEndpoint": { "description": "HTTP endpoint used to check that a custom runtime app is healthy.", "type": "string" }, "loadBalancingAlgorithm": { "description": "Load balancing algorithm. Valid values: round-robin, first-available, min-connections, random-choice-2. Default: round-robin.", "type": "string" }, "logLevel": { "description": "Log level for the deployment. Valid values: INFO, DEBUG, INTERNAL, ERROR. Default: INFO.", "type": "string" }, "maxReplicaCount": { "description": "Maximum number of replicas. Range: 1-2000. Default: 1.", "type": "integer" }, "memory": { "description": "Memory allocation in GB. Range: 0.05-1984. Default: 4.", "type": "number" }, "minReplicaCount": { "description": "Minimum number of replicas. Range: 0-2000. Default: 0.", "type": "integer" }, "name": { "description": "The name of the app. 3-30 lowercase alphanumeric characters and dashes.", "type": "string" }, "partialUpload": { "description": "Whether the upload contains only files changed since the previous deployment.", "type": "boolean" }, "port": { "description": "Port the app listens on. Range: 0-65535. Default: 8000.", "type": "integer" }, "provider": { "description": "Cloud provider to deploy to. Valid values: aws, crusoe, nebius. Defaults to an automatically selected provider.", "type": "string" }, "pythonVersion": { "description": "Python version to use. Default: 3.11.", "type": "string" }, "readycheckEndpoint": { "description": "HTTP endpoint used to check that a custom runtime app is ready to receive traffic.", "type": "string" }, "region": { "description": "Region to deploy to. Defaults to an automatically selected region.", "type": "string" }, "replicaConcurrency": { "description": "Maximum concurrent requests per replica. Defaults to 100 for CPU apps and 1 for GPU apps.", "type": "integer" }, "responseGracePeriodSeconds": { "description": "Grace period in seconds for in-flight requests when a replica stops. Range: 16-43200. Default: 900.", "type": "integer" }, "rollOutDurationSeconds": { "description": "Duration in seconds over which to roll out a new version. Range: 0-21600.", "type": "integer" }, "runtime": { "description": "App runtime. Valid values: cortex, custom. Default: cortex.", "type": "string" }, "scalingBuffer": { "description": "Number of extra replicas to keep available beyond current demand. Must be \u003e= 0.", "type": "integer" }, "scalingMetric": { "description": "Metric used for autoscaling. Valid values: cpu_utilization, memory_utilization, requests_per_second, concurrency_utilization. Default: concurrency_utilization.", "type": "string" }, "scalingTarget": { "description": "Target value for the scaling metric. Must be \u003e 0. Default: 100.", "type": "integer" }, "useUv": { "description": "Use uv for Python package installation.", "type": "boolean" } }, "required": ["name", "cliVersion"], "type": "object" } } } } } }, "/v2/projects/{project_id}/apps/github": { "post": { "operationId": "createGithubApp", "summary": "Create GitHub App", "description": "Create a new app linked to a GitHub repository for automatic deployments.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Details of the created GitHub-linked app and its first build.", "content": { "application/json": { "schema": { "properties": { "appId": { "description": "Unique identifier of the created app.", "type": "string" }, "appUrl": { "description": "URL of the app in the dashboard.", "type": "string" }, "buildId": { "description": "ID of the build created for this deployment.", "type": "string" }, "dashboardUrl": { "description": "URL of the build in the dashboard.", "type": "string" }, "internalEndpoint": { "description": "Base URL for invoking the app.", "type": "string" }, "logUrl": { "description": "URL for retrieving build logs.", "type": "string" }, "projectId": { "description": "ID of the project the app belongs to.", "type": "string" }, "status": { "description": "Current status of the build.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Apps", "GitHub Integration"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "baseImage": { "description": "Base Docker image for the app. Default: debian:bookworm-slim.", "type": "string" }, "cerebrium_toml": { "description": "Verbatim contents of the cerebrium.toml configuration file.", "type": "string" }, "cliVersion": { "description": "Version of the client initiating the deployment.", "type": "string" }, "compute": { "description": "Compute type(s) for the app, in priority order. A single value or a list of up to 5. Valid values: ADA_L4, ADA_L40, AMPERE_A10, AMPERE_A100_40GB, AMPERE_A100_80GB, HOPPER_H100, HOPPER_H200, BLACKWELL_B200, BLACKWELL_RTX6000, CPU, INF2, TRN1, TURING_T4. Default: CPU.", "type": "array" }, "computeTier": { "description": "Compute tier for the app. Valid values: interruptible, protected.", "type": "string" }, "containerRuntime": { "description": "Container runtime version. Valid values: v1, v2.", "type": "string" }, "cooldownPeriodSeconds": { "description": "Cooldown period in seconds before an idle replica scales down. Range: 0-3600. Default: 10.", "type": "integer" }, "cpu": { "description": "Number of CPU cores to allocate. Range: 0.25-192. Default: 2.", "type": "number" }, "deploymentInitializationTimeout": { "description": "Maximum time in seconds to wait for a deployment to initialize. Range: 60-7200. Default: 600.", "type": "integer" }, "disableAuth": { "description": "Disable authentication on the app endpoint. Default: false.", "type": "boolean" }, "dockerAuth": { "description": "Credentials for pulling the base image from a private Docker registry.", "type": "string" }, "dockerfilePath": { "description": "Path to a Dockerfile to build the app from.", "type": "string" }, "entrypoint": { "description": "Command to start a custom runtime app, as a list of strings.", "type": "array" }, "evaluationIntervalSeconds": { "description": "Interval in seconds between autoscaling evaluations. Range: 6-300.", "type": "integer" }, "githubAutoDeploy": { "description": "Automatically deploy new commits pushed to the configured branch.", "type": "boolean" }, "githubBranch": { "description": "Git branch to deploy. Default: main.", "type": "string" }, "githubPath": { "description": "Path within the repository containing the app.", "type": "string" }, "githubRepo": { "description": "GitHub repository to deploy from, in owner/repo format.", "type": "string" }, "gpuCount": { "description": "Number of GPUs to allocate. Range: 0-16. Default: 0.", "type": "integer" }, "healthcheckEndpoint": { "description": "HTTP endpoint used to check that a custom runtime app is healthy.", "type": "string" }, "loadBalancingAlgorithm": { "description": "Load balancing algorithm. Valid values: round-robin, first-available, min-connections, random-choice-2.", "type": "string" }, "logLevel": { "description": "Log level for the deployment. Valid values: INFO, DEBUG, INTERNAL, ERROR. Default: INFO.", "type": "string" }, "maxReplicaCount": { "description": "Maximum number of replicas. Range: 1-2000. Default: 1.", "type": "integer" }, "memory": { "description": "Memory allocation in GB. Range: 0.05-1984. Default: 4.", "type": "number" }, "minReplicaCount": { "description": "Minimum number of replicas. Range: 0-2000. Default: 0.", "type": "integer" }, "name": { "description": "The name of the app. 3-30 lowercase alphanumeric characters and dashes.", "type": "string" }, "partialUpload": { "description": "Whether the upload contains only files changed since the previous deployment.", "type": "boolean" }, "port": { "description": "Port the app listens on. Range: 0-65535. Default: 8000.", "type": "integer" }, "provider": { "description": "Cloud provider to deploy to. Valid values: aws, crusoe, nebius. Defaults to an automatically selected provider.", "type": "string" }, "pythonVersion": { "description": "Python version to use. Default: 3.10.", "type": "string" }, "readycheckEndpoint": { "description": "HTTP endpoint used to check that a custom runtime app is ready to receive traffic.", "type": "string" }, "region": { "description": "Region to deploy to. Defaults to an automatically selected region.", "type": "string" }, "replicaConcurrency": { "description": "Maximum concurrent requests per replica. Defaults to 100 for CPU apps and 1 for GPU apps.", "type": "integer" }, "responseGracePeriodSeconds": { "description": "Grace period in seconds for in-flight requests when a replica stops. Range: 16-43200. Default: 900.", "type": "integer" }, "rollOutDurationSeconds": { "description": "Duration in seconds over which to roll out a new version. Range: 0-21600.", "type": "integer" }, "runtime": { "description": "App runtime. Valid values: cortex, custom. Default: cortex.", "type": "string" }, "scalingBuffer": { "description": "Number of extra replicas to keep available beyond current demand. Must be \u003e= 0.", "type": "integer" }, "scalingMetric": { "description": "Metric used for autoscaling. Valid values: cpu_utilization, memory_utilization, requests_per_second, concurrency_utilization. Default: concurrency_utilization.", "type": "string" }, "scalingTarget": { "description": "Target value for the scaling metric. Must be \u003e 0. Default: 100.", "type": "integer" }, "useUv": { "description": "Use uv for Python package installation.", "type": "boolean" } }, "required": ["name", "cliVersion", "githubRepo"], "type": "object" } } } } } }, "/v2/projects/{project_id}/apps/{app_id}": { "delete": { "operationId": "deleteApp", "summary": "Delete App", "description": "Remove a specific app from a project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A plain text confirmation message that the app was deleted." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Apps"] }, "get": { "operationId": "getApp", "summary": "Get App", "description": "Retrieve details for a specific app in a project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full configuration and status details of the requested app.", "content": { "application/json": { "schema": { "properties": { "baseImage": { "description": "Base Docker image the app is built from.", "type": "string" }, "cerebriumVersion": { "description": "Version of the client used to deploy the app.", "type": "string" }, "computeTier": { "description": "Compute tier of the app, interruptible or protected.", "type": "string" }, "cooldownPeriodSeconds": { "description": "Cooldown period in seconds before an idle replica scales down, as a string value.", "type": "string" }, "costPerSecondCents": { "description": "Estimated cost per second in US cents while a replica is running, as a string value.", "type": "string" }, "cpu": { "description": "Number of CPU cores allocated, as a string value.", "type": "string" }, "createdAt": { "description": "Timestamp when the app was created.", "type": "string" }, "deploymentInitializationTimeout": { "description": "Maximum time in seconds to wait for a deployment to initialize, as a string value.", "type": "string" }, "disableAuth": { "description": "Whether authentication is disabled on the app endpoint.", "type": "boolean" }, "entrypoint": { "description": "Command used to start a custom runtime app, as a list of strings.", "type": "array" }, "errorMessage": { "description": "Error message from the most recent failure, if any.", "type": "string" }, "evaluationIntervalSeconds": { "description": "Interval in seconds between autoscaling evaluations, as a string value.", "type": "string" }, "gpuCount": { "description": "Number of GPUs allocated, as a string value.", "type": "string" }, "hardware": { "description": "Compute type the app runs on.", "type": "string" }, "hardwareProvider": { "description": "Cloud provider the app is deployed on.", "type": "string" }, "healthcheckEndpoint": { "description": "HTTP endpoint used to check that the app is healthy.", "type": "string" }, "id": { "description": "Unique identifier of the app.", "type": "string" }, "internalEndpoint": { "description": "Base URL for invoking the app.", "type": "string" }, "lastBuildStatus": { "description": "Status of the most recent build.", "type": "string" }, "latestBuildId": { "description": "ID of the most recent build.", "type": "string" }, "latestCreatedBuildId": { "description": "ID of the most recently created build.", "type": "string" }, "latestReadyBuildId": { "description": "ID of the most recent build that reached the ready state.", "type": "string" }, "loadBalancingAlgorithm": { "description": "Load balancing algorithm used by the app.", "type": "string" }, "maxReplicaCount": { "description": "Maximum number of replicas, as a string value.", "type": "string" }, "memory": { "description": "Memory allocation in GB, as a string value.", "type": "string" }, "minReplicaCount": { "description": "Minimum number of replicas, as a string value.", "type": "string" }, "name": { "description": "Name of the app.", "type": "string" }, "port": { "description": "Port the app listens on.", "type": "integer" }, "projectId": { "description": "ID of the project the app belongs to.", "type": "string" }, "pythonVersion": { "description": "Python version the app uses.", "type": "string" }, "readycheckEndpoint": { "description": "HTTP endpoint used to check that the app is ready to receive traffic.", "type": "string" }, "region": { "description": "Region the app is deployed in.", "type": "string" }, "replicaConcurrency": { "description": "Maximum concurrent requests per replica, as a string value.", "type": "string" }, "responseGracePeriodSeconds": { "description": "Grace period in seconds for in-flight requests when a replica stops, as a string value.", "type": "string" }, "rollOutDurationSeconds": { "description": "Duration in seconds over which a new version is rolled out, as a string value.", "type": "string" }, "runtime": { "description": "App runtime, cortex or custom.", "type": "string" }, "scalingBuffer": { "description": "Number of extra replicas kept available beyond current demand, as a string value.", "type": "string" }, "scalingMetric": { "description": "Metric used for autoscaling.", "type": "string" }, "scalingTarget": { "description": "Target value for the scaling metric, as a string value.", "type": "string" }, "status": { "description": "Current status of the app.", "type": "string" }, "updatedAt": { "description": "Timestamp when the app was last updated.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Apps"] }, "patch": { "operationId": "updateApp", "summary": "Modify App", "description": "Update the configuration or metadata of a specific app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirmation that the app update was accepted.", "content": { "application/json": { "schema": { "properties": { "app": { "description": "The app configuration after the update is applied, including appId, projectId, hardware, cpu, memory, gpuCount, scaling settings, runtime settings, and region.", "type": "object" }, "message": { "description": "Status message for the update.", "type": "string" }, "self": { "description": "URL of the updated app resource.", "type": "string" }, "success": { "description": "Whether the update request was accepted.", "type": "boolean" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Apps"], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cerebrium_toml": { "description": "Verbatim contents of the cerebrium.toml configuration file.", "type": "string" }, "compute": { "description": "Compute type(s) for the app, in priority order. A single value or a list of up to 5. Valid values: ADA_L4, ADA_L40, AMPERE_A10, AMPERE_A100_40GB, AMPERE_A100_80GB, HOPPER_H100, HOPPER_H200, BLACKWELL_B200, BLACKWELL_RTX6000, CPU, INF2, TRN1, TURING_T4.", "type": "array" }, "computeTier": { "description": "Compute tier for the app. Valid values: interruptible, protected.", "type": "string" }, "containerRuntime": { "description": "Container runtime version. Valid values: v1, v2.", "type": "string" }, "cooldownPeriodSeconds": { "description": "Cooldown period in seconds before an idle replica scales down. Range: 1-3600.", "type": "integer" }, "cpu": { "description": "Number of CPU cores to allocate, as a string value.", "type": "string" }, "deploymentInitializationTimeout": { "description": "Maximum time in seconds to wait for a deployment to initialize. Range: 60-7200 for global builds, 60-900 for region-pinned builds.", "type": "integer" }, "disableAuth": { "description": "Disable authentication on the app endpoint.", "type": "boolean" }, "entrypoint": { "description": "Command to start a custom runtime app, as a list of strings.", "type": "array" }, "evaluationIntervalSeconds": { "description": "Interval in seconds between autoscaling evaluations. Range: 6-300.", "type": "integer" }, "gpuCount": { "description": "Number of GPUs allocated. Range: 0-8.", "type": "integer" }, "healthcheckEndpoint": { "description": "HTTP endpoint used to check that a custom runtime app is healthy.", "type": "string" }, "loadBalancingAlgorithm": { "description": "Load balancing algorithm. Valid values: round-robin, first-available, min-connections, random-choice-2.", "type": "string" }, "maxReplicaCount": { "description": "Maximum number of replicas. Range: 1-2000.", "type": "integer" }, "memory": { "description": "Memory allocation in GB, as a string value.", "type": "string" }, "minReplicaCount": { "description": "Minimum number of replicas. Range: 0-2000.", "type": "integer" }, "port": { "description": "Port the app listens on. Range: 0-65535.", "type": "integer" }, "readycheckEndpoint": { "description": "HTTP endpoint used to check that a custom runtime app is ready to receive traffic.", "type": "string" }, "replicaConcurrency": { "description": "Maximum concurrent requests per replica. Range: 1-1000000.", "type": "integer" }, "responseGracePeriodSeconds": { "description": "Grace period in seconds for in-flight requests when a replica stops. Range: 16-43200.", "type": "integer" }, "rollOutDurationSeconds": { "description": "Duration in seconds over which to roll out a new version. Range: 1-21600.", "type": "integer" }, "runtime": { "description": "App runtime. Valid values: cortex, custom.", "type": "string" }, "scalingBuffer": { "description": "Number of extra replicas to keep available beyond current demand. Must be \u003e= 0.", "type": "integer" }, "scalingMetric": { "description": "Metric used for autoscaling. Valid values: cpu_utilization, memory_utilization, requests_per_second, concurrency_utilization.", "type": "string" }, "scalingTarget": { "description": "Target value for the scaling metric. Must be \u003e 0.", "type": "integer" } }, "type": "object" } } } } } }, "/v2/projects/{project_id}/apps/{app_id}/active-revision": { "get": { "operationId": "getAppActiveRevision", "summary": "Get Active Revision", "description": "Retrieve the active revision for a specific app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Details of the app's currently active revision. An empty object is returned when the app has no active deployment.", "content": { "application/json": { "schema": { "properties": { "latestCreatedRevisionName": { "description": "Name of the most recently created revision.", "type": "string" }, "latestReadyRevisionName": { "description": "Name of the most recent revision that is ready to serve traffic.", "type": "string" }, "maxReplicaCount": { "description": "Maximum number of replicas, as a string value.", "type": "string" }, "minReplicaCount": { "description": "Minimum number of replicas, as a string value.", "type": "string" }, "replicaConcurrency": { "description": "Maximum concurrent requests per replica, as a string value.", "type": "string" }, "scaleBuffer": { "description": "Number of extra replicas kept available beyond current demand, as a string value.", "type": "string" }, "scalingMetric": { "description": "Metric used for autoscaling.", "type": "string" }, "scalingTarget": { "description": "Target value for the scaling metric, as a string value.", "type": "string" }, "scalingTargetUtilization": { "description": "Target utilization percentage for scaling, as a string value.", "type": "string" }, "traffic": { "description": "Traffic split across revisions. Each item includes the revision name and the percentage of traffic it receives.", "type": "array" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Apps"] } }, "/v2/projects/{project_id}/apps/{app_id}/builds": { "get": { "operationId": "listBuilds", "summary": "List Builds", "description": "Retrieve a list of builds for a specific app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of builds to return.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Only return builds created before this timestamp. Use the createdAt of the last build in the previous page to paginate.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of builds for the app.", "content": { "application/json": { "schema": { "properties": { "items": { "description": "Builds ordered by creation time. Each item includes id, modelId, projectId, name, status, type, createdAt, updatedAt, buildTimeMs, initTimeMs, cliVersion, cerebriumVersion, cpu (number), memory (number), gpuCount (integer), hardware, region, dockerBaseImageUrl, pythonVersion, revisionName, runtimeVersion, imageSizeBytes (integer), zipSizeBytes (integer), and scaleOnly (boolean, omitted when not set) fields.", "type": "array" }, "nextToken": { "description": "Timestamp to pass as offset to retrieve the next page. Empty when there are no more results.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Builds"] } }, "/v2/projects/{project_id}/apps/{app_id}/builds/{build_id}": { "delete": { "operationId": "cancelBuild", "summary": "Cancel Build", "description": "Cancel an ongoing build for an app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "build_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A plain text confirmation message that the build was cancelled." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Builds"] }, "get": { "operationId": "getBuild", "summary": "Get Build", "description": "Retrieve details for a specific build.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "build_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full configuration and status details of the requested build.", "content": { "application/json": { "schema": { "properties": { "buildTimeMs": { "description": "Time taken to build, in milliseconds, as a string value.", "type": "string" }, "cerebriumVersion": { "description": "Version of the client used at deployment time.", "type": "string" }, "checkpointing": { "description": "Whether checkpointing is enabled for the build.", "type": "boolean" }, "cliVersion": { "description": "Version of the client that created the build.", "type": "string" }, "computeTier": { "description": "Compute tier of the build, interruptible or protected. Omitted when not set.", "type": "string" }, "containerRuntime": { "description": "Container runtime version. Omitted when not set.", "type": "string" }, "cooldownPeriod": { "description": "Cooldown period in seconds before an idle replica scales down.", "type": "integer" }, "cpu": { "description": "Number of CPU cores allocated.", "type": "number" }, "createdAt": { "description": "Timestamp when the build was created.", "type": "string" }, "createdByUserEmail": { "description": "Email address of the user who created the build.", "type": "string" }, "createdByUserIp": { "description": "IP address the build was created from.", "type": "string" }, "deadlineSeconds": { "description": "Maximum run duration in seconds, if set.", "type": "integer" }, "deploymentInitializationTimeout": { "description": "Maximum time in seconds to wait for the deployment to initialize.", "type": "integer" }, "disableAuth": { "description": "Whether authentication is disabled on the app endpoint.", "type": "boolean" }, "dockerBaseImageUrl": { "description": "Base Docker image used for the build.", "type": "string" }, "dockerfilePath": { "description": "Path to the Dockerfile used, if any.", "type": "string" }, "entrypoint": { "description": "Command used to start a custom runtime app, as a list of strings.", "type": "array" }, "evaluationIntervalSeconds": { "description": "Interval in seconds between autoscaling evaluations.", "type": "integer" }, "finalState": { "description": "Configuration after the update, for update builds. Omitted when not set.", "type": "object" }, "gpuCount": { "description": "Number of GPUs allocated.", "type": "integer" }, "hardware": { "description": "Compute type the build targets.", "type": "string" }, "hardwareFallbacks": { "description": "Fallback compute types, in priority order. Omitted when not set.", "type": "array" }, "hardwareProvider": { "description": "Cloud provider the build targets.", "type": "string" }, "hasDockerAuth": { "description": "Whether private registry credentials were provided.", "type": "boolean" }, "healthcheckEndpoint": { "description": "HTTP endpoint used to check that the app is healthy.", "type": "string" }, "id": { "description": "Unique identifier of the build.", "type": "string" }, "imageSizeBytes": { "description": "Size of the built image in bytes.", "type": "integer" }, "initError": { "description": "Error message from deployment initialization, if any. Omitted when not set.", "type": "string" }, "initTimeMs": { "description": "Time taken to initialize the deployment, in milliseconds, as a string value.", "type": "string" }, "loadBalancingAlgorithm": { "description": "Load balancing algorithm used by the app.", "type": "string" }, "maxReplicaCount": { "description": "Maximum number of replicas.", "type": "integer" }, "memory": { "description": "Memory allocation in GB.", "type": "number" }, "minReplicaCount": { "description": "Minimum number of replicas.", "type": "integer" }, "modelId": { "description": "ID of the app the build belongs to.", "type": "string" }, "name": { "description": "Name of the app.", "type": "string" }, "originalState": { "description": "Configuration before the update, for update builds. Omitted when not set.", "type": "object" }, "port": { "description": "Port the app listens on.", "type": "integer" }, "projectId": { "description": "ID of the project the build belongs to.", "type": "string" }, "pythonVersion": { "description": "Python version used for the build.", "type": "string" }, "readycheckEndpoint": { "description": "HTTP endpoint used to check that the app is ready to receive traffic.", "type": "string" }, "region": { "description": "Region the build targets.", "type": "string" }, "replicaConcurrency": { "description": "Maximum concurrent requests per replica.", "type": "integer" }, "responseGracePeriodSeconds": { "description": "Grace period in seconds for in-flight requests when a replica stops.", "type": "integer" }, "revisionName": { "description": "Name of the revision created by this build.", "type": "string" }, "rollOutDurationSeconds": { "description": "Duration in seconds over which the new version is rolled out.", "type": "integer" }, "runtime": { "description": "App runtime, cortex or custom.", "type": "string" }, "runtimeVersion": { "description": "Version of the app runtime.", "type": "string" }, "scaleOnly": { "description": "Whether the update only changed scaling parameters, so the app was updated in place without a redeployment. Omitted when not set.", "type": "boolean" }, "scalingBuffer": { "description": "Number of extra replicas kept available beyond current demand.", "type": "integer" }, "scalingMetric": { "description": "Metric used for autoscaling.", "type": "string" }, "scalingTarget": { "description": "Target value for the scaling metric.", "type": "integer" }, "status": { "description": "Current status of the build.", "type": "string" }, "type": { "description": "Type of the build.", "type": "string" }, "updateInput": { "description": "Configuration changes requested, for update builds. Omitted when not set.", "type": "object" }, "updatedAt": { "description": "Timestamp when the build was last updated.", "type": "string" }, "useUv": { "description": "Whether uv is used for Python package installation. Omitted when not set.", "type": "boolean" }, "zipSizeBytes": { "description": "Size of the uploaded source archive in bytes.", "type": "integer" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Builds"] } }, "/v2/projects/{project_id}/apps/{app_id}/builds/{build_id}/download": { "get": { "operationId": "downloadBuild", "summary": "Download Build", "description": "Download the build ZIP file for a specific build.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "build_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "filename", "in": "query", "required": false, "description": "Path of a specific file within the build archive. When set, the response includes the byte range of that file so it can be fetched with a range request.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A presigned URL for downloading the build archive.", "content": { "application/json": { "schema": { "properties": { "compressed_size": { "description": "Compressed size in bytes of the requested file. Only present when filename is provided.", "type": "integer" }, "compression_method": { "description": "Compression method identifier of the requested file. Only present when filename is provided.", "type": "integer" }, "data_offset": { "description": "Byte offset of the requested file's data within the archive. Only present when filename is provided.", "type": "integer" }, "download_url": { "description": "Presigned download URL for the build ZIP archive.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Builds"] } }, "/v2/projects/{project_id}/apps/{app_id}/builds/{build_id}/image/files": { "get": { "operationId": "getImageFiles", "summary": "List Image Files", "description": "Browse files inside a built container image at a specified path.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "build_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "required": false, "description": "Path inside the image to list. Defaults to the image root.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Files inside the built container image at the requested path.", "content": { "application/json": { "schema": { "properties": { "files": { "description": "Directory entries at the requested path. Each item has inode (string), name (string), type (string), size (integer), permissions (string), and mtime (integer) fields.", "type": "array" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Builds"] } }, "/v2/projects/{project_id}/apps/{app_id}/builds/{build_id}/logs": { "get": { "operationId": "listAppBuildLogs", "summary": "List Build Logs", "description": "Retrieve logs for a specific build of an app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "build_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Build status and log lines for the requested build.", "content": { "application/json": { "schema": { "properties": { "app_id": { "description": "ID of the app.", "type": "string" }, "build_id": { "description": "ID of the build.", "type": "string" }, "logs": { "description": "Build log entries. Each item has createdAt (string), id (string), and log (string) fields.", "type": "array" }, "project_id": { "description": "ID of the project.", "type": "string" }, "status": { "description": "Current status of the build.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Builds"] } }, "/v2/projects/{project_id}/apps/{app_id}/builds/{build_id}/rebuild": { "post": { "operationId": "rebuildBuild", "summary": "Rebuild", "description": "Trigger a new build using the same source as an existing build.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "build_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "redeploy_only", "in": "query", "required": false, "description": "Set to true to redeploy the existing built image without rebuilding.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Confirmation that the rebuild or redeploy was triggered.", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Result of the request, success when the rebuild was triggered.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Builds"] } }, "/v2/projects/{project_id}/apps/{app_id}/builds/{build_id}/zip-contents": { "get": { "operationId": "getBuildZipContents", "summary": "Get Build Zip Contents", "description": "List the files contained in a build's uploaded ZIP archive.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "build_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A tree of the files contained in the build's uploaded ZIP archive.", "content": { "application/json": { "schema": { "properties": { "id": { "description": "ID of the build.", "type": "string" }, "zipFiles": { "description": "Nested tree of directories and files in the archive. Each file entry has size (integer), type (string), and lastModified (string) fields.", "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Builds"] } }, "/v2/projects/{project_id}/apps/{app_id}/containers": { "get": { "operationId": "listAppRecentContainers", "summary": "List Recent Containers", "description": "Retrieve a list of recent containers for a specific app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recently active containers for the app.", "content": { "application/json": { "schema": { "items": { "properties": { "appId": { "description": "ID of the app the container belongs to.", "type": "string" }, "buildId": { "description": "ID of the build the container was created from.", "type": "string" }, "containerId": { "description": "Unique identifier of the container.", "type": "string" }, "containerIp": { "description": "IP address of the container.", "type": "string" }, "containerRestartCount": { "description": "Number of times the container has restarted.", "type": "integer" }, "containerRunningTimeMs": { "description": "Total running time of the container in milliseconds.", "type": "integer" }, "containerStartTimestamp": { "description": "Timestamp when the container started.", "type": "string" }, "containerState": { "description": "Current state of the container.", "type": "string" }, "containerTerminationTimestamp": { "description": "Timestamp when the container terminated, if it has.", "type": "string" }, "hardwareProvider": { "description": "Cloud provider the container is running on.", "type": "string" }, "hostIp": { "description": "IP address of the host running the container.", "type": "string" }, "isTerminating": { "description": "Whether the container is currently shutting down.", "type": "boolean" }, "projectId": { "description": "ID of the project the container belongs to.", "type": "string" }, "region": { "description": "Region the container is running in.", "type": "string" }, "timestamp": { "description": "Timestamp of the most recent status report for the container.", "type": "string" } }, "type": "object" }, "type": "array" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Containers"] } }, "/v2/projects/{project_id}/apps/{app_id}/containers/{container_id}": { "delete": { "operationId": "stopAppContainer", "summary": "Stop Container", "description": "Stop a specific container.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "container_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "force", "in": "query", "required": false, "description": "Set to true to force stop the container immediately, without a grace period.", "schema": { "type": "boolean" } }, { "name": "grace_period_seconds", "in": "query", "required": false, "description": "Seconds to wait after SIGTERM before the container is SIGKILLed. Defaults to 10, must be between 0 and 3599. Ignored when force is true.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "A plain text confirmation message that the container is being stopped." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Containers"] }, "get": { "operationId": "getAppContainer", "summary": "Get Container", "description": "Retrieve details for a specific container.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "container_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lifecycle and status details of the requested container.", "content": { "application/json": { "schema": { "properties": { "appId": { "description": "ID of the app the container belongs to.", "type": "string" }, "buildId": { "description": "ID of the build the container was created from.", "type": "string" }, "checkpointSizeBytes": { "description": "Size of the memory checkpoint this container saved or restored from, in bytes. Omitted when the container has no checkpoint.", "type": "integer" }, "containerIp": { "description": "IP address of the container.", "type": "string" }, "containerRestartExitCode": { "description": "Exit code from the container's last restart. Omitted when not available.", "type": "integer" }, "containerRestartMessage": { "description": "Message associated with the container's last restart. Omitted when not available.", "type": "string" }, "containerRestartReason": { "description": "Reason for the container's last restart. Omitted when not available.", "type": "string" }, "containerRestartSignal": { "description": "Signal that caused the container's last restart. Omitted when not available.", "type": "integer" }, "containerTerminationExitCode": { "description": "Exit code from the container's termination. Omitted when not available.", "type": "integer" }, "containerTerminationMessage": { "description": "Message associated with the container's termination. Omitted when not available.", "type": "string" }, "containerTerminationReason": { "description": "Reason the container terminated. Omitted when not terminated.", "type": "string" }, "containerTerminationSignal": { "description": "Signal that terminated the container. Omitted when not available.", "type": "integer" }, "endedAt": { "description": "Timestamp when the container ended, in RFC3339 format. Empty while running.", "type": "string" }, "hardwareProvider": { "description": "Cloud provider the container is running on.", "type": "string" }, "hostIp": { "description": "IP address of the host running the container.", "type": "string" }, "isTerminating": { "description": "Whether the container is currently shutting down.", "type": "boolean" }, "podDeletionTimestamp": { "description": "Timestamp when the container was marked for deletion. Omitted when not set.", "type": "string" }, "projectId": { "description": "ID of the project the container belongs to.", "type": "string" }, "region": { "description": "Region the container is running in.", "type": "string" }, "requestedAt": { "description": "Timestamp when the container was requested, in RFC3339 format.", "type": "string" }, "restartCount": { "description": "Number of times the container has restarted.", "type": "integer" }, "restoreDurationMs": { "description": "Time from checkpoint files being ready to the restored process's first HTTP call, in milliseconds. Omitted when the container was not restored from a checkpoint.", "type": "integer" }, "startedAt": { "description": "Timestamp when the container started, in RFC3339 format.", "type": "string" }, "state": { "description": "Current state of the container.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Containers"] } }, "/v2/projects/{project_id}/apps/{app_id}/cost": { "get": { "operationId": "getAppCost", "summary": "Get App Cost", "description": "Retrieve cost breakdown for a specific app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "month", "in": "query", "required": false, "description": "Billing month to retrieve costs for. Valid values: current, previous. Default: current.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Daily cost metrics for the app over the selected month.", "content": { "application/json": { "schema": { "properties": { "cost_totals": { "description": "Costs summed over the period, with the same fields as each costs entry.", "type": "object" }, "costs": { "description": "Costs per interval, keyed by date. Each value has total_cost_cents, cpu_cost_cents, memory_cost_cents, gpu_cost_cents, unique_container_count, and total_running_time_ms fields.", "type": "object" }, "end_date": { "description": "End of the reporting period, in RFC3339 format.", "type": "string" }, "interval": { "description": "Time bucket size for the breakdown.", "type": "string" }, "start_date": { "description": "Start of the reporting period, in RFC3339 format.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Apps"] } }, "/v2/projects/{project_id}/apps/{app_id}/dashboard-metrics": { "get": { "operationId": "getAppDashboardMetrics", "summary": "Get an app's request and cost breakdown over time", "description": "How much traffic an app served and what it cost to run, over a chosen period. Requests are counted per time bucket and split by response status (2xx/4xx/5xx, normal and error WebSocket closes, and anything else); cost is split across GPU, CPU and memory. Every bucket in the period is returned, zero-filled where there was no activity, so the series can be charted without gap handling.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "month", "in": "query", "required": false, "description": "Report on a whole billing month, in UTC. One of current or previous; defaults to current. Ignored when start and end are supplied. A billing month is longer than the minute and hour intervals allow, so those require start and end.", "schema": { "type": "string" } }, { "name": "start", "in": "query", "required": false, "description": "Start of an arbitrary period, RFC3339. Takes precedence over month, and must be sent with end. Cannot be more than 180 days ago.", "schema": { "type": "string" } }, { "name": "end", "in": "query", "required": false, "description": "End of an arbitrary period, RFC3339. Takes precedence over month, and must be sent with start.", "schema": { "type": "string" } }, { "name": "interval", "in": "query", "required": false, "description": "Bucket size to group the series by: minute, hour, day (default) or month. Each caps how long a period you can ask for — 6 hours for minute, 7 days for hour, 180 days for day and month — and a longer one is rejected with a 400. Because a billing month is longer than the minute and hour caps, those intervals must be paired with start and end rather than month.", "schema": { "type": "string" } }, { "name": "tz", "in": "query", "required": false, "description": "IANA timezone the buckets fall in, e.g. America/New_York. Defaults to UTC. Month and day buckets start at midnight in this zone, and minute and hour buckets on its minute or hour — which is not the UTC hour in zones offset by 30 or 45 minutes, such as Asia/Kolkata.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Two zero-filled time series covering the whole period — requests by response status and cost by resource — plus a total for each. Both series are objects keyed by bucket start, in ascending key order.", "content": { "application/json": { "schema": { "properties": { "cost_totals": { "description": "Spend for the whole period, same fields as a costs entry. Equal to the sum of the buckets.", "type": "object" }, "costs": { "description": "Spend per bucket in fractional cents, split into gpu_cost_cents, cpu_cost_cents and memory_cost_cents alongside total_cost_cents, with total_running_time_ms for the container time that spend covers. Note the key format differs from requests: month and day buckets are keyed YYYY-MM-DD (a month by its first day), minute and hour buckets RFC3339. unique_container_count is not populated.", "type": "object" }, "end_date": { "description": "End of the period actually reported on, RFC3339. Echoes end, or the last moment of the billing month when month was used.", "type": "string" }, "interval": { "description": "Bucket size the series were grouped by, echoing the interval requested: minute, hour, day or month.", "type": "string" }, "request_totals": { "description": "Request counts for the whole period, same fields as a requests entry. Equal to the sum of the buckets.", "type": "object" }, "requests": { "description": "Request counts per bucket, keyed by bucket start in RFC3339. Month and day buckets fall at midnight in tz; minute and hour buckets are instants expressed in UTC. Each value splits total into 2xx, 4xx, 5xx, websocket_success (close codes 1000-1001), websocket_error (1002-1999), and other (anything outside those ranges, including no status).", "type": "object" }, "start_date": { "description": "Start of the period actually reported on, RFC3339. Echoes start, or the first moment of the billing month when month was used.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Apps"] } }, "/v2/projects/{project_id}/apps/{app_id}/logs": { "get": { "operationId": "getAppLogs", "summary": "Get App Logs", "description": "Retrieve logs for a specific app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "beforeDate", "in": "query", "required": false, "description": "Retrieve logs before a specific date, in RFC3339 format. A value at or before retentionStart returns an empty page.", "schema": { "type": "string" } }, { "name": "afterDate", "in": "query", "required": false, "description": "Retrieve logs after a specific date, in RFC3339 format. Raised to retentionStart when earlier or omitted.", "schema": { "type": "string" } }, { "name": "container", "in": "query", "required": false, "description": "Retrieve logs for a specific container.", "schema": { "type": "string" } }, { "name": "runId", "in": "query", "required": false, "description": "Retrieve logs for a specific run.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Only return log lines containing this search term.", "schema": { "type": "string" } }, { "name": "stream", "in": "query", "required": false, "description": "Filter by output stream. Valid values: stdout, stderr.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "Set to forward to page forward in time. Defaults to backward.", "schema": { "type": "string" } }, { "name": "nextToken", "in": "query", "required": false, "description": "Pagination token from a previous response.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "required": false, "description": "Number of log lines to return per page. Maximum: 1000. Default: 200.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "A page of log lines for the app.", "content": { "application/json": { "schema": { "properties": { "hasMore": { "description": "Whether more log lines are available.", "type": "boolean" }, "logs": { "description": "Log entries. Each item has appId, containerId, containerName, lineNumber (integer), logLine, logId, projectId, stream, timestamp, and runId fields.", "type": "array" }, "nextPageToken": { "description": "Token to pass as nextToken to retrieve the next page. Omitted when there are no more results.", "type": "string" }, "retentionDays": { "description": "How many days of logs the project retains, the lower of its setting and its plan cap.", "type": "integer" }, "retentionStart": { "description": "Earliest instant logs can be retrieved from, in RFC3339 format. No log line before it is returned.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Apps"] } }, "/v2/projects/{project_id}/apps/{app_id}/metrics/response-time": { "get": { "operationId": "getAppResponseTimeMetrics", "summary": "Get Response Time Metrics", "description": "Retrieve end-to-end response time percentiles for an app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "start", "in": "query", "required": true, "description": "Start of the time range as an RFC 3339 timestamp", "schema": { "type": "string" } }, { "name": "end", "in": "query", "required": true, "description": "End of the time range as an RFC 3339 timestamp (must not be before start)", "schema": { "type": "string" } }, { "name": "container_id", "in": "query", "required": false, "description": "Filter metrics to a specific container", "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "required": false, "description": "Data resolution ('medium' or 'high' for more data points; defaults to standard)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response time percentile and distribution metrics for the app over the requested time range.", "content": { "application/json": { "schema": { "properties": { "data": { "description": "Metrics payload containing 'percentiles' (object with p50, p90, p95, p99 response times in milliseconds), 'distribution' (object mapping latency thresholds such as '1ms' through '1hr' to the estimated cumulative percentage of requests completing within each), 'total_requests' (total request count in the range), and 'start_date' / 'end_date' (RFC 3339 range bounds).", "type": "object" }, "status": { "description": "Result status of the metrics query ('success' when data was retrieved).", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Metrics"] } }, "/v2/projects/{project_id}/apps/{app_id}/metrics/run-execution-time": { "get": { "operationId": "getAppRunExecutionTimeMetrics", "summary": "Get Execution Time Metrics", "description": "Retrieve run execution time percentiles for an app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "start", "in": "query", "required": true, "description": "Start of the time range as an RFC 3339 timestamp", "schema": { "type": "string" } }, { "name": "end", "in": "query", "required": true, "description": "End of the time range as an RFC 3339 timestamp (must not be before start)", "schema": { "type": "string" } }, { "name": "container_id", "in": "query", "required": false, "description": "Filter metrics to a specific container", "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "required": false, "description": "Data resolution ('medium' or 'high' for more data points; defaults to standard)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run execution time percentile metrics for the app as a time series over the requested time range.", "content": { "application/json": { "schema": { "properties": { "data": { "description": "Metrics payload containing 'time_series' (array of datapoints with 'timestamp' in Unix seconds and 'p50' / 'p90' / 'p99' execution times in seconds), 'total_runs' (total run count in the range), and 'start_date' / 'end_date' (RFC 3339 range bounds).", "type": "object" }, "status": { "description": "Result status of the metrics query ('success' when data was retrieved).", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Metrics"] } }, "/v2/projects/{project_id}/apps/{app_id}/metrics/startup-time": { "get": { "operationId": "getAppStartupTimeMetrics", "summary": "Get Startup Time Metrics", "description": "Retrieve cold start and container startup time metrics for an app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "start", "in": "query", "required": true, "description": "Start of the time range as an RFC 3339 timestamp", "schema": { "type": "string" } }, { "name": "end", "in": "query", "required": true, "description": "End of the time range as an RFC 3339 timestamp (must not be before start)", "schema": { "type": "string" } }, { "name": "container_id", "in": "query", "required": false, "description": "Filter metrics to a specific container", "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "required": false, "description": "Data resolution ('medium' or 'high' for more data points; defaults to standard)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Startup time percentile metrics for the app as a time series over the requested time range.", "content": { "application/json": { "schema": { "properties": { "data": { "description": "Metrics payload containing 'time_series' (array of datapoints with 'timestamp' in Unix seconds and 'p50' / 'p90' / 'p99' startup times in seconds), 'total_runs' (total run count in the range), and 'start_date' / 'end_date' (RFC 3339 range bounds).", "type": "object" }, "status": { "description": "Result status of the metrics query ('success' when data was retrieved).", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Metrics"] } }, "/v2/projects/{project_id}/apps/{app_id}/resource-metrics": { "get": { "operationId": "getAppResourceMetrics", "summary": "Get App Resource Metrics", "description": "Retrieve CPU, memory, and GPU utilization metrics for an app over a time period.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "start", "in": "query", "required": true, "description": "Start of the time range, in RFC3339 format.", "schema": { "type": "string" } }, { "name": "end", "in": "query", "required": false, "description": "End of the time range, in RFC3339 format. Defaults to the current time.", "schema": { "type": "string" } }, { "name": "container_id", "in": "query", "required": false, "description": "Return metrics for a specific container instead of the whole app.", "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "required": false, "description": "Granularity of the returned data points. Valid values: medium, high. Defaults to standard granularity.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Time series of resource utilization for the app or a specific container.", "content": { "application/json": { "schema": { "properties": { "containers": { "description": "Container count chart data, with timestamps (array of integers) and series (array of objects with name and data fields).", "type": "object" }, "cpu": { "description": "CPU utilization chart data, with timestamps (array of integers) and series (array of objects with name and data fields).", "type": "object" }, "gpu": { "description": "GPU utilization chart data, with timestamps (array of integers) and series (array of objects with name and data fields).", "type": "object" }, "memory": { "description": "Memory utilization chart data, with timestamps (array of integers) and series (array of objects with name and data fields).", "type": "object" }, "requests": { "description": "Request rate chart data, with timestamps (array of integers) and series (array of objects with name and data fields).", "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Apps"] } }, "/v2/projects/{project_id}/apps/{app_id}/runs": { "get": { "operationId": "listAppRuns", "summary": "List Runs", "description": "Retrieve a list of runs for a specific app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter runs by status.", "schema": { "type": "string" } }, { "name": "runId", "in": "query", "required": false, "description": "Retrieve a specific run by its ID.", "schema": { "type": "string" } }, { "name": "statusCode", "in": "query", "required": false, "description": "Filter runs by HTTP status code. Digits pin their position and the first 'x' frees the rest, so 201 is exactly 201, 20 is 200-209 and 4xx is 400-499.", "schema": { "type": "string" } }, { "name": "containerId", "in": "query", "required": false, "description": "Filter runs by the container that executed them.", "schema": { "type": "string" } }, { "name": "asyncOnly", "in": "query", "required": false, "description": "Set to true to only return asynchronous runs.", "schema": { "type": "boolean" } }, { "name": "websocketOnly", "in": "query", "required": false, "description": "Set to true to only return websocket runs.", "schema": { "type": "boolean" } }, { "name": "minQueueTimeMs", "in": "query", "required": false, "description": "Only return runs queued for at least this many milliseconds.", "schema": { "type": "integer" } }, { "name": "maxQueueTimeMs", "in": "query", "required": false, "description": "Only return runs queued for at most this many milliseconds.", "schema": { "type": "integer" } }, { "name": "minContainerQueueTimeMs", "in": "query", "required": false, "description": "Only return runs that waited at least this many milliseconds for a container.", "schema": { "type": "integer" } }, { "name": "minResponseTimeMs", "in": "query", "required": false, "description": "Only return runs with a response time of at least this many milliseconds.", "schema": { "type": "integer" } }, { "name": "maxResponseTimeMs", "in": "query", "required": false, "description": "Only return runs with a response time of at most this many milliseconds.", "schema": { "type": "integer" } }, { "name": "afterDate", "in": "query", "required": false, "description": "Only return runs created after this timestamp, in RFC3339 format.", "schema": { "type": "string" } }, { "name": "beforeDate", "in": "query", "required": false, "description": "Only return runs created before this timestamp, in RFC3339 format.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "Filter runs by region.", "schema": { "type": "string" } }, { "name": "nextToken", "in": "query", "required": false, "description": "Pagination token from a previous response.", "schema": { "type": "string" } }, { "name": "includeEphemeral", "in": "query", "required": false, "description": "Include runs from ephemeral apps. Set to true to include them.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A page of runs matching the filters.", "content": { "application/json": { "schema": { "properties": { "hitMaxLoops": { "description": "Whether the query stopped early before scanning all matching runs.", "type": "boolean" }, "items": { "description": "Runs ordered by creation time. Each item includes id, modelId, projectId, status, statusCode (integer), async (boolean), websocket (boolean), createdAt, updatedAt, completedAt, containerId, containerStartedAt, functionName, method, region, timing fields in milliseconds (queueTimeMs, runtimeMs, responseTimeMs, activatorQueueTimeMs, containerQueueTimeMs, totalQueueTimeMs, executionTimeMs, totalResponseTimeMs), and for ephemeral runs the run configuration (ephemeral, command, hardware, cpu, memory, gpuCount, createdByUserId).", "type": "array" }, "nextToken": { "description": "Pagination token to pass as nextToken to retrieve the next page. Empty when there are no more results.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Runs"] } }, "/v2/projects/{project_id}/apps/{app_id}/runs/charts": { "get": { "operationId": "listAppRunsCharts", "summary": "Get Runs Chart Data", "description": "Retrieve aggregated run data optimized for charting over long time ranges.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "required": true, "description": "Start of the time range, in RFC3339 format.", "schema": { "type": "string" } }, { "name": "endDate", "in": "query", "required": true, "description": "End of the time range, in RFC3339 format.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of individual runs to return when not aggregating. Must be \u003e 0. Default: 100.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Number of runs to skip when not aggregating. Must be \u003e= 0. Default: 0.", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "description": "Filter runs by status. Valid values: pending, proxyQueued, containerQueued, processing, success, failure, cancelled.", "schema": { "type": "string" } }, { "name": "statusCode", "in": "query", "required": false, "description": "Filter runs by HTTP status code.", "schema": { "type": "integer" } }, { "name": "groupBy", "in": "query", "required": false, "description": "Time bucket for aggregated results. Valid values: minute, hour, day.", "schema": { "type": "string" } }, { "name": "aggregate", "in": "query", "required": false, "description": "Set to true to return aggregated counts instead of individual runs. Time ranges longer than 24 hours are aggregated automatically.", "schema": { "type": "boolean" } }, { "name": "minStartupTimeMs", "in": "query", "required": false, "description": "Only include runs with a startup time of at least this many milliseconds.", "schema": { "type": "integer" } }, { "name": "maxStartupTimeMs", "in": "query", "required": false, "description": "Only include runs with a startup time of at most this many milliseconds.", "schema": { "type": "integer" } }, { "name": "minResponseTimeMs", "in": "query", "required": false, "description": "Only include runs with a response time of at least this many milliseconds.", "schema": { "type": "integer" } }, { "name": "maxResponseTimeMs", "in": "query", "required": false, "description": "Only include runs with a response time of at most this many milliseconds.", "schema": { "type": "integer" } }, { "name": "tz", "in": "query", "required": false, "description": "IANA timezone used for time bucketing (e.g. America/New_York). Default: UTC.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run data for charting, either individual runs or aggregated time buckets.", "content": { "application/json": { "schema": { "properties": { "aggregatedData": { "description": "Aggregated counts per time bucket, when aggregating. Each item includes timeGroup, startTime, endTime, request counts (totalRequests, successfulRequests, failedRequests, cancelledRequests, proxyQueued, containerQueued, processing), successRate (number), and timing statistics in milliseconds (avg, p50, p90, p99, min, and max for runtime and response time, plus avgColdstartTimeMs and avgQueueTimeMs). Omitted when not aggregating.", "type": "array" }, "groupBy": { "description": "The time bucket size used for aggregation. Omitted when not aggregating.", "type": "string" }, "items": { "description": "Individual runs, when not aggregating. Each item has id, projectId, modelId, podName, coldstartTimeMs (integer), totalQueueTimeMs (integer), runtimeMs (number), totalResponseTimeMs (number), statusCode (integer), createdAt, and updatedAt fields. Omitted when aggregating.", "type": "array" }, "nextToken": { "description": "Pagination token for the next page. Omitted when there are no more results.", "type": "string" }, "timeRange": { "description": "The time range covered by the aggregated results. Omitted when not aggregating.", "type": "string" }, "total": { "description": "Total number of runs matching the query.", "type": "integer" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Runs"] } }, "/v2/projects/{project_id}/apps/{app_id}/runs/queueDepth": { "get": { "operationId": "countQueuedRuns", "summary": "Count Queued Runs", "description": "Retrieve the number of queued runs for a specific app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Counts of currently queued runs for the app.", "content": { "application/json": { "schema": { "properties": { "containerQueued": { "description": "Number of runs queued waiting for a container.", "type": "integer" }, "proxyQueued": { "description": "Number of runs queued at the proxy.", "type": "integer" }, "total": { "description": "Total number of queued runs.", "type": "integer" }, "truncated": { "description": "Whether the counts were capped before all queued runs were counted.", "type": "boolean" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Runs"] } }, "/v2/projects/{project_id}/apps/{app_id}/runs/{run_id}": { "delete": { "operationId": "cancelAppRun", "summary": "Cancel Run", "description": "Cancel an ongoing run for an app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A plain text message describing the result of the cancellation request." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Runs"] }, "get": { "operationId": "getAppRun", "summary": "Get Run", "description": "Retrieve details for a specific run of an app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Details of the requested run.", "content": { "application/json": { "schema": { "properties": { "item": { "description": "The run. Includes id, modelId, projectId, status, statusCode (integer), async (boolean), websocket (boolean), createdAt, updatedAt, completedAt, containerId, containerStartedAt, functionName, method, region, queue and response timing fields in milliseconds (queueTimeMs, runtimeMs, responseTimeMs, activatorQueueTimeMs, containerQueueTimeMs, totalQueueTimeMs, executionTimeMs, totalResponseTimeMs), request metadata (ip, accept, contentLength, origin, referrer, userAgent, websocketStream, webhookEndpoint), and for ephemeral runs the run configuration (ephemeral, command, hardware, cpu, memory, gpuCount, createdByUserId).", "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Runs"] } }, "/v2/projects/{project_id}/apps/{app_id}/secrets": { "get": { "operationId": "listAppSecrets", "summary": "List App Secrets", "description": "Retrieve a list of secrets for a specific app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A JSON object mapping secret names to their string values." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Secrets"] }, "patch": { "operationId": "updateAppSecrets", "summary": "Update App Secrets", "description": "Modify secrets for a specific app. The request body is a JSON object mapping secret names to string values.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A plain text confirmation message that the secrets were updated." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Secrets"] } }, "/v2/projects/{project_id}/audit-log": { "get": { "operationId": "listAuditLogs", "summary": "List Audit Logs", "description": "List the project's audit log, newest first. Readable by the project owner only, over the window the project's plan allows.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Start of the window, RFC3339. Clamped to the plan's retention window.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End of the window, RFC3339. Defaults to now.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": false, "description": "Return only this action, e.g. secrets.read.", "schema": { "type": "string" } }, { "name": "actor", "in": "query", "required": false, "description": "Return only actions taken by this actor id.", "schema": { "type": "string" } }, { "name": "outcome", "in": "query", "required": false, "description": "Return only success or failure.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1-200. Defaults to 50.", "schema": { "type": "integer" } }, { "name": "nextToken", "in": "query", "required": false, "description": "Page token from a previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of the project's audit log.", "content": { "application/json": { "schema": { "properties": { "hasMore": { "description": "Whether more rows remain.", "type": "boolean" }, "logs": { "description": "The audited actions, newest first.", "type": "array" }, "nextPageToken": { "description": "Token for the next page, absent at the end of the timeline.", "type": "string" }, "retentionDays": { "description": "How far back the project's plan allows reading.", "type": "integer" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Audit Log"] } }, "/v2/projects/{project_id}/billing/coupons/apply": { "post": { "operationId": "applyCoupon", "summary": "Apply Coupon", "description": "Apply a promotional coupon code to the project's billing account.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirmation that the coupon was applied, with the applied coupon's details.", "content": { "application/json": { "schema": { "properties": { "coupon": { "description": "Details of the applied coupon. Contains code (string), name (string), amount_cents (integer), amount_currency (string), frequency (string), expiration_at (string timestamp, omitted if the coupon does not expire), percentage_rate (number, omitted for fixed-amount coupons), and amount_cents_balance (integer of remaining credit in cents).", "type": "object" }, "message": { "description": "Human-readable confirmation message.", "type": "string" }, "success": { "description": "Whether the coupon was applied successfully.", "type": "boolean" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Billing", "Coupons"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "coupon_code": { "description": "The promotional coupon code to apply", "type": "string" } }, "required": ["coupon_code"], "type": "object" } } } } } }, "/v2/projects/{project_id}/billing/graph": { "get": { "operationId": "getProjectBillingGraph", "summary": "Get Billing Graph", "description": "Retrieve daily billing cost data per app as time series for charting.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "month", "in": "query", "required": false, "description": "Month to query in YYYY-MM format, or 'current'/'previous' aliases", "schema": { "type": "string" } }, { "name": "granularity", "in": "query", "required": false, "description": "Time granularity for data points (currently only 'day' is supported)", "schema": { "type": "string" } }, { "name": "top_n", "in": "query", "required": false, "description": "Number of top apps to return (default 10)", "schema": { "type": "integer" } }, { "name": "group_others", "in": "query", "required": false, "description": "Whether to group remaining apps into 'Others' (true/false)", "schema": { "type": "boolean" } }, { "name": "include_app_ids", "in": "query", "required": false, "description": "Comma-separated list of app IDs to include (optional filter)", "schema": { "type": "string" } }, { "name": "exclude_app_ids", "in": "query", "required": false, "description": "Comma-separated list of app IDs to exclude (optional filter)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Daily per-app billing cost time series for the requested month, ready for charting.", "content": { "application/json": { "schema": { "properties": { "labels": { "description": "Date labels (YYYY-MM-DD) for each data point in the series, covering the requested month.", "type": "array" }, "meta": { "description": "Summary metadata. Contains window_start (string), window_end (string), currency (string), total_apps (integer), returned_apps (integer), top_n (integer), y_max_suggestion (number), total_cost_before_discounts (number), total_discounts (number), and total_cost_after_discounts (number).", "type": "object" }, "others": { "description": "Aggregated series for apps outside the top N when group_others is true. Contains count (integer of grouped apps), data (array of daily cost numbers aligned with labels), and total (number). Omitted otherwise.", "type": "object" }, "series": { "description": "Per-app cost series. Each item contains app_id (string), app_name (string), data (array of daily cost numbers aligned with labels), and total (number) for the month.", "type": "array" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Billing"] } }, "/v2/projects/{project_id}/cost": { "get": { "operationId": "getProjectCost", "summary": "Get Project Cost", "description": "Retrieve current billing period cost breakdown for a project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "month", "in": "query", "required": false, "description": "Month to retrieve costs for, in YYYY-MM format. Defaults to the current month.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cost breakdown for the project for the requested month.", "content": { "application/json": { "schema": { "properties": { "app_breakdown": { "description": "Per-app usage breakdown from billing. Each item has app_name (string), cpu_cost_cents, cpu_seconds, gpu_cost_cents, gpu_seconds, memory_cost_cents, memory_seconds, and total_cost_cents fields.", "type": "array" }, "breakdown": { "description": "Per-app cost metrics for the month. Each item includes the app identifier with its CPU, GPU, and memory cost and usage figures.", "type": "array" }, "coupons": { "description": "Coupons applied to the account.", "items": { "properties": { "amount_cents": { "description": "Original coupon value in US cents.", "type": "integer" }, "amount_cents_remaining": { "description": "Credit still unspent, in US cents.", "type": "integer" }, "coupon_name": { "description": "Name of the applied coupon.", "type": "string" } }, "type": "object" }, "type": "array" }, "summary": { "description": "Aggregated cost totals for the month, including compute cost and usage totals in cents and seconds, build cost totals, coupon discounts, and combined totals before and after discounts.", "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Projects"] } }, "/v2/projects/{project_id}/domains": { "get": { "operationId": "listDomains", "summary": "List Custom Domains", "description": "Retrieve a list of custom domains for a specific project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "An object containing the list of custom domains for the project.", "content": { "application/json": { "schema": { "properties": { "domains": { "description": "List of custom domains, each with its validation status, DNS validation record details, region, and timestamps.", "type": "array" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Custom Domains"] }, "post": { "operationId": "createDomain", "summary": "Create Custom Domain", "description": "Create a new custom domain for a project with DNS validation records.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "The newly created custom domain, including the DNS record you must create to validate ownership.", "content": { "application/json": { "schema": { "properties": { "createdAt": { "description": "Timestamp when the domain was created (RFC 3339).", "type": "string" }, "dnsRecordName": { "description": "Name of the DNS record to create for validation.", "type": "string" }, "dnsRecordType": { "description": "Type of DNS record to create for validation (e.g., CNAME).", "type": "string" }, "dnsRecordValue": { "description": "Value of the DNS record to create for validation.", "type": "string" }, "domain": { "description": "The custom domain name.", "type": "string" }, "domainType": { "description": "Type of domain (apex or subdomain).", "type": "string" }, "id": { "description": "Unique identifier of the custom domain.", "type": "string" }, "projectId": { "description": "ID of the project the domain belongs to.", "type": "string" }, "region": { "description": "The region the domain routes to.", "type": "string" }, "updatedAt": { "description": "Timestamp when the domain was last updated (RFC 3339).", "type": "string" }, "validationStatus": { "description": "Current DNS validation status of the domain.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Custom Domains"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "domain": { "description": "The domain name to add (e.g., api.example.com)", "type": "string" }, "domainType": { "description": "Type of domain. Valid values: apex, subdomain. Wildcard domains are not currently supported.", "type": "string" }, "region": { "description": "The region the domain should route to (e.g., us-east-1). Must match the region where the target app is deployed.", "type": "string" } }, "required": ["domain", "domainType", "region"], "type": "object" } } } } } }, "/v2/projects/{project_id}/domains/{domain_id}": { "delete": { "operationId": "deleteDomain", "summary": "Delete Custom Domain", "description": "Remove a custom domain from a project. Domain must be unassigned from all apps first.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Empty response on success." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Custom Domains"] }, "get": { "operationId": "getDomain", "summary": "Get Custom Domain", "description": "Retrieve details for a specific custom domain.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested custom domain with its validation status and DNS validation record details.", "content": { "application/json": { "schema": { "properties": { "createdAt": { "description": "Timestamp when the domain was created (RFC 3339).", "type": "string" }, "dnsRecordName": { "description": "Name of the DNS record to create for validation.", "type": "string" }, "dnsRecordType": { "description": "Type of DNS record to create for validation (e.g., CNAME).", "type": "string" }, "dnsRecordValue": { "description": "Value of the DNS record to create for validation.", "type": "string" }, "domain": { "description": "The custom domain name.", "type": "string" }, "domainType": { "description": "Type of domain (apex or subdomain).", "type": "string" }, "errorMessage": { "description": "Details of the most recent validation failure. Omitted if there is no error.", "type": "string" }, "id": { "description": "Unique identifier of the custom domain.", "type": "string" }, "projectId": { "description": "ID of the project the domain belongs to.", "type": "string" }, "region": { "description": "The region the domain routes to.", "type": "string" }, "updatedAt": { "description": "Timestamp when the domain was last updated (RFC 3339).", "type": "string" }, "validatedAt": { "description": "Timestamp when the domain was successfully validated (RFC 3339). Omitted if not yet validated.", "type": "string" }, "validationStatus": { "description": "Current DNS validation status of the domain.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Custom Domains"] } }, "/v2/projects/{project_id}/domains/{domain_id}/assign": { "delete": { "operationId": "unassignDomain", "summary": "Unassign Domain from App", "description": "Remove the assignment between a domain and an app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Empty response on success." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Custom Domains"] }, "post": { "operationId": "assignDomain", "summary": "Assign Domain to App", "description": "Assign a validated custom domain to a specific app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "The mapping created between the domain and the app.", "content": { "application/json": { "schema": { "properties": { "appId": { "description": "ID of the app the domain is assigned to.", "type": "string" }, "createdAt": { "description": "Timestamp when the mapping was created (RFC 3339).", "type": "string" }, "domainId": { "description": "ID of the custom domain.", "type": "string" }, "id": { "description": "Unique identifier of the domain-to-app mapping.", "type": "string" }, "projectId": { "description": "ID of the project the domain belongs to.", "type": "string" }, "updatedAt": { "description": "Timestamp when the mapping was last updated (RFC 3339).", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Custom Domains"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "appId": { "description": "The ID of the app to assign the domain to.", "type": "string" } }, "required": ["appId"], "type": "object" } } } } } }, "/v2/projects/{project_id}/domains/{domain_id}/validate": { "post": { "operationId": "validateDomain", "summary": "Validate Custom Domain", "description": "Manually trigger DNS validation for a custom domain. Useful for retrying failed validations after DNS configuration changes.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirmation that domain validation has been triggered.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable confirmation message.", "type": "string" }, "success": { "description": "Whether the validation was triggered successfully.", "type": "boolean" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Custom Domains"] } }, "/v2/projects/{project_id}/invoices": { "get": { "operationId": "getProjectInvoices", "summary": "List Invoices", "description": "Retrieve billing invoices for a project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Billing invoices for the project.", "content": { "application/json": { "schema": { "items": { "properties": { "accountCountry": { "description": "Country of the billing account.", "type": "string" }, "accountName": { "description": "Name on the billing account.", "type": "string" }, "amountDue": { "description": "Amount due in the smallest currency unit.", "type": "integer" }, "createdAt": { "description": "Timestamp when the invoice was created.", "type": "string" }, "currency": { "description": "Currency of the invoice.", "type": "string" }, "fileUrl": { "description": "URL to download the invoice PDF.", "type": "string" }, "id": { "description": "Unique identifier of the invoice.", "type": "string" }, "paymentStatus": { "description": "Payment status of the invoice.", "type": "string" } }, "type": "object" }, "type": "array" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Subscriptions"] } }, "/v2/projects/{project_id}/payment-methods": { "get": { "operationId": "getProjectPaymentMethods", "summary": "List Payment Methods", "description": "Retrieve saved payment methods for a project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Saved payment methods for the project.", "content": { "application/json": { "schema": { "properties": { "creditCardBonusClaimed": { "description": "Whether the account has claimed the credit card signup bonus. Null when not applicable.", "type": "boolean" }, "methods": { "description": "Saved payment methods, the default first. Each item has id, brand, lastFourNumbers, expiryMonth, expiryYear, funding, country, wallet and isDefault fields.", "type": "array" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Subscriptions"] } }, "/v2/projects/{project_id}/payment-methods/{payment_method_id}": { "delete": { "operationId": "removeProjectPaymentMethod", "summary": "Remove Payment Method", "description": "Delete a saved payment method from a project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "payment_method_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A plain text confirmation message that the payment method was removed." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Subscriptions"] } }, "/v2/projects/{project_id}/payment-url": { "get": { "operationId": "getProjectPaymentUrl", "summary": "Get Payment URL", "description": "Generate a Stripe checkout URL for adding a payment method.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The checkout URL for adding a payment method, returned as a plain text string." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Subscriptions"] } }, "/v2/projects/{project_id}/secrets": { "get": { "operationId": "listProjectSecrets", "summary": "List Secrets", "description": "Retrieve a list of secrets for a specific project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A JSON object mapping secret names to their string values." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Secrets"] }, "patch": { "operationId": "updateProjectSecrets", "summary": "Update Secrets", "description": "Modify secrets for a specific project. The request body is a JSON object mapping secret names to string values.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A plain text confirmation message that the secrets were updated." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Secrets"] } }, "/v2/projects/{project_id}/service-accounts": { "get": { "operationId": "listServiceAccounts", "summary": "List Service Accounts", "description": "List all service accounts for a project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "An object containing the project's service accounts.", "content": { "application/json": { "schema": { "properties": { "serviceAccounts": { "description": "List of service accounts, each with id, name, description, projectId, createdByUserId, createdAt, and grants.", "type": "array" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Service Accounts"] }, "post": { "operationId": "createServiceAccount", "summary": "Create Service Account", "description": "Create a new service account for a project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The created service account together with its initial token.", "content": { "application/json": { "schema": { "properties": { "createdAt": { "description": "Creation timestamp in RFC 3339 format.", "type": "string" }, "createdByUserId": { "description": "ID of the user who created the service account.", "type": "string" }, "description": { "description": "Description of the service account.", "type": "string" }, "grants": { "description": "List of project IDs the service account is granted access to.", "type": "array" }, "id": { "description": "Unique identifier of the service account.", "type": "string" }, "name": { "description": "Name of the service account.", "type": "string" }, "projectId": { "description": "ID of the project that owns the service account.", "type": "string" }, "token": { "description": "The initial token, with its id, secret, and expiry. The secret value is only returned once, at creation.", "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Service Accounts"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "description": { "description": "Description of the service account (max 500 characters).", "type": "string" }, "expiresIn": { "description": "Lifetime of the initial token in seconds (max 31536000, i.e. one year). Use 0 for a token that never expires.", "type": "integer" }, "grants": { "description": "List of project IDs the service account is granted access to (1-50 entries).", "type": "array" }, "name": { "description": "Name of the service account (1-100 characters).", "type": "string" } }, "required": ["name", "grants", "expiresIn"], "type": "object" } } } } } }, "/v2/projects/{project_id}/service-accounts/{service_account_id}": { "delete": { "operationId": "deleteServiceAccount", "summary": "Delete Service Account", "description": "Delete a service account.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "service_account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirmation that the service account was deleted.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Confirmation message.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Service Accounts"] }, "patch": { "operationId": "updateServiceAccount", "summary": "Update Service Account", "description": "Update service account grants.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "service_account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirmation of the updated service account.", "content": { "application/json": { "schema": { "properties": { "serviceAccountId": { "description": "ID of the updated service account.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Service Accounts"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "grants": { "description": "Full list of project IDs the service account is granted access to (at least one entry). Replaces the existing grants.", "type": "array" } }, "required": ["grants"], "type": "object" } } } } } }, "/v2/projects/{project_id}/service-accounts/{service_account_id}/keys": { "get": { "operationId": "listServiceAccountTokens", "summary": "List Service Account Keys", "description": "List all tokens for a service account.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "service_account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "An object containing the service account's tokens, without the secret token values.", "content": { "application/json": { "schema": { "properties": { "keys": { "description": "List of tokens, each with id, name, description, createdAt, expiresAt, status, projectId, principalId, and source.", "type": "array" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Service Accounts"] } }, "/v2/projects/{project_id}/subscription": { "get": { "operationId": "getProjectSubscription", "summary": "Get Subscription", "description": "Retrieve the current subscription plan and status for a project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The project's current subscription plan and status.", "content": { "application/json": { "schema": { "properties": { "canManageBilling": { "description": "Whether the caller is allowed to manage billing for the project.", "type": "boolean" }, "id": { "description": "Identifier of the subscription.", "type": "string" }, "name": { "description": "Name of the subscription plan.", "type": "string" }, "nextPlanCode": { "description": "Code of the plan taking effect at the next billing period, if a downgrade is pending.", "type": "string" }, "ownerEmailAddress": { "description": "Email address of the project owner.", "type": "string" }, "planCode": { "description": "Code of the current plan.", "type": "string" }, "status": { "description": "Status of the subscription.", "type": "string" }, "userId": { "description": "ID of the project owner.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Subscriptions"] }, "patch": { "operationId": "changeProjectPlan", "summary": "Change Plan", "description": "Upgrade or downgrade the subscription plan for a project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Result of the plan change request.", "content": { "application/json": { "schema": { "properties": { "redirectUrl": { "description": "URL to complete payment for the plan change, when payment is required. Empty when no action is needed.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Subscriptions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "planCode": { "description": "The plan to switch the project to. Valid values: hobby, standard, enterprise.", "type": "string" } }, "required": ["planCode"], "type": "object" } } } } } }, "/v2/projects/{project_id}/users": { "delete": { "operationId": "removeUserFromProject", "summary": "Remove User", "description": "Remove a user from a project. Only project owners may remove users, and the last owner cannot be removed.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirmation that the user was removed.", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Whether the user was removed successfully.", "type": "boolean" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Users"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "emailAddress": { "description": "The email address of the user to remove.", "type": "string" } }, "required": ["emailAddress"], "type": "object" } } } } }, "get": { "operationId": "listProjectUsers", "summary": "List Users", "description": "Retrieve all users with access to a project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Users and pending invitations for the project.", "content": { "application/json": { "schema": { "items": { "properties": { "createdAt": { "description": "Timestamp when the user joined or was invited.", "type": "string" }, "email": { "description": "Email address of the user.", "type": "string" }, "firstName": { "description": "First name of the user.", "type": "string" }, "id": { "description": "Unique identifier of the user or invitation.", "type": "string" }, "invitedBy": { "description": "ID of the user who sent the invitation, for pending invitations.", "type": "string" }, "lastName": { "description": "Last name of the user.", "type": "string" }, "projectId": { "description": "ID of the project.", "type": "string" }, "role": { "description": "Role of the user on the project.", "type": "string" }, "status": { "description": "Membership status, such as active or invited.", "type": "string" }, "updatedAt": { "description": "Timestamp when the membership was last updated.", "type": "string" } }, "type": "object" }, "type": "array" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Users"] }, "post": { "operationId": "inviteUserToProject", "summary": "Invite User", "description": "Invite a user to join a project. Any member of the project may invite users.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirmation that the invitation was sent.", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Whether the invitation was sent successfully.", "type": "boolean" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Users"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "emailAddress": { "description": "The email address of the user to invite.", "type": "string" }, "role": { "description": "Role to grant the invited user. Valid values: member, billing.", "type": "string" } }, "required": ["emailAddress", "role"], "type": "object" } } } } } }, "/v2/projects/{project_id}/volumes": { "get": { "operationId": "listVolumes", "summary": "List Volumes", "description": "Retrieve a list of volumes for a specific project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Volumes for the project across all regions.", "content": { "application/json": { "schema": { "items": { "properties": { "capacityBytes": { "description": "Total capacity of the volume in bytes.", "type": "integer" }, "id": { "description": "Identifier of the volume.", "type": "string" }, "region": { "description": "Region the volume is in.", "type": "string" }, "usedCapacityBytes": { "description": "Used capacity of the volume in bytes. -1 when usage is unavailable.", "type": "integer" }, "usedCapacityInodes": { "description": "Number of files stored in the volume. -1 when usage is unavailable.", "type": "integer" } }, "type": "object" }, "type": "array" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Volumes"] } }, "/v2/projects/{project_id}/volumes/alerts": { "get": { "operationId": "getVolumeAlerts", "summary": "Get Volume Alerts", "description": "Retrieve the storage alert thresholds configured for the project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Configured storage alert thresholds.", "content": { "application/json": { "schema": { "properties": { "thresholds": { "description": "Percentages at which the project owner is emailed. Any of: 80, 90, 95. Empty when alerts are disabled.", "type": "array" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Volumes"] }, "put": { "operationId": "updateVolumeAlerts", "summary": "Update Volume Alerts", "description": "Replace the storage alert thresholds for the project. The project owner is emailed when a volume's used space crosses a configured threshold.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The normalized threshold set that was stored.", "content": { "application/json": { "schema": { "properties": { "thresholds": { "description": "Stored thresholds in ascending order.", "type": "array" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Volumes"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "thresholds": { "description": "Percentages at which to email the project owner. Any of: 80, 90, 95. An empty list disables alerts.", "type": "array" } }, "required": ["thresholds"], "type": "object" } } } } } }, "/v2/projects/{project_id}/volumes/{volume_id}/cp/complete": { "post": { "operationId": "completeUpload", "summary": "Complete File Upload", "description": "Finalize the file upload process to a specific volume. Intended for internal use - rather use the `cerebrium cp` command.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "volume_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A plain text confirmation message that the upload was completed." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Files"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "file_path": { "description": "The destination path of the uploaded file.", "type": "string" }, "parts": { "description": "The uploaded parts of the file. Each item is an object with part_number (integer) and etag (string).", "type": "array" }, "region": { "description": "Region of the volume. Default: us-east-1.", "type": "string" }, "upload_id": { "description": "The unique identifier for the upload, returned when the upload was initialized.", "type": "string" } }, "required": ["upload_id", "file_path", "parts"], "type": "object" } } } } } }, "/v2/projects/{project_id}/volumes/{volume_id}/cp/initialize": { "post": { "operationId": "initializeUpload", "summary": "Initialize File Upload", "description": "Begin the file upload process to a specific volume. Intended for internal use - rather use the `cerebrium cp` command.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "volume_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Upload identifier and presigned URLs for each part.", "content": { "application/json": { "schema": { "properties": { "parts": { "description": "Presigned upload URLs. Each item has part_number (integer) and url (string) fields.", "type": "array" }, "upload_id": { "description": "Identifier for the upload, to pass when completing it.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Files"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "file_path": { "description": "The destination path for the file.", "type": "string" }, "part_count": { "description": "The number of parts the file will be uploaded in. Must be \u003e= 0.", "type": "integer" }, "region": { "description": "Region of the volume. Default: us-east-1.", "type": "string" } }, "required": ["file_path", "part_count"], "type": "object" } } } } } }, "/v2/projects/{project_id}/volumes/{volume_id}/download": { "get": { "operationId": "downloadFile", "summary": "Download File", "description": "Download a file from a specific volume.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "volume_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file_path", "in": "query", "required": true, "description": "Path of the file to download.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "Region of the volume. Default: us-east-1.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A presigned URL for downloading the file.", "content": { "application/json": { "schema": { "properties": { "url": { "description": "Presigned download URL for the requested file.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Files"] } }, "/v2/projects/{project_id}/volumes/{volume_id}/ls": { "get": { "operationId": "listFiles", "summary": "List Files", "description": "Retrieve a list of files in a specified volume. Intended for internal use - rather use the `cerebrium ls` command.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "volume_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dir", "in": "query", "required": false, "description": "Directory path to list. Defaults to the volume root.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "Region of the volume. Default: us-east-1.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Files and folders at the requested path in the volume.", "content": { "application/json": { "schema": { "items": { "properties": { "is_folder": { "description": "Whether the entry is a folder.", "type": "boolean" }, "last_modified": { "description": "Timestamp when the file was last modified. Omitted when not available.", "type": "string" }, "name": { "description": "Name of the file or folder.", "type": "string" }, "size_bytes": { "description": "Size of the file in bytes. Omitted for folders.", "type": "integer" } }, "type": "object" }, "type": "array" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Files"] } }, "/v2/projects/{project_id}/volumes/{volume_id}/resize": { "patch": { "operationId": "resizeVolume", "summary": "Resize Volume", "description": "Modify the size of a specific volume.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "volume_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A plain text confirmation message that the volume was resized." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Volumes"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "newSizeGb": { "description": "New size of the volume in GB. Minimum 50. Sizes above 1024 require a protected project.", "type": "integer" } }, "required": ["newSizeGb"], "type": "object" } } } } } }, "/v2/projects/{project_id}/volumes/{volume_id}/rm": { "delete": { "operationId": "deleteFile", "summary": "Delete File", "description": "Remove a file from a specific volume. Intended for internal use - rather use the `cerebrium rm` command.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "volume_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file_path", "in": "query", "required": true, "description": "Path of the file or directory to delete.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "Region of the volume. Default: us-east-1.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A plain text confirmation message that the file was deleted." }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Files"] } }, "/v3/projects/{project_id}/apps/{app_id}/base-image": { "post": { "operationId": "createBaseImage", "summary": "Create Base Image Hash", "description": "Generate a SHA256 hash from dependency lists to determine if a base image rebuild is needed.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "Region the base image is built for. Defaults to the app's deployed region", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deterministic digest for the requested dependency set and its build status.", "content": { "application/json": { "schema": { "properties": { "digest": { "description": "SHA256 digest identifying the base image for this dependency set.", "type": "string" }, "status": { "description": "Build status of the base image, e.g. building or ready.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Builds"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "baseImageUri": { "description": "Base image URI to include in hash", "type": "string" }, "dependencies": { "description": "Dependency lists as objects mapping package name to version, under the keys pip, conda and apt", "type": "object" }, "preBuildCommands": { "description": "Base64 encoded pre-build commands", "type": "array" }, "shellCommands": { "description": "Base64 encoded shell commands", "type": "array" } }, "required": ["dependencies"], "type": "object" } } } } } }, "/v3/projects/{project_id}/apps/{app_id}/containers/active": { "get": { "operationId": "listActiveContainers", "summary": "List Active Containers", "description": "Retrieve all active containers, including those in terminating state.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of the app's active containers, including those currently shutting down.", "content": { "application/json": { "schema": { "items": { "properties": { "appId": { "description": "Identifier of the app the container belongs to.", "type": "string" }, "buildId": { "description": "Identifier of the build the container is running.", "type": "string" }, "containerId": { "description": "Unique identifier of the container instance.", "type": "string" }, "containerIp": { "description": "IP address assigned to the container.", "type": "string" }, "containerRestartCount": { "description": "Total number of times the container has restarted.", "type": "integer" }, "containerRunningTimeMs": { "description": "How long the container has been running, in milliseconds.", "type": "integer" }, "containerStartTimestamp": { "description": "Time the container started (ISO 8601).", "type": "string" }, "containerState": { "description": "Lifecycle state of the container (e.g. RUNNING, PENDING, SUCCEEDED).", "type": "string" }, "containerTerminationTimestamp": { "description": "Time the container terminated (ISO 8601). Set to the Unix epoch if the container has not terminated.", "type": "string" }, "hardwareProvider": { "description": "Cloud provider hosting the container.", "type": "string" }, "hostIp": { "description": "IP address of the host machine running the container.", "type": "string" }, "isTerminating": { "description": "Whether the container is currently shutting down.", "type": "boolean" }, "projectId": { "description": "Identifier of the project the app belongs to.", "type": "string" }, "region": { "description": "Region where the container is running.", "type": "string" }, "timestamp": { "description": "Time of the most recent status report for this container (ISO 8601).", "type": "string" } }, "type": "object" }, "type": "array" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Containers"] } }, "/v3/projects/{project_id}/apps/{app_id}/containers/cpu-mem": { "get": { "operationId": "listContainersCpuMem", "summary": "List Container Resource Usage", "description": "Retrieve current CPU and memory usage per container with totals.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current CPU and memory usage for each of the app's containers, alongside their allocated limits.", "content": { "application/json": { "schema": { "items": { "properties": { "container_id": { "description": "Unique identifier of the container instance.", "type": "string" }, "cpu": { "description": "Current CPU usage in cores.", "type": "number" }, "memory": { "description": "Current memory usage in MiB.", "type": "number" }, "total_cpu": { "description": "CPU limit allocated to the container, in cores.", "type": "number" }, "total_mem": { "description": "Memory limit allocated to the container, in MiB.", "type": "number" } }, "type": "object" }, "type": "array" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Containers"] } }, "/v3/projects/{project_id}/apps/{app_id}/containers/search": { "get": { "operationId": "searchContainers", "summary": "Search Containers", "description": "Search containers by ID or status with pagination.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Search term to filter containers by container ID", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter containers by status/state (case-insensitive, e.g., running, RUNNING, Running all work)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of containers to return (max 100, default 25)", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (default 1)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "A paginated list of containers matching the search criteria, most recent first.", "content": { "application/json": { "schema": { "items": { "properties": { "appId": { "description": "Identifier of the app the container belongs to.", "type": "string" }, "buildId": { "description": "Identifier of the build the container is running.", "type": "string" }, "containerId": { "description": "Unique identifier of the container instance.", "type": "string" }, "containerIp": { "description": "IP address assigned to the container.", "type": "string" }, "containerRestartCount": { "description": "Total number of times the container has restarted.", "type": "integer" }, "containerRunningTimeMs": { "description": "How long the container ran, in milliseconds.", "type": "integer" }, "containerStartTimestamp": { "description": "Time the container started (ISO 8601). Omitted if unavailable.", "type": "string" }, "containerState": { "description": "Lifecycle state of the container (e.g. RUNNING, SUCCEEDED, FAILED, PENDING).", "type": "string" }, "containerTerminationExitCode": { "description": "Exit code the container terminated with. Omitted if the container has not terminated.", "type": "integer" }, "containerTerminationTimestamp": { "description": "Time the container terminated (ISO 8601). Omitted if the container has not terminated.", "type": "string" }, "hardwareProvider": { "description": "Cloud provider hosting the container.", "type": "string" }, "hostIp": { "description": "IP address of the host machine running the container.", "type": "string" }, "projectId": { "description": "Identifier of the project the app belongs to.", "type": "string" }, "region": { "description": "Region where the container is running.", "type": "string" }, "timestamp": { "description": "Time of the most recent status report for this container (ISO 8601).", "type": "string" } }, "type": "object" }, "type": "array" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Containers"] } }, "/v3/projects/{project_id}/apps/{app_id}/containers/status": { "get": { "operationId": "listContainersStatus", "summary": "List Container Readiness", "description": "Retrieve the ready/not-ready status of each container.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of the app's containers with their current readiness status.", "content": { "application/json": { "schema": { "items": { "properties": { "container_id": { "description": "Unique identifier of the container instance.", "type": "string" }, "status": { "description": "Readiness of the container, either \"ready\" or \"not ready\".", "type": "string" } }, "type": "object" }, "type": "array" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Containers"] } }, "/v3/projects/{project_id}/apps/{app_id}/containers/{container_id}/events": { "get": { "operationId": "getContainerEvents", "summary": "Get Container Events", "description": "Retrieve lifecycle events for a container such as eviction, OOM, spot interruption, and checkpoint save or restore.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "container_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (default 1)", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of events per page (default 50, max 200)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "A paginated list of lifecycle events for the container.", "content": { "application/json": { "schema": { "properties": { "events": { "description": "Lifecycle events for the container, each with a timestamp, reason, message, type, and occurrence count.", "type": "array" }, "limit": { "description": "Number of events per page.", "type": "integer" }, "page": { "description": "Current page number.", "type": "integer" }, "total": { "description": "Number of events returned in this page.", "type": "integer" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Containers"] } }, "/v3/projects/{project_id}/apps/{app_id}/create-run-app": { "post": { "operationId": "createRunApp", "summary": "Create Run App", "description": "Create an app if it does not already exist, used by the CLI before running code.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "Region to create the app in. Defaults to the existing app's region, or the platform default for new apps", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirmation that the app was created or already exists.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable confirmation message.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Apps"] } }, "/v3/projects/{project_id}/apps/{app_id}/queue-depth": { "get": { "operationId": "queueDepth", "summary": "Get Queue Depth", "description": "Get real-time queue depth counts (proxyQueued, containerQueued, processing) for an app", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Real-time counts of the app's requests in each queue state.", "content": { "application/json": { "schema": { "properties": { "containerQueued": { "description": "Number of requests queued at a container waiting to be processed.", "type": "integer" }, "processing": { "description": "Number of requests currently being processed.", "type": "integer" }, "proxyQueued": { "description": "Number of requests queued at the gateway waiting for a container to become available.", "type": "integer" }, "total": { "description": "Total number of queued and in-flight requests.", "type": "integer" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Containers"] } }, "/v3/projects/{project_id}/apps/{app_id}/run": { "post": { "operationId": "runCommand", "summary": "Run App", "description": "Execute code on a deployed app.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "appName", "in": "query", "required": true, "description": "Name of the app to run against", "schema": { "type": "string" } }, { "name": "filename", "in": "query", "required": true, "description": "Path of the Python file to execute. Must have a .py extension", "schema": { "type": "string" } }, { "name": "functionName", "in": "query", "required": false, "description": "Name of the function to call within the file", "schema": { "type": "string" } }, { "name": "computeType", "in": "query", "required": false, "description": "Compute type to run on. One of ADA_L4, ADA_L40, AMPERE_A10, AMPERE_A100_40GB, AMPERE_A100_80GB, HOPPER_H100, CPU, INF2, TRN1, TURING_T4. Defaults to CPU", "schema": { "type": "string" } }, { "name": "cpu", "in": "query", "required": false, "description": "Number of CPU cores (0.1-12). Defaults to 2", "schema": { "type": "number" } }, { "name": "memoryGb", "in": "query", "required": false, "description": "Memory in GB (0.5-64). Defaults to 2", "schema": { "type": "number" } }, { "name": "gpuCount", "in": "query", "required": false, "description": "Number of GPUs (0-8). Defaults to 0", "schema": { "type": "integer" } }, { "name": "imageDigest", "in": "query", "required": false, "description": "Base image digest to run on, as returned by the base-image endpoint. Defaults to the standard Python base image", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "Region to run in. Defaults to the app's deployed region", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Details of the run that was created. Run output is not returned by this endpoint; it is delivered asynchronously via the run's logs.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable confirmation message.", "type": "string" }, "runId": { "description": "Unique identifier of the created run.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Cerebrium Run"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "data": { "description": "Multipart form field containing a JSON string of arguments passed to the function", "type": "string" }, "file": { "description": "Multipart form field containing a tar archive of the code files to run", "type": "string" } }, "required": ["file"], "type": "object" } } } } } }, "/v4/projects/{project_id}/integrations": { "get": { "operationId": "listIntegrations", "summary": "List Integrations", "description": "List all integrations for a project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The integrations connected to the project.", "content": { "application/json": { "schema": { "properties": { "integrations": { "description": "Integrations for the project, each with integrationId, integrationType, accountType, accountName, accountId, selectedRepos, status, createdAt, and updatedAt.", "type": "array" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Integrations"] } }, "/v4/projects/{project_id}/integrations/github": { "delete": { "operationId": "removeGithub", "summary": "Remove GitHub Integration", "description": "Remove the GitHub integration from a project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirmation that the GitHub integration was removed.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable confirmation message.", "type": "string" }, "success": { "description": "Whether the integration was removed.", "type": "boolean" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Integrations"] } }, "/v4/projects/{project_id}/integrations/github/install-url": { "get": { "operationId": "githubInstallUrl", "summary": "Get GitHub Install URL", "description": "Generate a GitHub App installation URL for a project.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The GitHub App installation URL along with a state token and its expiry time.", "content": { "application/json": { "schema": { "properties": { "expiresAt": { "description": "RFC 3339 timestamp at which the state token expires.", "type": "string" }, "state": { "description": "One-time state token that links the installation back to the project.", "type": "string" }, "url": { "description": "URL to visit to install the GitHub App for this project.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Integrations"] } }, "/v4/projects/{project_id}/integrations/github/repos": { "get": { "operationId": "listGithubRepos", "summary": "List GitHub Repos", "description": "List accessible GitHub repositories for the project's GitHub integration.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The GitHub repositories accessible to the project's GitHub App installation.", "content": { "application/json": { "schema": { "properties": { "repositories": { "description": "Accessible repositories, each with id, name, fullName, description, private, defaultBranch, htmlUrl, cloneUrl, language, starCount, and updatedAt.", "type": "array" }, "totalCount": { "description": "Total number of repositories returned.", "type": "integer" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Integrations"] } }, "/v4/projects/{project_id}/integrations/github/repos/{owner}/{repo}": { "get": { "operationId": "getRepoMetadata", "summary": "Get Repo Metadata", "description": "Retrieve metadata for a GitHub repository.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Metadata about the GitHub repository.", "content": { "application/json": { "schema": { "properties": { "archived": { "description": "Whether the repository is archived.", "type": "boolean" }, "branchCount": { "description": "Number of branches in the repository.", "type": "integer" }, "cloneUrl": { "description": "HTTPS URL for cloning the repository.", "type": "string" }, "createdAt": { "description": "Timestamp when the repository was created.", "type": "string" }, "defaultBranch": { "description": "Name of the repository's default branch.", "type": "string" }, "description": { "description": "Repository description, if set.", "type": "string" }, "disabled": { "description": "Whether the repository is disabled on GitHub.", "type": "boolean" }, "forksCount": { "description": "Number of forks of the repository.", "type": "integer" }, "fullName": { "description": "Full repository name in owner/repo format.", "type": "string" }, "hasIssues": { "description": "Whether issues are enabled on the repository.", "type": "boolean" }, "hasPages": { "description": "Whether GitHub Pages is enabled on the repository.", "type": "boolean" }, "hasWiki": { "description": "Whether the wiki is enabled on the repository.", "type": "boolean" }, "htmlUrl": { "description": "URL of the repository on GitHub.", "type": "string" }, "language": { "description": "Primary programming language, if detected.", "type": "string" }, "name": { "description": "Repository name.", "type": "string" }, "private": { "description": "Whether the repository is private.", "type": "boolean" }, "pushedAt": { "description": "Timestamp of the last push to the repository, if available.", "type": "string" }, "size": { "description": "Repository size in kilobytes.", "type": "integer" }, "stargazersCount": { "description": "Number of stars on the repository.", "type": "integer" }, "topics": { "description": "Topics assigned to the repository, if any.", "type": "array" }, "updatedAt": { "description": "Timestamp when the repository was last updated.", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Integrations"] } }, "/v4/projects/{project_id}/integrations/github/repos/{owner}/{repo}/branches": { "get": { "operationId": "listGithubBranches", "summary": "List GitHub Branches", "description": "List branches for a GitHub repository.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The branches of the GitHub repository.", "content": { "application/json": { "schema": { "properties": { "branches": { "description": "Branches in the repository, each with name, protected, default, and sha.", "type": "array" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Integrations"] } }, "/v4/projects/{project_id}/integrations/github/repos/{owner}/{repo}/toml": { "get": { "operationId": "getTomlConfig", "summary": "Get TOML Config", "description": "Parse and retrieve the cerebrium.toml configuration from a GitHub repository.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "query", "required": false, "description": "Branch to read the configuration from (either branch or commit is required)", "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "description": "Commit SHA to read the configuration from; takes precedence over branch (either branch or commit is required)", "schema": { "type": "string" } }, { "name": "path", "in": "query", "required": false, "description": "Directory path within the repository containing cerebrium.toml (defaults to the repository root)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The parsed cerebrium.toml configuration from the repository.", "content": { "application/json": { "schema": { "properties": { "config": { "description": "Parsed cerebrium.toml configuration; omitted if no cerebrium.toml was found at the given location.", "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Integrations"] } }, "/v4/projects/{project_id}/integrations/github/repos/{owner}/{repo}/tree": { "get": { "operationId": "getRepoTree", "summary": "Get Repo File Tree", "description": "Retrieve the file tree for a GitHub repository.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ref", "in": "query", "required": true, "description": "Branch name or commit SHA to retrieve the file tree for", "schema": { "type": "string" } }, { "name": "path", "in": "query", "required": false, "description": "Directory path within the repository (defaults to the repository root)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The hierarchical file tree of the GitHub repository at the requested ref.", "content": { "application/json": { "schema": { "properties": { "totalCount": { "description": "Total number of entries in the repository tree before filtering.", "type": "integer" }, "tree": { "description": "Root-level tree nodes, each with name, path, type (file or dir), size, sha, and nested children.", "type": "array" }, "truncated": { "description": "Whether GitHub truncated the tree because the repository is too large.", "type": "boolean" } }, "type": "object" } } } }, "400": { "description": "Bad request. The request was malformed or contained invalid parameters.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or the token is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Human-readable description of the error.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": ["Integrations"] } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Service Account Token authentication. To authenticate API requests:\n\n1. **Create a Service Account Token:**\n - Go to the [Cerebrium Dashboard](https://dashboard.cerebrium.ai/) and open the **API Keys** page\n - Click **Create Service Account**, name it (e.g., \"GitHub Actions CI/CD\"), choose an expiry date, and click **Create**\n - **Copy the token** generated for the desired service account\n\n2. **Use the Token:**\n Include the service account token in the Authorization header of API requests:\n `Authorization: Bearer \u003cyour-service-account-token\u003e`\n\n3. **Best Practices:**\n - Create separate service accounts for different environments (dev, staging, prod)\n - Store tokens securely as secrets in consuming applications or workflows\n - Set appropriate expiry dates and rotate tokens regularly\n - Never commit tokens to source control\n\nFor CI/CD integration examples, see the [CI/CD documentation](https://docs.cerebrium.ai/cerebrium/deployments/ci-cd)." } } } }