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

> Create a visible work item with one required body field.



## OpenAPI

````yaml openapi/v1.yaml POST /work
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:
  /work:
    post:
      tags:
        - Work
      summary: Create work
      description: >-
        Create a work item and return its receipt. Send only a title to place it
        in the workspace Inbox, or supply a complete initiative hierarchy when
        you need precise placement.


        ### Guarantees

        The Idempotency-Key makes retries safe. The response identifies the
        work, receipt, and accepted event.
      operationId: command.createWork
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkCommandRequest'
            example:
              title: Review the launch plan
      responses:
        '200':
          description: Idempotent replay of the same command
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkCommandResponse'
              example:
                data:
                  taskId: 7fbb727d-17c4-4bc7-9fc7-60eb15e9314d
                  receiptId: 7ab98058-f221-49cc-8aa4-d3d8040249b8
                  eventId: 405a3742-f821-4147-b527-91c79b676967
                  aggregateVersion: 1
                  eventHash: >-
                    sha256:a000000000000000000000000000000000000000000000000000000000000000
                  duplicate: false
                  task:
                    id: 7fbb727d-17c4-4bc7-9fc7-60eb15e9314d
                    title: Review the launch plan
                    status: todo
                    updated_at: '2026-08-18T18:30:00.000Z'
                  receipt:
                    id: 7ab98058-f221-49cc-8aa4-d3d8040249b8
                    status: completed
                    summary: Review the launch plan
                meta:
                  apiVersion: '1'
                  workspaceId: 5be1076d-8fd0-4c0f-847f-fd67fdb935e8
                  duplicate: false
        '201':
          description: Work item and receipt created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkCommandResponse'
              example:
                data:
                  taskId: 7fbb727d-17c4-4bc7-9fc7-60eb15e9314d
                  receiptId: 7ab98058-f221-49cc-8aa4-d3d8040249b8
                  eventId: 405a3742-f821-4147-b527-91c79b676967
                  aggregateVersion: 1
                  eventHash: >-
                    sha256:a000000000000000000000000000000000000000000000000000000000000000
                  duplicate: false
                  task:
                    id: 7fbb727d-17c4-4bc7-9fc7-60eb15e9314d
                    title: Review the launch plan
                    status: todo
                    updated_at: '2026-08-18T18:30:00.000Z'
                  receipt:
                    id: 7ab98058-f221-49cc-8aa4-d3d8040249b8
                    status: completed
                    summary: Review the launch plan
                meta:
                  apiVersion: '1'
                  workspaceId: 5be1076d-8fd0-4c0f-847f-fd67fdb935e8
                  duplicate: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '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:
    CreateWorkCommandRequest:
      type: object
      additionalProperties: false
      required:
        - title
      properties:
        workspace_id:
          type: string
          format: uuid
        command_id:
          type: string
          format: uuid
        title:
          type: string
          minLength: 1
          maxLength: 240
        description:
          type:
            - string
            - 'null'
          maxLength: 4000
        initiative_id:
          type: string
          format: uuid
        workstream_id:
          type: string
          format: uuid
        milestone_id:
          type: string
          format: uuid
        priority:
          type: string
          enum:
            - low
            - medium
            - high
            - urgent
          default: medium
        due_date:
          type:
            - string
            - 'null'
          format: date
        metadata:
          type: object
          additionalProperties: true
        estimated_cost_cents:
          type: integer
          minimum: 0
          default: 0
        causation_id:
          type:
            - string
            - 'null'
          format: uuid
        correlation_id:
          type:
            - string
            - 'null'
          format: uuid
      description: >-
        Send a title to use the workspace Inbox. Supply all three hierarchy IDs
        together only when you need explicit placement.
    WorkCommandResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: object
          required:
            - taskId
            - receiptId
            - eventId
            - aggregateVersion
            - eventHash
            - duplicate
            - task
            - receipt
          properties:
            taskId:
              type: string
              format: uuid
            receiptId:
              type: string
              format: uuid
            eventId:
              type: string
              format: uuid
            aggregateVersion:
              type: integer
              minimum: 1
            eventHash:
              type: string
            duplicate:
              type: boolean
            task:
              type: object
              additionalProperties: true
            receipt:
              type: object
              additionalProperties: true
        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
  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'
    Forbidden:
      description: The caller is authenticated but cannot command this workspace
      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'
    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

````