Skip to main content
POST
Plan a deployment

Authorizations

Authorization
string
header
required

WorkOS access JWT or a user-owned WorkOS API key. User keys are bound to one organization and restricted to their enabled product permissions. Session-only onboarding and session revocation require an interactive access JWT. No cookie session is assumed.

Headers

X-Request-Id
string

Optional caller-provided correlation identifier.

Required string length: 1 - 128

Path Parameters

project_id
string
required

Project identifier.

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$

Body

application/json
commit_sha
string
required

Exact full Git commit object identifier; abbreviated or branch references are forbidden.

Pattern: ^[0-9a-f]{40}$
environment
enum<string>
default:dev

The environment the deployment builds into. Prod skips Dev and switches Prod traffic once activated.

Available options:
dev,
prod

Response

A deployment plan valid for 24 hours.

Immutable pre-build deployment plan. It expires exactly 24 hours after creation.

id
string
required
Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
project_id
string
required
Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
environment
enum<string>
required

The environment this plan builds into.

Available options:
dev,
prod
commit_sha
string
required

Exact full Git commit object identifier; abbreviated or branch references are forbidden.

Pattern: ^[0-9a-f]{40}$
source_digest
string
required
Pattern: ^sha256:[0-9a-f]{64}$
build_plan_digest
string
required
Pattern: ^sha256:[0-9a-f]{64}$
application_root
string
required
read-only

Canonical repository-relative application root selected from immutable source evidence.

Maximum string length: 64
Pattern: ^(?:\.|[A-Za-z0-9][A-Za-z0-9._-]{0,62}(?:/[A-Za-z0-9][A-Za-z0-9._-]{0,62}){0,7})$
runtime
enum<string>
required
Available options:
cloudflare_workers_static_assets,
cloudflare_workers_edge_ssr
route
string<uri>
required

Server-derived project-isolated public deployment URL; clients cannot select its gateway host or target Worker.

Pattern: ^https://
resource_effects
string[]
required
Required string length: 1 - 512
limits
string[]
required
Required string length: 1 - 512
estimated_cost
object
required

Build-compute reservation quote, not the lifetime cost of the application. credits is the reserved amount in credits as a decimal (credit_micros divided by one million), the figure to show people. amount_micros is the customer USD equivalent of credit_micros; provider_cost_micros is the corresponding published provider-list basis. The versioned price is fixed by this immutable deployment plan. reserved_seconds is the reserved build time in seconds. The measured build seconds settle the reservation and unused credits are released. Storage, mail and runtime costs are separate.

risks
string[]
required
Required string length: 1 - 512
destructive_effects
string[]
required
Required string length: 1 - 512
required_confirmations
string[]
required
Required string length: 1 - 128
created_at
string<date-time>
required
expires_at
string<date-time>
required
artifact_digest
string
Pattern: ^sha256:[0-9a-f]{64}$