Skip to main content
POST
Create a project

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
Idempotency-Key
string
required

Identifies one mutation and its canonical request payload.

Required string length: 1 - 128

Body

application/json

Phase 1 project creation request. The server assigns resource identifiers.

organization_id
string
required
Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
name
string
required
Required string length: 1 - 128
Pattern: ^\S(?:.*\S)?$
include_development_environment
boolean
default:true

Set false to create only Prod; Dev can be added later. Omission preserves existing Dev and Prod creation behavior.

source
object
data_mode
enum<string>
default:shared

Optional at creation, default shared. shared uses one data area across Dev/Prod; isolated gives each environment its own database/Auth records and file namespace. The four Owner-confirmed data-change actions reassign or reset areas without copying data or files and without a special change fee; ordinary measured resource consumption still applies. A reset or merge removes the named Dev resources. Promotion applies pending schema migrations to isolated Prod without copying Dev data.

Available options:
shared,
isolated
dev_access_mode
enum<string>
default:protected
Available options:
protected,
public
region
enum<string>
default:us

Chosen at project creation and immutable through customer operations. us (default) or eu places new build resources and, when no storage is already assigned, new file buckets. Existing buckets, source repositories and historical artifacts retain their recorded locations independently of a platform-authorized project-region migration. New PGCF application databases follow the selected project region; existing owner-authorized migrations target US1. Read database compute for the actual database region. storage.jurisdiction must match the project's recorded storage location, or this region when no storage custody exists. Project context reports the authoritative storage jurisdiction. Prices are identical in both project regions.

Available options:
us,
eu

Response

The project creation was accepted for asynchronous provisioning.

Durable record of an accepted project creation. project_id identifies the new project; it is returned unchanged by an identical idempotent replay.

id
string
required
Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
state
enum<string>
required
Available options:
queued
created_at
string<date-time>
required
updated_at
string<date-time>
required
project_id
string
required
Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$