skills/kora-cli/references/http-api.md

# Platform HTTP API

The live OpenAPI document is the source of truth:

```sh
curl -fsS "$BASE_URL/api/v1/openapi.json" -o kora-openapi.json
```

Use that exact path. Do not probe `/openapi`, `/swagger`, or `/api/openapi`;
the web app may return the SPA shell as HTTP 200 for unknown browser paths. If
OpenAPI and skill prose disagree, trust OpenAPI.

## Authentication

Organization API keys authenticate product API calls with:

```http
Authorization: Bearer <api-key-secret>
```

The key secret is returned once. Store it server-side only; never put it in
browser JavaScript, URLs, logs, workflow state, or checked-in files.

Use the least role that supports the app:

| Role | Use for |
| --- | --- |
| `viewer` | Read runs and run state. |
| `member` | Start workflows, complete tasks, and read runtime state. |
| `admin` | Manage keys, secrets, deployments, and other operational settings. |

## Start And Poll A Workflow

Only deployed workflows are callable.

```http
POST /api/v1/orgs/{orgId}/workflows/{workflowName}/runs
```

Body shape:

```json
{
  "environment": "production",
  "idempotencyKey": "customer-request-123",
  "inputData": {},
  "startEvent": {
    "type": "message",
    "name": "start-event-name"
  }
}
```

Use `startEvent.type: "manual"` for manual starts. For message starts, include
the workflow start event name. Use `idempotencyKey` for retryable client
requests. The `201` response includes `started.runId`.

Poll with:

```http
GET /api/v1/orgs/{orgId}/runs/{runId}
GET /api/v1/orgs/{orgId}/runs/{runId}/export
POST /api/v1/orgs/{orgId}/runs/{runId}/save
GET /api/v1/orgs/{orgId}/runs/{runId}/state
```

Use run detail for status and failure summaries. Use export to materialize the
retained run event ledger as source JSON files, and save to pin retained run
evidence in place so retention does not sweep it. Keep polling while status is
running or unknown; terminal statuses include `COMPLETED` and `FAILED`.

The run-state response is wrapped:

```json
{
  "runId": "kora-example-run",
  "state": {
    "variables": {
      "randomNumber": 7
    }
  }
}
```

Workflow result fields are workflow-specific; service `resultMapping` output
appears under `response.state` for direct HTTP callers. Confirm the expected
field path with the workflow source or `kora run state <run-id> --json`.