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

# Generate a reviewable initiative plan proposal

> Run the planning pipeline synchronously over your title, prompt, and
optional explicit workstreams, and persist an immutable,
digest-addressed proposal — agent assignments with confidence and
rationale, milestone/task expansion, effort and budget estimates, and
the generation receipt. No workstream, milestone, or task rows are
written: review the proposal, then commit it through
`POST /initiatives` with `proposal_id` + `proposal_digest`.

Retrying with the same Idempotency-Key returns the original stored
proposal without re-running generation. Rate limited to 6 requests
per minute with one concurrent generation per workspace.



## OpenAPI

````yaml /openapi/v1.yaml post /initiatives/proposals
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/proposals:
    post:
      tags:
        - Initiatives
      summary: Generate a reviewable initiative plan proposal
      description: |-
        Run the planning pipeline synchronously over your title, prompt, and
        optional explicit workstreams, and persist an immutable,
        digest-addressed proposal — agent assignments with confidence and
        rationale, milestone/task expansion, effort and budget estimates, and
        the generation receipt. No workstream, milestone, or task rows are
        written: review the proposal, then commit it through
        `POST /initiatives` with `proposal_id` + `proposal_digest`.

        Retrying with the same Idempotency-Key returns the original stored
        proposal without re-running generation. Rate limited to 6 requests
        per minute with one concurrent generation per workspace.
      operationId: proposeInitiativeScaffold
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiativeProposalRequest'
            example:
              title: Launch the customer API
              prompt: Ship a public REST surface with docs and examples in two weeks
              depth: full
              agent_assignment: auto
      responses:
        '200':
          description: Original proposal returned after a safe retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiativeProposalResponse'
              example:
                data:
                  proposal_id: 7c1f9a34-5b2e-4d8f-9a01-3e6b7c8d9e0f
                  proposal_digest: >-
                    sha256:9b2f1c0d8a7e6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c
                  status: proposed
                  expires_at: '2026-08-26T12:00:00.000Z'
                  plan:
                    initiative:
                      title: Launch the customer API
                    workstreams:
                      - name: Strategy
                        domain: product
                        agent_id: product-agent
                        agent_name: Pace
                        confidence: 0.62
                        rationale: Baseline capability routing.
                        expected_tokens: 8000
                        expected_duration_hours: 5
                        expected_budget_usd: 0.4
                  assignment_source: baseline
                  economics:
                    expected_tokens: 8000
                    expected_hours: 5
                    expected_budget_usd: 0.4
                    human_equivalent_usd: 599.6
                    value_basis: market_rate_by_task_type_less_spend
                  generation_receipt:
                    receipt_id: 1a9f5066-24b3-4d4a-90f0-b0f75fe2fe19
                    provider: orgx
                    model: deterministic-baseline
                    tokens_in: 0
                    tokens_out: 0
                    cost_usd: 0
                meta:
                  apiVersion: '1'
                  workspaceId: 09707fa5-aaae-4493-8a23-827111000f89
                  duplicate: true
        '201':
          description: Proposal generated and stored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiativeProposalResponse'
              example:
                data:
                  proposal_id: 7c1f9a34-5b2e-4d8f-9a01-3e6b7c8d9e0f
                  proposal_digest: >-
                    sha256:9b2f1c0d8a7e6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c
                  status: proposed
                  expires_at: '2026-08-26T12:00:00.000Z'
                  plan:
                    initiative:
                      title: Launch the customer API
                    workstreams:
                      - name: Strategy
                        domain: product
                        agent_id: product-agent
                        agent_name: Pace
                        confidence: 0.62
                        rationale: Baseline capability routing.
                        expected_tokens: 8000
                        expected_duration_hours: 5
                        expected_budget_usd: 0.4
                  assignment_source: baseline
                  economics:
                    expected_tokens: 8000
                    expected_hours: 5
                    expected_budget_usd: 0.4
                    human_equivalent_usd: 599.6
                    value_basis: market_rate_by_task_type_less_spend
                  generation_receipt:
                    receipt_id: 1a9f5066-24b3-4d4a-90f0-b0f75fe2fe19
                    provider: orgx
                    model: deterministic-baseline
                    tokens_in: 0
                    tokens_out: 0
                    cost_usd: 0
                meta:
                  apiVersion: '1'
                  workspaceId: 09707fa5-aaae-4493-8a23-827111000f89
                  duplicate: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          description: |-
            Policy refusal on valid input — `objective_required`,
            `generation_allowance_exhausted`, or `generation_cost_unknown`
            (the provider reported no billable usage; nothing was persisted).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: |-
            `generation_in_progress` — one generation runs per workspace at a
            time; retry after the interval in Retry-After.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: |-
            `upstream_generation_failed` — generation failed upstream; a
            failure receipt was recorded and no proposal was persisted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      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:
    InitiativeProposalRequest:
      type: object
      additionalProperties: false
      required:
        - title
      properties:
        workspace_id:
          type: string
          format: uuid
        title:
          type: string
          minLength: 1
          maxLength: 200
        summary:
          type:
            - string
            - 'null'
          maxLength: 4000
        prompt:
          type: string
          maxLength: 4000
          description: Small-prompt carrier folded into the generation intent
        goal_ids:
          type: array
          maxItems: 20
          items:
            type: string
            format: uuid
        context:
          type: object
          additionalProperties: false
          properties:
            audience:
              type: string
              maxLength: 500
            constraints:
              type: array
              maxItems: 10
              items:
                type: string
            success_criteria:
              type: array
              maxItems: 10
              items:
                type: string
            links:
              type: array
              maxItems: 10
              items:
                type: string
                format: uri
            notes:
              type: string
              maxLength: 4000
        depth:
          type: string
          enum:
            - initiative
            - workstreams
            - full
          default: full
        workstreams:
          type: array
          maxItems: 20
          description: When present, generation only fills gaps in your explicit lanes
          items:
            type: object
            additionalProperties: false
            required:
              - name
            properties:
              name:
                type: string
                minLength: 1
                maxLength: 240
              goal:
                type: string
                maxLength: 4000
              domain_hint:
                type: string
                enum:
                  - product
                  - engineering
                  - marketing
                  - sales
                  - operations
                  - design
                  - orchestration
              agent_id:
                type: string
              depends_on:
                type: array
                maxItems: 20
                items:
                  type: string
              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:
                  type: object
                  additionalProperties: false
                  required:
                    - title
                  properties:
                    title:
                      type: string
                    tasks:
                      type: array
                      maxItems: 15
                      items:
                        $ref: '#/components/schemas/InitiativePlanTask'
        agent_assignment:
          type: string
          enum:
            - auto
            - none
          default: auto
        generation:
          type: object
          additionalProperties: false
          properties:
            model_tier:
              type: string
              enum:
                - standard
                - balanced
                - precision
              default: standard
              description: >-
                Generation-time tier only; run-time forcing lives on launch and
                runs
            max_workstreams:
              type: integer
              minimum: 1
              maximum: 12
        source_evidence:
          type: object
          additionalProperties: false
          required:
            - target_url
            - verification_state
          properties:
            target_url:
              type: string
              format: uri
            verification_state:
              type: string
              enum:
                - verified
                - partial
                - unverified
              description: >-
                unverified pins the committed initiative to draft and blocks
                launch
            evidence_urls:
              type: array
              maxItems: 20
              items:
                type: string
                format: uri
            notes:
              type: string
              maxLength: 4000
    InitiativeProposalResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: object
          required:
            - proposal_id
            - proposal_digest
            - status
            - expires_at
            - plan
            - assignment_source
            - economics
          properties:
            proposal_id:
              type: string
              format: uuid
            proposal_digest:
              type: string
              pattern: ^sha256:[0-9a-f]{64}$
            status:
              type: string
              enum:
                - proposed
                - instantiated
                - expired
            expires_at:
              type: string
              format: date-time
            plan:
              $ref: '#/components/schemas/InitiativePlan'
            assignment_source:
              type: string
              enum:
                - model
                - baseline
            economics:
              type: object
              properties:
                expected_tokens:
                  type: integer
                expected_hours:
                  type: number
                expected_budget_usd:
                  type: number
                human_equivalent_usd:
                  type: number
                value_basis:
                  type: string
            generation_receipt:
              type: object
              properties:
                receipt_id:
                  type: string
                  format: uuid
                provider:
                  type:
                    - string
                    - 'null'
                model:
                  type:
                    - string
                    - 'null'
                tokens_in:
                  type:
                    - integer
                    - 'null'
                tokens_out:
                  type:
                    - integer
                    - 'null'
                cost_usd:
                  type:
                    - number
                    - 'null'
        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
    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
    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'
  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'
    Conflict:
      description: Idempotency or expected-version conflict
      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

````