Preview or execute an initiative launch

curl --request POST \
  --url https://useorgx.com/api/v1/launches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "workspace_id": "5be1076d-8fd0-4c0f-847f-fd67fdb935e8",
  "initiative_id": "4b014796-6b1e-4a4f-9a35-2b6a4d1c8a10",
  "expected_aggregate_version": 3
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workspace_id: '5be1076d-8fd0-4c0f-847f-fd67fdb935e8',
    initiative_id: '4b014796-6b1e-4a4f-9a35-2b6a4d1c8a10',
    expected_aggregate_version: 3
  })
};

fetch('https://useorgx.com/api/v1/launches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://useorgx.com/api/v1/launches"

payload = {
    "workspace_id": "5be1076d-8fd0-4c0f-847f-fd67fdb935e8",
    "initiative_id": "4b014796-6b1e-4a4f-9a35-2b6a4d1c8a10",
    "expected_aggregate_version": 3
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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"
    }
  }
}

{
  "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
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

Launches

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.

POST

launches

Preview or execute an initiative launch

curl --request POST \
  --url https://useorgx.com/api/v1/launches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "workspace_id": "5be1076d-8fd0-4c0f-847f-fd67fdb935e8",
  "initiative_id": "4b014796-6b1e-4a4f-9a35-2b6a4d1c8a10",
  "expected_aggregate_version": 3
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workspace_id: '5be1076d-8fd0-4c0f-847f-fd67fdb935e8',
    initiative_id: '4b014796-6b1e-4a4f-9a35-2b6a4d1c8a10',
    expected_aggregate_version: 3
  })
};

fetch('https://useorgx.com/api/v1/launches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://useorgx.com/api/v1/launches"

payload = {
    "workspace_id": "5be1076d-8fd0-4c0f-847f-fd67fdb935e8",
    "initiative_id": "4b014796-6b1e-4a4f-9a35-2b6a4d1c8a10",
    "expected_aggregate_version": 3
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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"
    }
  }
}

{
  "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
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

Authorizations

Authorization

string

header

required

OrgX API key, sent as Authorization: Bearer oxk_...

Headers

Idempotency-Key

string

required

Workspace-scoped retry key for safe mutation replay.

Required string length: 1 - 200

Pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$

Body

application/json

workspace_id

string<uuid> | null

required

initiative_id

string<uuid>

required

expected_aggregate_version

integer

required

The initiative version you read. A mismatch returns 409.

Required range: x >= 0

mode

enum<string>

default:preview

Available options:

preview,

execute

scope

object

Narrows the launch. Every id is checked against your workspace and the named initiative first.

Show child attributes

launch_plan_digest

string

Required on execute. The digest returned by your preview.

cost_ceiling_cents

integer

Required on execute. Your UPPER BOUND, never the estimate — OrgX computes that.

Required range: x >= 1

max_parallel_agents

integer

default:1

Required range: 1 <= x <= 4

model_tier

enum<string>

default:standard

Available options:

standard,

balanced,

precision,

local

autonomy_ceiling

enum<string>

Lowers the effective autonomy for this launch; it can never raise it above policy.

Available options:

manual,

gated,

autopilot

Response

The launch plan and its server-computed estimate; nothing was dispatched

data

object

required

Show child attributes

Getting Started

Connect Your Tools

Agent Ops

Platform

Build with the API

REST API v1 Reference

Entity Reference

Content Studio API

MCP and Plugins

Resources

Preview or execute an initiative launch

Preview first

The estimate is ours, the ceiling is yours

Scope and autonomy

Execution is asynchronous

Authorizations

Headers

Body

Response