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

# Create an initiative

> Create an initiative with its first workstream and backlog.



## OpenAPI

````yaml openapi/v1.yaml POST /initiatives
openapi: 3.1.0
info:
  title: OrgX REST API v1
  version: '1'
  description: >-
    Build accountable work into your product with OrgX REST API v1.


    Create work with one field, attach evidence when it is complete, and keep
    the receipt. Every authenticated request is scoped to the workspace resolved
    from your credential.


    Start with `POST /work`. Human guide:
    https://docs.useorgx.com/docs/api/quickstart
  contact:
    name: OrgX Support
    url: https://useorgx.com/support
    email: support@useorgx.com
  license:
    name: Proprietary
    url: https://useorgx.com/terms
servers:
  - url: https://useorgx.com/api/v1
    description: Production
security: []
tags:
  - name: Work
    description: Create accountable work and complete it with evidence
  - name: Initiatives
    description: Organize related work around an outcome
  - name: Operating processes
    description: Evidence-backed company workflow/process lifecycle
  - name: Operating map
    description: Derived, rebuildable Operating Map projection over the process ledger
  - name: Discovery runs
    description: Wizard and deep-search workflow discovery over connected company sources
  - name: Handoffs
    description: Ledger-backed stage handoffs between operating-process stages
  - name: Events
    description: Replayable, workspace-scoped accepted ledger events
  - name: Projections
    description: Workspace-scoped, rebuildable read projections over OrgX sources
  - name: Episodes
    description: Mission-compatible Episode read adapters
  - name: Receipt validation
    description: Account-free Agent Work Receipt schema discovery and conformance
  - name: Receipt import
    description: Authenticated, workspace-scoped import into the hosted receipt ledger
  - name: Workload diagnosis
    description: >-
      Account-free evaluation of time, agents, systems, authority, and
      accountability boundaries
  - name: Content Studio
    description: >-
      Estimate, showcase, checkout, and payment event operations for Content
      Studio
  - name: Decisions
    description: Raise decisions for human ruling and read their state
  - name: Artifacts
    description: Register produced work against the entity it belongs to
  - name: Launches
    description: Preview and run an initiative launch through its spend gates
  - name: Runs
    description: Control agent runs with pause, resume, cancel, and rollback
  - name: Lifecycle
    description: Pause, resume, retry, or cancel work hierarchy nodes and runs
  - name: Deduplication
    description: Claim durable event fingerprints so duplicate triggers fire once
  - name: Credential
    description: >-
      Resolve the calling credential, the workspaces it reaches, and what it may
      do
  - name: API discovery
    description: Account-free error codes, request schemas, and closed vocabularies for v1
externalDocs:
  description: Human-readable OrgX REST API v1 reference
  url: https://docs.useorgx.com/docs/api/public-api
