> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiative

> The initiative resource: scaffold and read it through /api/v1/initiatives, use the compatibility adapter for older full-field clients, and place work under it.

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. |

```bash theme={"dark"}
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:

```json theme={"dark"}
{
  "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`](/docs/api/entities/work-item).

## 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

```bash theme={"dark"}
# 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.