Initiative

An initiative is the container the work hierarchy hangs from: initiative → workstreams → milestones → tasks. POST /api/v1/initiatives scaffolds an initiative together with one starter workstream and milestone so work placement IDs exist immediately. Read the initiative tree with GET /api/v1/initiatives/{initiativeId}?include=tree.

Create — `POST /api/v1/initiatives`

Requires Authorization: Bearer oxk_... and an Idempotency-Key header. The body accepts exactly two fields; unknown fields are rejected.

Field	Type	Required	Meaning
`title`	string, 1–240	yes	Initiative title.
`summary`	string ≤4000, nullable	no	Short description.

curl https://useorgx.com/api/v1/initiatives \
  -X POST \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: q3-onboarding-revamp' \
  -d '{"title":"Q3 onboarding revamp","summary":"Reduce time-to-first-work."}'

Response — 201 first write, 200 on idempotent replay:

{
  "data": {
    "initiativeId": "2c6d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "workstreamId": "1b5c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
    "milestoneId": "0a4b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
    "duplicate": false
  },
  "meta": { "apiVersion": "1", "workspaceId": "3d7e4f5a-...", "duplicate": false }
}

The three returned IDs are the placement inputs for POST /work.

Compatibility: full-field writes

The compatibility surface accepts the full initiative field set: title (required), summary, description, status, priority (critical, active, maintenance, hold), risk_level, sequence, objective_id, estimated_hours, estimated_spend_usd, estimated_roi_usd, daily_limit_usd, hourly_limit_usd, metadata, context, workspace_id, and idempotency_key (up to 120 characters — replays return the existing initiative with _dedup: true instead of inserting a duplicate). New integrations should use the dedicated v1 scaffold and detail operations. The compatibility write is retained for older workspace and MCP clients. Creating an initiative here also kicks off a planning run unless you send auto_plan: false.

Read and update

# Read an initiative with its hierarchy
curl "https://useorgx.com/api/v1/initiatives/2c6d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f?include=tree" \
  -H "Authorization: Bearer $ORGX_API_KEY"

# Pause an initiative
curl https://useorgx.com/api/v1/lifecycle \
  -X POST \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"level":"initiative","id":"2c6d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f","action":"pause"}'

Initiative status values: draft, active, blocked, paused, completed, archived. The declared lifecycle is launch (draft → active), pause, resume, complete, and archive.

All operations on this resource

Operation	Method + path	Auth	Notes
Scaffold	`POST /api/v1/initiatives`	API key	Returns initiative + workstream + milestone IDs. `Idempotency-Key` required.
Read tree	`GET /api/v1/initiatives/{initiativeId}?include=tree`	API key	Returns workstreams, milestones, tasks, and dependency edges.
Create (full fields)	Compatibility `POST /api/entities` with `type: "initiative"`	API key	Older workspace clients only; prefer the v1 scaffold.
Update fields	Compatibility `PATCH /api/entities` with `type: "initiative"`	API key	Older workspace clients only.
Pause/resume/cancel	`POST /api/v1/lifecycle` with `level: "initiative"`	API key	Actions: `pause`, `resume`, `retry`, `cancel` — cascades to child runs.
Read the plan	`GET /api/v1/initiatives/{initiativeId}/plan`	Session	Web-app session only; not available to API keys today.
Delete	Not exposed	—	`PATCH` `status: "archived"` is the supported terminal state.

The child resources follow the same pattern with type: "workstream" (requires initiative_id; statuses not_started, active, blocked, paused, completed) and type: "milestone" (statuses planned, in_progress, completed, at_risk, cancelled). Creating a workstream, milestone, or task whose label already exists inside the same parent returns the existing row with _dedup: true.

Where the IDs come from

Field you send	Obtain it from
`initiativeId`	`POST /api/v1/initiatives` response `data.initiativeId`
`workstream_id`	Scaffold response `data.workstreamId`; compatibility lookup is available to older clients
`milestone_id`	Scaffold response `data.milestoneId`; compatibility lookup is available to older clients
`objective_id`	Compatibility entity read
`workspace_id`	`GET /api/v1/me` → `data.default_workspace_id`; usually omitted

MCP equivalents

scaffold_initiative mirrors the scaffold operation; orgx_act launches, pauses, and completes through the gateway lifecycle route; orgx_inspect hydrates one initiative with execution context. Older orgx_write calls use the compatibility adapter for full-field updates.

Getting Started

Connect Your Tools

Agent Ops

Platform

Build with the API

REST API v1 Reference

Entity Reference

Content Studio API

MCP and Plugins

Resources

Create — `POST /api/v1/initiatives`

Compatibility: full-field writes

Read and update

All operations on this resource

Where the IDs come from

MCP equivalents

​Create — POST /api/v1/initiatives

​Compatibility: full-field writes

​Read and update

​All operations on this resource

​Where the IDs come from

​MCP equivalents

Create — `POST /api/v1/initiatives`

Compatibility: full-field writes

Read and update

All operations on this resource

Where the IDs come from

MCP equivalents