Endpoint reference

Overview

Base URL: https://api.harumi.io/api/external/projects

All endpoints need an API key in the Authorization header. Replace <PROJECT_ID> and <RUN_ID> with the ids of one of the key's projects and one of its runs.

Find your projects

GET /api/external/projects

The projects the key can reach right now, with their ids. Projects you've lost access to are left out.

curl https://api.harumi.io/api/external/projects \
  -H "Authorization: Bearer pk_..."

[{ "id": "223e4567-e89b-12d3-a456-426614174000", "name": "Routing" }]

Read runs

curl "https://api.harumi.io/api/external/projects/<PROJECT_ID>/runs?status=completed&limit=10" \
  -H "Authorization: Bearer pk_..."

Run

The list and latest endpoints return run objects:

Fetching a single run adds the captured output:

Files

The files endpoint returns the run's id, status, started and ended, plus a files array:

{
  "id": "01J...",
  "status": "completed",
  "started": "2026-08-01T12:00:00Z",
  "ended": "2026-08-01T12:03:14Z",
  "files": [
    {
      "name": "results/output.csv",
      "extension": "csv",
      "size": 4021,
      "url": "https://...s3...&X-Amz-Expires=3600"
    }
  ]
}

Each file's url is a presigned download link valid for 1 hour. If the run didn't produce output files, files is an empty array.

Start a run

POST /api/external/projects/{project_id}/runs

Queues a run of the project's committed harumi.toml, billed to the key's creator. The command and kernel come from that file; they can't be overridden.

curl -X POST https://api.harumi.io/api/external/projects/<PROJECT_ID>/runs \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{"branch": "main"}'

A successful call returns 202 Accepted. Use project_run_id to follow the run with the read endpoints above:

{
  "status": "queued",
  "project_run_id": "01J...",
  "workflow_run_id": "wf_...",
  "execution_log_id": "01J..."
}

execution_log_id repeats project_run_id for older clients; use project_run_id.

A run can be refused before it starts: 402 if the workspace has no active plan or a limit is reached, 429 if you already have a run in progress, and 422 if harumi.toml is missing or invalid at that ref. See Errors.

Cancel a run

POST /api/external/projects/{project_id}/runs/{run_id}/cancel

Stops a run that is queued or running and returns the run. A key can cancel the runs its creator started, or any run in a project the creator owns. 403 otherwise; 409 if the run already finished.

curl -X POST https://api.harumi.io/api/external/projects/<PROJECT_ID>/runs/<RUN_ID>/cancel \
  -H "Authorization: Bearer pk_..."