> ## 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. # Preview or execute an initiative launch > Turn a committed plan into running work. This is the one operation on the API that spends your provider budget, so it is deliberately two calls. ### Preview first `mode: "preview"` returns the plan, the targets, the block reasons, and `server_estimate_cents` — and dispatches nothing. No agent starts, no reservation is written, no spend occurs. Send the returned `launch_plan_digest` back with `mode: "execute"` to run exactly the plan you were shown; a plan that drifted returns `409 launch_plan_stale`. ### The estimate is ours, the ceiling is yours `cost_ceiling_cents` is your upper bound. OrgX computes the estimate server-side from the resolved model tier and a conservative token budget, and refuses with `422 cost_ceiling_below_estimate` when your ceiling is under it — the launch is refused whole rather than trimmed to fit. A tier with no server-side price returns `422 cost_unestimable`. ### Scope and autonomy Every id in `scope` is checked against your workspace and the named initiative before anything reaches the dispatcher; an id outside either is reported exactly like an id that was never issued. `autonomy_ceiling` lowers the effective autonomy for this launch and can never raise it above your workspace or initiative policy. ### Execution is asynchronous A successful execute returns `202` with a `launch_id` and one entry per target. Targets fail independently — poll `GET /launches/{launchId}` for jobs, runs, receipts, and spend to date. Rate limited to 6 launches per hour per credential. ## OpenAPI ````yaml /openapi/v1.yaml post /launches 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: /launches: post: tags: - Launches summary: Preview or execute an initiative launch description: >- Turn a committed plan into running work. This is the one operation on the API that spends your provider budget, so it is deliberately two calls. ### Preview first `mode: "preview"` returns the plan, the targets, the block reasons, and `server_estimate_cents` — and dispatches nothing. No agent starts, no reservation is written, no spend occurs. Send the returned `launch_plan_digest` back with `mode: "execute"` to run exactly the plan you were shown; a plan that drifted returns `409 launch_plan_stale`. ### The estimate is ours, the ceiling is yours `cost_ceiling_cents` is your upper bound. OrgX computes the estimate server-side from the resolved model tier and a conservative token budget, and refuses with `422 cost_ceiling_below_estimate` when your ceiling is under it — the launch is refused whole rather than trimmed to fit. A tier with no server-side price returns `422 cost_unestimable`. ### Scope and autonomy Every id in `scope` is checked against your workspace and the named initiative before anything reaches the dispatcher; an id outside either is reported exactly like an id that was never issued. `autonomy_ceiling` lowers the effective autonomy for this launch and can never raise it above your workspace or initiative policy. ### Execution is asynchronous A successful execute returns `202` with a `launch_id` and one entry per target. Targets fail independently — poll `GET /launches/{launchId}` for jobs, runs, receipts, and spend to date. Rate limited to 6 launches per hour per credential. operationId: createLaunch parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LaunchRequest' example: workspace_id: 5be1076d-8fd0-4c0f-847f-fd67fdb935e8 initiative_id: 4b014796-6b1e-4a4f-9a35-2b6a4d1c8a10 expected_aggregate_version: 3 mode: execute scope: workstream_id: 9c1f2e77-3c58-4a1e-9d0b-6a2f8e4b1c33 launch_plan_digest: >- sha256:9f2c1b8a7d6e5f4c3b2a1908f7e6d5c4b3a2918077665544332211009988aabb cost_ceiling_cents: 1000 max_parallel_agents: 2 model_tier: balanced responses: '200': description: >- The launch plan and its server-computed estimate; nothing was dispatched content: application/json: schema: $ref: '#/components/schemas/LaunchPreviewResponse' example: data: launch_plan_digest: >- sha256:9f2c1b8a7d6e5f4c3b2a1908f7e6d5c4b3a2918077665544332211009988aabb expires_at: '2026-08-19T21:10:00.000Z' dispatchable: true targets: - workstream_id: 9c1f2e77-3c58-4a1e-9d0b-6a2f8e4b1c33 name: Engineering domain: engineering status: not_started dispatchable: true block_reasons: [] block_reasons: [] server_estimate_cents: 500 estimate_basis: conservative_tier_default resolved_model: claude-sonnet-5 autonomy: effective_mode: gated bound_by: workspace request_would_have_raised: false expected_aggregate_version: 3 meta: apiVersion: '1' workspaceId: 5be1076d-8fd0-4c0f-847f-fd67fdb935e8 mode: preview dispatched: false idempotency_key: result: not_evaluated '202': description: The launch was accepted and dispatched to its targets content: application/json: schema: $ref: '#/components/schemas/LaunchExecuteResponse' example: data: launch_id: 1d2c3b4a-5e6f-4a7b-8c9d-0e1f2a3b4c5d state: dispatched aggregateVersion: 2 eventId: 7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d jobs: - workstream_id: 9c1f2e77-3c58-4a1e-9d0b-6a2f8e4b1c33 job_id: 3f4e5d6c-7b8a-4901-a2b3-c4d5e6f70819 status: dispatched block_code: null reservation_receipt_ids: - 8c7b6a59-4d3e-4f21-a0b9-c8d7e6f5a4b3 server_estimate_cents: 500 capacity: workspace_spent_today_cents: 120 workspace_slice_cents: 2500 global_cap_cents: 5000 active_workspaces_today: 2 meta: apiVersion: '1' workspaceId: 5be1076d-8fd0-4c0f-847f-fd67fdb935e8 mode: execute dispatched: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': description: The launch would exceed the workspace spend cap content: application/json: schema: $ref: '#/components/schemas/ApiError' '403': description: The credential lacks the launch:execute scope content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': $ref: '#/components/responses/NotFound' '409': description: The initiative or the plan changed since it was read content: application/json: schema: $ref: '#/components/schemas/ApiError' '422': description: >- The launch is blocked, unpriceable, over its ceiling, or missing a workspace budget content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: >- Launch rate limit or the workspace's share of shared daily capacity is exhausted 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: LaunchRequest: type: object required: - workspace_id - initiative_id - expected_aggregate_version properties: workspace_id: type: - string - 'null' format: uuid initiative_id: type: string format: uuid expected_aggregate_version: type: integer minimum: 0 description: The initiative version you read. A mismatch returns 409. mode: type: string enum: - preview - execute default: preview scope: $ref: '#/components/schemas/LaunchScope' launch_plan_digest: type: string description: Required on execute. The digest returned by your preview. cost_ceiling_cents: type: integer minimum: 1 description: >- Required on execute. Your UPPER BOUND, never the estimate — OrgX computes that. max_parallel_agents: type: integer minimum: 1 maximum: 4 default: 1 model_tier: type: string enum: - standard - balanced - precision - local default: standard autonomy_ceiling: type: string enum: - manual - gated - autopilot description: >- Lowers the effective autonomy for this launch; it can never raise it above policy. LaunchPreviewResponse: type: object required: - data - meta properties: data: type: object properties: launch_plan_digest: type: string expires_at: type: string format: date-time dispatchable: type: boolean targets: type: array items: $ref: '#/components/schemas/LaunchTarget' block_reasons: type: array items: $ref: '#/components/schemas/LaunchBlockReason' server_estimate_cents: type: integer estimate_basis: type: string enum: - computed - conservative_tier_default resolved_model: type: string autonomy: $ref: '#/components/schemas/LaunchAutonomy' expected_aggregate_version: type: integer meta: type: object properties: apiVersion: type: string workspaceId: type: string format: uuid mode: type: string dispatched: type: boolean description: >- Always false on a preview. Stated because "preview" is a promise about spending. idempotency_key: type: object properties: result: type: string LaunchExecuteResponse: type: object required: - data - meta properties: data: type: object properties: launch_id: type: string format: uuid state: type: string enum: - dispatched aggregateVersion: type: integer eventId: type: string format: uuid jobs: type: array items: $ref: '#/components/schemas/LaunchJob' reservation_receipt_ids: type: array items: type: string format: uuid server_estimate_cents: type: integer capacity: $ref: '#/components/schemas/LaunchCapacity' meta: type: object properties: apiVersion: type: string workspaceId: type: string format: uuid mode: type: string dispatched: 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 LaunchScope: type: object description: >- Narrows the launch. Every id is checked against your workspace and the named initiative first. properties: workstream_id: type: string format: uuid nullable: true task_id: type: string format: uuid nullable: true LaunchTarget: type: object properties: workstream_id: type: string format: uuid name: type: string nullable: true domain: type: string nullable: true status: type: string nullable: true dispatchable: type: boolean block_reasons: type: array items: $ref: '#/components/schemas/LaunchBlockReason' LaunchBlockReason: type: object properties: code: type: string message: type: string severity: type: string overrideable: type: boolean LaunchAutonomy: type: object properties: effective_mode: type: string enum: - manual - gated - autopilot bound_by: type: string enum: - workspace - initiative - request request_would_have_raised: type: boolean description: >- True when the requested ceiling was above policy and was therefore ignored. LaunchJob: type: object properties: workstream_id: type: string format: uuid nullable: true job_id: type: string format: uuid nullable: true status: type: string nullable: true block_code: type: string nullable: true LaunchCapacity: type: object properties: workspace_spent_today_cents: type: integer workspace_slice_cents: type: integer global_cap_cents: type: integer active_workspaces_today: type: integer 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 ````