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}$

Response

A deployment plan valid for fifteen minutes.

Immutable pre-build deployment plan. It expires exactly fifteen minutes after creation.

id
string
required
Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
project_id
string
required
Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
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,
cloudflare_containers
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. 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. Actual measured usage settles 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}$