> ## 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 a handoff > Create a responsibility transfer between two stages of work. ## OpenAPI ````yaml /openapi/v1.yaml post /handoffs 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: /handoffs: post: tags: - Handoffs summary: Create a handoff description: Create a responsibility transfer between two stages of work. operationId: createHandoff parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/HandoffProposalRequest' example: workspace_id: 98608ef9-3fc8-4e9a-8ae4-5f80e214cfab handoff_key: launch-plan-review from_stage_key: launch-plan-review to_stage_key: launch-plan-review title: Review the launch plan responses: '200': description: Idempotent replay of the same proposal content: application/json: schema: $ref: '#/components/schemas/HandoffMutationResponse' example: data: schemaVersion: 1.0.0 id: a5614527-0ce6-43be-8d1d-d012b7394867 workspaceId: 09707fa5-aaae-4493-8a23-827111000f89 handoffKey: launch-plan-review fromStageKey: launch-plan-review toStageKey: launch-plan-review sourceProcessRef: f54b9152-1f4b-4e01-82e7-a47fa0006734 sourceRevisionRef: 7fb481a5-15f3-4b6b-8795-221def1c9745 title: Review the launch plan summary: Launch plan reviewed with supporting evidence. priority: low slaMinutes: 1 dueAt: '2026-08-18T18:30:00.000Z' currentActor: type: human id: 2d4b7f66-3a2a-4e9d-9ad1-3b2d1b2e4101 proofRequirements: - kind: evidence required: true result: {} status: proposed createdAt: '2026-08-18T18:30:00.000Z' updatedAt: '2026-08-18T18:30:00.000Z' meta: {} '201': description: Handoff proposal appended content: application/json: schema: $ref: '#/components/schemas/HandoffMutationResponse' example: data: schemaVersion: 1.0.0 id: a5614527-0ce6-43be-8d1d-d012b7394867 workspaceId: 09707fa5-aaae-4493-8a23-827111000f89 handoffKey: launch-plan-review fromStageKey: launch-plan-review toStageKey: launch-plan-review sourceProcessRef: f54b9152-1f4b-4e01-82e7-a47fa0006734 sourceRevisionRef: 7fb481a5-15f3-4b6b-8795-221def1c9745 title: Review the launch plan summary: Launch plan reviewed with supporting evidence. priority: low slaMinutes: 1 dueAt: '2026-08-18T18:30:00.000Z' currentActor: type: human id: 2d4b7f66-3a2a-4e9d-9ad1-3b2d1b2e4101 proofRequirements: - kind: evidence required: true result: {} status: proposed createdAt: '2026-08-18T18:30:00.000Z' updatedAt: '2026-08-18T18:30:00.000Z' meta: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '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: HandoffProposalRequest: type: object additionalProperties: false required: - workspace_id - handoff_key - from_stage_key - to_stage_key - title properties: workspace_id: type: string format: uuid handoff_id: type: string format: uuid handoff_key: type: string from_stage_key: type: string to_stage_key: type: string source_process_ref: type: - string - 'null' format: uuid source_revision_ref: type: - string - 'null' format: uuid title: type: string summary: type: - string - 'null' priority: type: string enum: - low - normal - high - urgent default: normal sla_minutes: type: - integer - 'null' minimum: 1 due_at: type: - string - 'null' format: date-time proof_requirements: type: array items: type: object HandoffMutationResponse: type: object additionalProperties: false required: - data - meta properties: data: $ref: '#/components/schemas/Handoff' meta: $ref: '#/components/schemas/HandoffLedgerMeta' Handoff: type: object additionalProperties: false required: - schemaVersion - id - workspaceId - handoffKey - fromStageKey - toStageKey - sourceProcessRef - sourceRevisionRef - title - summary - priority - slaMinutes - dueAt - currentActor - proofRequirements - result - status - createdAt - updatedAt properties: schemaVersion: type: string const: 1.0.0 id: type: string format: uuid workspaceId: type: string format: uuid handoffKey: type: string pattern: ^[a-z][a-z0-9_-]*$ fromStageKey: type: string toStageKey: type: string sourceProcessRef: type: - string - 'null' format: uuid sourceRevisionRef: type: - string - 'null' format: uuid title: type: string summary: type: - string - 'null' priority: type: string enum: - low - normal - high - urgent slaMinutes: type: - integer - 'null' minimum: 1 dueAt: type: - string - 'null' format: date-time currentActor: oneOf: - $ref: '#/components/schemas/ActorRef' - type: 'null' proofRequirements: type: array items: type: object result: oneOf: - type: object - type: 'null' status: type: string enum: - proposed - claimed - returned - fulfilled - escalated - cancelled createdAt: type: string format: date-time updatedAt: type: string format: date-time HandoffLedgerMeta: allOf: - $ref: '#/components/schemas/ContractMeta' - type: object properties: duplicate: type: boolean aggregateVersion: type: integer minimum: 1 projectionStatus: type: string const: ledger_replay 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 ActorRef: type: object additionalProperties: false required: - type - id properties: type: type: string enum: - human - agent - service - external_agent - system id: type: string ContractMeta: type: object additionalProperties: false required: - apiVersion - workspaceId properties: apiVersion: type: string const: '1' workspaceId: type: string format: uuid count: type: integer minimum: 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' 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 ````