paths:
  /initiatives:
    post:
      tags:
        - Initiatives
      summary: Create an initiative
      description: |-
        Create an initiative in one of three forms, discriminated by body shape:

        - **Commit a proposal**: send `proposal_id` + `proposal_digest` (from
          `POST /initiatives/proposals`) to instantiate the exact reviewed plan.
          Proposals are single-use and expire after 7 days.
        - **Inline plan**: send a full `plan` hierarchy plus its `plan_digest`
          (sha256 over the canonical JSON of `plan`); the server recomputes the
          digest and refuses drift with 409.
        - **Title only**: send `{title, summary?}` for the starter 3-row
          hierarchy (initiative, first workstream, backlog milestone).

        Plan commits write the whole tree — workstreams, milestones, tasks,
        dependency edges, receipt, and ledger event — in one transaction; a
        failed commit persists nothing. Creation is inert: agents dispatch only
        through an explicit launch. Safe to retry with the same Idempotency-Key.
      operationId: scaffoldInitiative
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/InitiativeCommitProposalRequest'
                - $ref: '#/components/schemas/InitiativeCommitPlanRequest'
                - $ref: '#/components/schemas/InitiativeScaffoldRequest'
            example:
              plan:
                initiative:
                  title: Launch the customer API
                workstreams:
                  - name: Engineering
                    goal: Build and validate the API surface
                    agent_id: engineering-agent
                    milestones:
                      - title: 'Engineering: plan, execute, and validate'
                        tasks:
                          - title: Scope the endpoints
                            type: research
                          - title: Implement the endpoints
                            type: implement
                            depends_on:
                              - Scope the endpoints
                  - name: Launch
                    depends_on:
                      - Engineering
              plan_digest: >-
                sha256:9b2f1c0d8a7e6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c
      responses:
        '200':
          description: Original result returned after a safe retry
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/InitiativeCommitResponse'
                  - $ref: '#/components/schemas/InitiativeScaffoldResponse'
              example:
                data:
                  initiative:
                    id: 1481c341-089b-4be0-809b-49cb6e4fee48
                    title: Launch the customer API
                    status: draft
                    aggregateVersion: 1
                  created:
                    workstreams: 2
                    milestones: 1
                    tasks: 2
                    dependency_edges: 2
                    agents_assigned: 1
                  receipt:
                    receipt_id: 1a9f5066-24b3-4d4a-90f0-b0f75fe2fe19
                    event_id: 1231d7d4-c43e-4f5a-8c65-628f4122b1b9
                  links:
                    self: /api/v1/initiatives/1481c341-089b-4be0-809b-49cb6e4fee48
                    tree: >-
                      /api/v1/initiatives/1481c341-089b-4be0-809b-49cb6e4fee48?include=tree
                    pulse: >-
                      /api/v1/initiatives/1481c341-089b-4be0-809b-49cb6e4fee48/pulse
                meta:
                  apiVersion: '1'
                  workspaceId: 09707fa5-aaae-4493-8a23-827111000f89
                  duplicate: true
                  aggregateVersion: 1
        '201':
          description: Initiative created
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/InitiativeCommitResponse'
                  - $ref: '#/components/schemas/InitiativeScaffoldResponse'
              example:
                data:
                  initiative:
                    id: 1481c341-089b-4be0-809b-49cb6e4fee48
                    title: Launch the customer API
                    status: draft
                    aggregateVersion: 1
                  created:
                    workstreams: 2
                    milestones: 1
                    tasks: 2
                    dependency_edges: 2
                    agents_assigned: 1
                  receipt:
                    receipt_id: 1a9f5066-24b3-4d4a-90f0-b0f75fe2fe19
                    event_id: 1231d7d4-c43e-4f5a-8c65-628f4122b1b9
                  links:
                    self: /api/v1/initiatives/1481c341-089b-4be0-809b-49cb6e4fee48
                    tree: >-
                      /api/v1/initiatives/1481c341-089b-4be0-809b-49cb6e4fee48?include=tree
                    pulse: >-
                      /api/v1/initiatives/1481c341-089b-4be0-809b-49cb6e4fee48/pulse
                meta:
                  apiVersion: '1'
                  workspaceId: 09707fa5-aaae-4493-8a23-827111000f89
                  duplicate: false
                  aggregateVersion: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: |-
            Conflict — `idempotency_conflict` (key reused with different
            material), `plan_digest_mismatch`, `proposal_digest_mismatch`,
            `proposal_expired`, or `proposal_already_instantiated`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: |-
            The plan is structurally invalid — for example a `depends_on`
            reference to an unknown sibling. Nothing was persisted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - bearerAuth: []
        - cookieAuth: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 200
        pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$
      description: Workspace-scoped retry key for safe mutation replay.
  schemas:
    InitiativeCommitProposalRequest:
      type: object
      additionalProperties: false
      required:
        - proposal_id
        - proposal_digest
      properties:
        workspace_id:
          type: string
          format: uuid
        proposal_id:
          type: string
          format: uuid
        proposal_digest:
          type: string
          pattern: ^sha256:[0-9a-f]{64}$
          description: >-
            Must equal the stored proposal digest — commit exactly what you
            reviewed
        initiative_id:
          type: string
          format: uuid
          description: >-
            Optional client-supplied id; defaults to a deterministic id derived
            from workspace and Idempotency-Key
        overrides:
          $ref: '#/components/schemas/InitiativeCommitOverrides'
        expected_aggregate_version:
          type: integer
          const: 0
    InitiativeCommitPlanRequest:
      type: object
      additionalProperties: false
      required:
        - plan
        - plan_digest
      properties:
        workspace_id:
          type: string
          format: uuid
        plan:
          $ref: '#/components/schemas/InitiativePlan'
        plan_digest:
          type: string
          pattern: ^sha256:[0-9a-f]{64}$
          description: >-
            sha256 over the canonical JSON (sorted keys) of `plan`; the server
            recomputes and compares
        initiative_id:
          type: string
          format: uuid
        overrides:
          $ref: '#/components/schemas/InitiativeCommitOverrides'
        expected_aggregate_version:
          type: integer
          const: 0
    InitiativeScaffoldRequest:
      type: object
      additionalProperties: false
      required:
        - title
      properties:
        workspace_id:
          type: string
          format: uuid
          description: >-
            Optional target workspace; defaults to the caller's default
            workspace
        title:
          type: string
          minLength: 1
          maxLength: 240
        summary:
          type:
            - string
            - 'null'
          maxLength: 4000
    InitiativeCommitResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: object
          required:
            - initiative
            - created
            - receipt
            - links
          properties:
            initiative:
              type: object
              required:
                - id
                - status
                - aggregateVersion
              properties:
                id:
                  type: string
                  format: uuid
                title:
                  type:
                    - string
                    - 'null'
                status:
                  type: string
                aggregateVersion:
                  type: integer
            created:
              type: object
              required:
                - workstreams
                - milestones
                - tasks
                - dependency_edges
                - agents_assigned
              properties:
                workstreams:
                  type: integer
                milestones:
                  type: integer
                tasks:
                  type: integer
                dependency_edges:
                  type: integer
                agents_assigned:
                  type: integer
            proposal_id:
              type: string
              format: uuid
            receipt:
              type: object
              required:
                - receipt_id
                - event_id
              properties:
                receipt_id:
                  type: string
                  format: uuid
                event_id:
                  type: string
                  format: uuid
            links:
              type: object
              properties:
                self:
                  type: string
                tree:
                  type: string
                pulse:
                  type: string
        meta:
          type: object
          required:
            - apiVersion
            - workspaceId
            - duplicate
          properties:
            apiVersion:
              type: string
              const: '1'
            workspaceId:
              type: string
              format: uuid
            duplicate:
              type: boolean
            aggregateVersion:
              type: integer
    InitiativeScaffoldResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: object
          required:
            - initiativeId
            - workstreamId
            - milestoneId
            - duplicate
          properties:
            initiativeId:
              type: string
              format: uuid
            workstreamId:
              type: string
              format: uuid
            milestoneId:
              type: string
              format: uuid
            duplicate:
              type: boolean
        meta:
          type: object
          required:
            - apiVersion
            - workspaceId
            - duplicate
          properties:
            apiVersion:
              type: string
              const: '1'
            workspaceId:
              type: string
              format: uuid
            duplicate:
              type: boolean
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
            requestId:
              type: string
            timestamp:
              type: string
              format: date-time
            docsUrl:
              type: string
              format: uri
            retryAfter:
              type: integer
              description: Seconds until rate limit resets
    InitiativeCommitOverrides:
      type: object
      additionalProperties: false
      description: >-
        Non-structural adjustments; structural edits require a new plan or
        proposal
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 240
        visibility:
          type: string
          enum:
            - private
            - workspace
            - public
          default: private
        model_tier:
          type: string
          enum:
            - standard
            - balanced
            - precision
            - local
            - sonnet
            - opus
        autonomy:
          type: object
          additionalProperties: false
          properties:
            mode:
              type: string
              enum:
                - manual
                - gated
                - autopilot
            max_budget_usd:
              type: number
              exclusiveMinimum: 0
            max_concurrent_agents:
              type: integer
              minimum: 1
              maximum: 20
              default: 8
    InitiativePlan:
      type: object
      additionalProperties: false
      required:
        - initiative
        - workstreams
      properties:
        initiative:
          type: object
          additionalProperties: false
          required:
            - title
          properties:
            title:
              type: string
              minLength: 1
              maxLength: 240
            summary:
              type:
                - string
                - 'null'
              maxLength: 4000
        workstreams:
          type: array
          minItems: 1
          maxItems: 20
          items:
            $ref: '#/components/schemas/InitiativePlanWorkstream'
    InitiativePlanWorkstream:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 240
        goal:
          type:
            - string
            - 'null'
          maxLength: 4000
        domain:
          type: string
          enum:
            - product
            - engineering
            - marketing
            - sales
            - operations
            - design
            - orchestration
        agent_id:
          type: string
        agent_name:
          type: string
        confidence:
          type: number
          minimum: 0
          maximum: 1
        rationale:
          type: string
          maxLength: 2000
        depends_on:
          type: array
          maxItems: 20
          items:
            type: string
          description: Names of sibling workstreams
        deliverables:
          type: array
          maxItems: 20
          items:
            type: string
        expected_tokens:
          type: integer
          minimum: 1
        expected_duration_hours:
          type: number
          exclusiveMinimum: 0
        expected_budget_usd:
          type: number
          exclusiveMinimum: 0
        milestones:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/InitiativePlanMilestone'
    InitiativePlanMilestone:
      type: object
      additionalProperties: false
      required:
        - title
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 240
        description:
          type:
            - string
            - 'null'
          maxLength: 4000
        tasks:
          type: array
          maxItems: 15
          items:
            $ref: '#/components/schemas/InitiativePlanTask'
    InitiativePlanTask:
      type: object
      additionalProperties: false
      required:
        - title
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 240
        detail:
          type:
            - string
            - 'null'
          maxLength: 4000
        type:
          type: string
          enum:
            - research
            - create
            - review
            - implement
        depends_on:
          type: array
          maxItems: 15
          items:
            type: string
          description: Titles of sibling tasks in the same milestone
        agent_id:
          type: string
          description: Canonical '-agent' id
        expected_tokens:
          type: integer
          minimum: 1
        expected_duration_hours:
          type: number
          exclusiveMinimum: 0
        expected_budget_usd:
          type: number
          exclusiveMinimum: 0
  responses:
    BadRequest:
      description: Request validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    NotFound:
      description: Resource is unavailable to the caller
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ServiceUnavailable:
      description: Ledger or workspace authorization is unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'OrgX API key, sent as `Authorization: Bearer oxk_...`'
    cookieAuth:
      type: apiKey
      in: cookie
      name: __session
      description: Session cookie from web authentication

````