Harumi API

Read your projects' runs and outputs, and start or cancel runs, from your own systems using an API key.

Overview

The Harumi API lets a system of yours work with your projects without a person signing in: a scheduled job that pulls the latest results into a dashboard, a pipeline that starts a run when new data lands, or a service that waits for a run to finish and then downloads its files.

You authenticate with an API key that you create in the platform. Each key reaches only the projects you pick, can only do what you allow, and never does more than you can do yourself.

Looking for interactive access instead?

This API is for systems calling in with a static key. If you're a platform user running code and fetching your own results, use the harumi CLI instead — it authenticates as you and has no relation to the API keys described here. Keys for your own AI models (OpenAI, Anthropic) are a different thing, under Settings → Your models.

Create a key

Turn on two-factor authentication. Creating, editing and rotating a key asks for a code from your authenticator app. In Settings → My Account, open Two-factor authentication and click Turn on. If you skip this, Harumi walks you through it the first time you create a key.

Open Settings → API Keys and click Create API key.

Give the key a Name, tick its Permissions, pick the Workspace, tick the Projects it may reach, and choose when it Expires.

Click Create key, then copy the key. It is shown once: it can't be retrieved again, only rotated.

Back on the API Keys tab each key shows its projects, permissions, expiry and when it was last used. You can change a key at any time:

Edit its name, permissions and projects. The secret, expiry and workspace stay as they are.
Rotate it to get a new secret. The old one stops working immediately, so update whatever uses it.
Revoke it to end its access for good.

What a key can do

A key has one or more permissions:

Permission	Lets the key	Endpoints
Read run outputs	List runs, read a run's status and logs, and download its output files.	`GET` endpoints
Start and cancel runs	Start a run of the project's committed `harumi.toml` on a branch, and cancel a run in progress.	`POST` endpoints

Every key also lists the projects it reaches, all in one workspace: either one organization, or your personal projects. A key can reach up to 50 projects, and you can have up to 25 active keys.

A key acts as you

A key is you, without a browser. That sets its limits:

It never exceeds your access. If you lose access to a project — you leave the organization, you're made a viewer, or the project is deleted — the key stops working on it, with no need to find and revoke it.
Runs are billed to you, and count toward your plan like runs you start yourself. A workspace without an active plan is read-only, so its keys can read but can't start runs.
One run at a time. The limit of one run in progress per person applies across the platform and the API together.
A run uses harumi.toml as committed. A key can't override the command or the kernel, so it can only run what the project already says to run.

Authentication

Every request needs an Authorization header with a key prefixed pk_:

Authorization: Bearer pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Requests without this header, with a malformed value, or with an unknown, expired or revoked key get back 401 Unauthorized. Keys expire — 30, 90, 180 or 365 days after you create them — so rotate a key before its date.

Limits

Limits apply per key, not per IP address.

Requests	Limit
Reads (`GET`)	120 per minute
Starting or cancelling a run (`POST`)	20 per minute

Going over a limit returns 429 Too Many Requests.

Keeping keys safe

Store a key like a password: in your system's secret store, never in code or in a repository.
Give each integration its own key, with only the permissions and projects it needs. A leaked key then costs you one integration, not everything.
If a key leaks, Revoke it from Settings → API Keys. Revoking doesn't ask for two-factor authentication, so it is always one click away.

Errors

Status	Meaning
`401`	Missing, malformed, unknown, expired or revoked key.
`402`	The workspace has no active plan, or a plan limit is reached.
`403`	The key doesn't have the permission the endpoint needs.
`404`	The project or run doesn't exist, isn't one of the key's projects, or you no longer have access to it. These are indistinguishable on purpose.
`409`	The project has no repository yet.
`422`	`harumi.toml` is missing or invalid at that branch or commit.
`429`	Too many requests, or you already have a run in progress.
`500`	Error reading files from storage.

See the endpoint reference for every request and response.

On this page