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)?$
data_mode
enum<string>
default:shared

Chosen when the project is created. shared uses one database and a shared file namespace across Dev/Prod; isolated keeps their database/Auth records and files separate. Skills recommend isolated development, but the customer chooses the additional measured database consumption. Promotion applies pending schema migrations to an isolated Prod database without copying Dev data. Changing an established mode requires an explicit data migration.

Available options:
shared,
isolated

Response

The mutation was accepted for asynchronous processing.

Durable record returned for an accepted asynchronous mutation. Optional reconciliation is a current observation for queued/running work, separate from immutable terminal state. A completed reconciliation attempt alone does not mean the operation succeeded.

id
string
required
Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
state
enum<string>
required
Available options:
queued,
running,
succeeded,
failed,
cancelled
created_at
string<date-time>
required
updated_at
string<date-time>
required
result
object
error
object
progress
object

Current deployment dependency observation, separate from immutable operation history. Poll the same operation; mail readiness does not mean application activation.

reconciliation
object