Authentication

Every call carries an API key in the Authorization header:

Authorization: Bearer hk_live_...

A key belongs to one account. Keys start with hk_live_ or hk_test_, which says which environment they are for. A key is shown once, when it is created, and Himmel keeps only a hash of it: a lost key cannot be shown again. Create a new one and revoke the old. Your account's admins and engineers make and revoke keys in the console, under Settings, API keys — see Making and revoking keys.

The rule-set catalogue is the one part of the API readable without a key. See Rule sets.

GET /v1/me says which account a key belongs to, whether it is live or a test key, and the scopes it carries. The account comes with country, where your company is established (an ISO 3166-1 code such as US, AE or DE), and currency, the currency your books are kept in (an ISO 4217 code). Both are set when your account is opened, and the currency is never taken from the country: a company may keep its books in another. An account opened by signing up says the terms its person accepted, in terms.

Opening your account

Sign up in the console and open your company's account yourself, on Home: you are its first admin, and its first two keys are shown to you there, once.

• GET /v1/terms needs no key: Himmel's terms in force, version and text. A version is never changed once published. sign_up says whether accounts are opened here: open, or closed until Himmel's terms are published, when opening one is 503 sign-up-closed.
• POST /v1/me/account is for a person signed in to the console whom no account has added yet; a key never opens an account. It takes account - name, your company's; slug, a short name of 2 to 40 lower-case letters, digits and _, beginning with a letter, which names your account's own rule sets (policy.<slug>.<name>); country, where your company is established; currency, the one your books are kept in; and retention_years, how many years your records must be kept by your country's law, from 1 to 30 - with name, yours, where Clerk holds none for you, and terms, the version you accept. The API document lists every country and currency it takes.
• The account opens with live and test. You are its admin; its matching rules wait for you to confirm them, as everything in it does before it answers. Its live key and its test key, each shown once, hold what a system that acts needs - check, checks:read, checks:write and rules:read - and neither confirms a rule or posts a policy: an admin makes a key that does on purpose, in Settings.
• Refused, with nothing opened: a person in an account already (409, another_account: one person, one account), a slug another account has (409, taken), a value that is not as described (422, naming the field), the terms a version other than the one in force (422, not_in_force), and the accounts opened in a day - at most 50 for all of Himmel and 5 from one network address (429 rate-limited, with Retry-After saying in how many seconds the next can be opened). A retry with the same Idempotency-Key gets the same account, its keys' key null, and counts nothing.

Accounts for your customers

If your agents act for your customers - an AI support agent for online shops, say - open an account for each customer you serve: theirs, its owner confirming its rules, you acting there as its builder and no further. Every call needs accounts, which an admin's and an engineer's roles hold - signed in, never with a key. See Accounts for your customers.

An account a builder opened for you

If a company whose agents act for you opened your account - its builder - you are its owner. You join by taking its invitation up, signed in, accepting Himmel's terms for the account as you do - terms on the accept, the version GET /v1/me/invitations names - and you own its agents here from then: you switch any of them off, in one step. GET /v1/me names the company that opened your account (opened_by), and your agents and keys say which are its (builder). It registers its agents here and makes and revokes their keys, sends your invitation again until you join, and posts your playbook from Himmel's template; it never confirms a rule, switches a playbook on, changes a setting, names anybody or decides anything here. An admin of your account can cut it off - POST /v1/builder/cut-off, from then and for good: it acts in your account no more, and reads nothing more of it. Its agents and their keys stay as they are: switch each agent off, or revoke its keys, in a step of its own.

Live and test

Every account has two environments, live and test, and a key acts in its own. The database keeps what happens in one apart from the other: a booking, a check, a sign-off, an alert and a recipient each belong to the environment they were made in, and a request never sees the other's. A gift sent with a test key never counts toward a live recipient's yearly total, and a test key cannot read, report on or sign off a live answer. An answer given in test carries "sandbox": true; a live answer has no such field.

What your company has decided belongs to the account, and both environments read it: the rules your owner confirmed, your settings and your policies. A check in test therefore gets the answer a live one would. They are changed from live. With a test key, confirming rules, changing a setting or writing a policy is refused with 403 live-only, so a test key that leaks cannot change a live answer.

The sandbox account holds test data only: its keys are test keys, and it changes its own settings from test. GET /v1/me says so, with account.test_only.

In the console you act in live unless you switch to test, and the console then sends Himmel-Env: test with your requests. A key never needs the header, because it has an environment already; a Himmel-Env that disagrees with the key is refused.

Keys are for software, sign-in is for people

Keys are for your software and your agents. People sign in to the console, and what they may do follows from their role in your account rather than from a key. That difference shows in the record: a request made with a key can only name the person it acts for, and the record keeps who it named as the key's claim. Someone signed in has shown who they are, so a rule confirmed in the console is recorded against that person.

It shows in what comes back, too. Recipient names are shown only to people — admins and ops, signed in to the console — and a key is given recipient ids, whatever its scopes. See Recipients.

Naming a person

Five fields say who did something: by_user, confirmed_by, decided_by, resolved_by and acknowledged_by. With a key, each takes the Himmel id of a person in your account — everyone's is on the console's People page, under Settings, and your own on Developers — whose role could have done it themselves: only an admin confirms rules, for instance. Anything else is refused with 422 invalid-request, and errors says why: unknown_user when nobody in your account has that id (a name never is one), role_cannot when their role could not have done it. The refusal never repeats what you sent. Leave a field out when nobody in particular acted; resolved_by is the exception, because a resolution is somebody's decision. A key made for an agent names nobody but itself: any of these fields from it is refused with 422 invalid-request and not_the_keys, and it records no resolution at all (403 cannot-decide).

Signed in to the console, leave them out: it is you, and naming anybody else is refused (not_the_signed_in_person).

transaction.actor.on_behalf_of is different. The person an agent acts for needs no account here, so it takes your own systems' id for them — never a name or an email address.

Scopes

A key carries scopes, and each endpoint needs one. The reference for every endpoint says which.

A key without the scope an endpoint needs gets 403 with the problem type insufficient-scope, naming the scope it needed (required_scope) and the ones it has (scopes). confirm and policies:write change what your account has decided, so outside the sandbox they work with a live key only.

Four more scopes belong to people alone, and no key can hold them: keys, making and revoking keys, which an admin's and an engineer's roles hold; people, inviting colleagues, changing a role, removing somebody and cutting off the builder that opened your account, which only an admin's holds; agents, registering your agents, changing them and switching them off and on, which an admin's and an engineer's hold - and an agent's owner switches it off and on whatever their role; and accounts, opening accounts for your customers and acting in them as their builder, which an admin's and an engineer's hold.

A key of its own for every agent

An agent that acts for your company gets its own key, never a person's. It is registered first - see Your agents - and an admin or an engineer then makes its key in the console, for that agent, named by the id it was registered under (agt_travel_ops); it is shown once. The key identifies the agent, and every check it sends records that agent, whatever the request says — so a rule of yours that turns on who acts, "an agent refunds up to €30 on its own", reads what the key is. In the request, the agent names the person it acts for:

"transaction": {
  "status": "proposed",
  "actor": { "on_behalf_of": "emp_4f1c" }
}

It may repeat its own kind and id, and naming any other is refused with 422 invalid-request (not_the_keys). GET /v1/me says, under caller.actor, which agent a key acts as.

An agent's key carries only what an agent needs: check, checks:read, checks:write and rules:read. It asks before it acts, reports what became of its own actions, and reads what concerns its own agent alone: its answers, the requests Himmel made about them, the alerts about them, its record, its runs and the rules it is held to. Another agent's action or request is 403 not-the-agents-action, another agent's record 403 insufficient-scope, and so is anything your whole account holds - the register of agents, your people, settings, policies and their documents, confirmations, the review queue, who is who and the templates (agent_key); the rule catalogue it reads as anybody does, the law's rule sets alone, and your playbooks' worked examples it is served with itself acting, to try it with. So a key that leaks, or an agent talked into misusing its key, reads its own agent's work and nothing more. It confirms nothing and changes no setting or policy, which are your company's to do.

It speaks for itself. It names nobody: a field naming a person who did something is refused (not_the_keys), and so is a fact naming a person — who approved an action — or the figure an approval was given for, which Himmel holds for the agent (An agent never names a person); a resolution is refused whole with 403 cannot-decide — a decision is a person's, made signed in to the console or sent by your own software with one of your account's own keys. And it acts on its own actions only, those its agent took, whichever of its keys sent them: it reports on them, takes them back, completes and corrects them, and anyone else's is refused with 403 not-the-agents-action. Your account's own keys and your people act on any.

Both the agent and the person it acted for are recorded on every check. When the agent's key is replaced, the new one is made for the same agent and the record of what it did stays whole, without touching anyone's own access; to stop the agent itself, switch it off.

Your account's own keys — the two you are given when the account is opened, and any made for your own software — are tied to nobody. Your software acts for many people and agents, so it says in transaction.actor who acts in each request - an agent it names being one your account has registered, or the check is refused with 422 invalid-request (unknown_agent), so a mistyped id is never a new agent; and a person it names (kind: user) being one of your account's people, by their Himmel id - here on the day of an action taken, here now for one asked about - or 422 invalid-request (unknown_user, left_the_account), so your log never names as who acted somebody your account never had. A check that names nobody records nobody, and a rule of yours that turns on who acts answers undetermined_missing_facts with actor in missing rather than guess.

Making and revoking keys

Keys are made and revoked by a person signed in whose role holds keys — an admin, or an engineer — in the console under Settings, or through the API with their session. Never by a key: keys is a scope no key can hold, so a key that leaks cannot make more keys or revoke the ones meant to replace it.

• GET /v1/keys lists every key of your account, live and test, newest first, revoked ones too: its prefix and name, the agent it is for (or none, for your own software), what it may do, who made it (created_by, empty for one we made for you) and when it was last used, to the minute. Never the key itself.
• POST /v1/keys makes one: a name saying what it is for, agent for an agent's key - the id your account registered it under, 422 invalid-request (unknown_agent) for one it has not - env (live or test, your account's own when left out) and scopes. An agent's key may do at most what an agent does, all four when left out; a key for your own software may do anything your role may, and when left out the same four - send checks, report what became of an action, read the check log and the rules - so confirm, recipients:write and policies:write are given only by naming them. Nobody makes a key that can do more than they can: an engineer's keys never confirm, and asking for more is 403 insufficient-scope, naming the scope. The answer carries the key, hk_live_…, once: store it before you leave the page. A retry with the same Idempotency-Key gets the same key's record with key empty, never a second key; a key lost before it was stored is revoked and another made.
• POST /v1/keys/{key_id}/revoke revokes one, from now and for good: the next request with it is 401, and nothing puts it back. It is never deleted — your check log still names it as the sender of what it sent. You revoke only a key that can do no more than your role, so your account's own keys, which confirm, are an admin's to revoke.

To replace an agent's key, make the new one for the same agent, move the agent to it, then revoke the old one: the agent stays the same in every rule and in your check log. Keys belong to the account, so both calls are made from live — from test they are 403 live-only; the sandbox, which has only test, makes test keys.

Your agents

Every agent that acts for your company is registered before it acts: by its own id in your systems, what it is in words, and the person in your account who answers for it, its owner. Its keys are made for it, and your own software names only an agent you have registered. An agent is answered under every playbook of yours, as anybody is; where a playbook holds an agent tighter than a person, its own rules say so. An agent whose runtime speaks MCP adds Himmel by configuration, with its own key, and reads its rules, asks and reports through Himmel's tools: see Connect an agent by MCP.

In the console, Agents lists every agent your account has registered, registers one, changes it and switches it off and on, and shows what each reads before it starts - and whether its own keys last read what applies now - and what each did, its last actions and its runs; an agent's keys are made on its page, or under Settings, picked from the agents registered. Through the API:

• GET /v1/agents lists every agent your account has registered, in the order registered: its id, its role, its owner (a person's Himmel id), whether it is switched off (switched_off_at, switched_off_by), who registered it and when, and last_acted_at — when an action recorded as its was last asked about or taken, in the environment you ask in, whoever sent the check. That is never when one of its keys was last used, which any request sets, and sending an action's missing facts later is not acting again. And rules_read_at with rules_read — when its own key last read its rules, in the environment you ask in, and what it was given then: the versions of your rule sets, and the checksum of the text (see Rule sets). Any key or person reads it (rules:read). GET /v1/agents/{agent_id} reads one.
• GET /v1/agents/{agent_id}/runs says what it did, run by run — each task a person dispatched it to do, as its checks named it in transaction.run (see Check) — the one it acted in last first, fifty to a page (limit, before set to the last page's next_before). For each run: on_behalf_of, everybody its actions said it acted for; first_at and last_at, when its first action was asked about or taken and when its last was; actions, how many, a completion or a correction being the action it amends; answers, what the answers that stand came to, by state and outcome; statuses, what became of the actions — taken, still asked about, not taken, taken back; and checks, the check log's query that lists exactly those actions. Its actions sent with no run are counted together in without_run. It needs checks:read, as the check log does.
• GET /v1/runs lists every agent's runs at once, the one acted in last first, fifty to a page, each as an agent's runs give it, with agent, whose run it is: a run is its agent's, so two agents that name the same run are two runs. actor keeps one agent's runs or several's, separated by commas, and system the actions taken in these systems (codes, or none): a run then counts those actions alone, and its checks lists exactly them. from and to keep the runs that acted in that time — a moment, or a date at its midnight UTC — each with every action counted. Actions sent with no run are no run. Continue with before set to the last page's next_before, with the same filters. It needs checks:read, and a key made for an agent reads its own agent's runs alone.
• GET /v1/map is the map of your agents, below: who answers for each, the systems they act in, and how each of their actions was answered.
• GET /v1/agents/{agent_id}/rules gives it the rules it is held to today, in the words your rule owner confirmed, for it to read at the start of each run: see Rule sets.
• POST /v1/agents registers one: id - letters, digits and _ . : -, up to 64, never a name or an address and never beginning usr_, fixed once registered - role, one line saying what it is ("The support assistant"), and owner, the Himmel id of a person in your account, any role. An id registered already is 409 conflict (already_registered).
• PUT /v1/agents/{agent_id} changes its role and owner, both sent; never its id, which its checks record.
• POST /v1/agents/{agent_id}/switch-off switches it off, from now: every request its keys send is refused with 403 agent-switched-off, and a check asking first in its name is refused the same, whoever sends it. An action reported as taken that names it is recorded and answered as any - your books hold what happened - and nothing it did is touched. POST /v1/agents/{agent_id}/switch-on puts it back, and its keys work again. A key that leaked is revoked instead, for good.

Registering and changing an agent need agents, an admin's or an engineer's; switching one off and on is theirs, and its owner's whatever their role. Agents belong to the account, as keys do: both environments read them, and they are changed from live - from test, 403 live-only. A person who owns an agent is removed once each of their agents has another owner (409 owns-agents, listing them).

The map of your agents

GET /v1/map is one window over your agents, as the console's Home draws it: every action an agent asked about or reported on the days you choose, once, by the answer that stands - never what a person did - counted by the agent that acted, the system it was taken in and the kind of answer it came to. effective_from and effective_to are the first and last day counted, both included, as each action is dated (the day it happened): the last thirty days to today where you send neither, the thirty to the last day where you send that alone, and from the first day to today where you send that alone. actor keeps one agent's actions or several's, separated by commas, and system those taken in these systems, codes or none.

Every figure comes with checks, the check log's query that lists exactly what it counts:

• actions, every action counted;
• agents, every agent your filters keep, in the order registered - those that did nothing on those days too, with nought - each with its role, its owner and whether it is switched off;
• people, each person who answers for one of them, with theirs;
• systems, where they acted, the busiest first, none for the actions whose system nobody named;
• lines, one for each agent, system and kind of answer, and of those actions the ones taken against your rules (against_rules) and the ones waiting on an approval Himmel asked a person for (approvals_waiting), each null where there are none;
• answers, the actions of each kind;
• not_covered, the actions no rule of yours gave an answer for, approvals_waiting, those waiting on an approval - the review queue's, of these days - and against_rules, those taken against your rules, as check.against_rules is raised.

The kinds are those the check log's answer lists - allowed, approval, person, refused, other and open (Check) - and every action is of exactly one, so an agent's lines add up to the agent, a system's to the system, and every line to actions. It names people by their Himmel ids and no customer at all. It needs checks:read, as the check log does, and a key made for an agent maps its own agent alone. Nothing is drawn in it: how many agents and systems a picture shows, and which fold together, is the picture's.

People: invited, and removed

Nobody joins your account alone. An admin invites a colleague by the address they sign in with and the role they are to have; Clerk, which signs people in to Himmel, emails them the invitation, and they join by taking it up, signed in to the console. The first admin of a new account is the person who opened it by signing up, or - for an account we open with your company - is invited by us, or - for an account a builder opened for you - is its owner, whom the builder invited.

• GET /v1/people lists everybody in your account and everybody who left it: their Himmel id — what every answer that names them says — their role, when they joined, and when they left and who removed them. Any key or person reads ids and roles (rules:read); a person signed in reads names; an admin reads addresses.
• POST /v1/invitations invites a colleague: email and role (tenant_admin, tenant_engineer or tenant_ops). It runs out after seven days. Refused for an address somebody in your account signs in with, or one an invitation already waits for (409: withdraw it to send another); 503 sign-in-unavailable where Clerk could not be asked, and nothing was sent. GET /v1/invitations lists them, and POST /v1/invitations/{invitation_id}/withdraw withdraws one: nobody takes it up, and its address goes.
• GET /v1/me/invitations and POST /v1/me/invitations/{invitation_id}/accept are the invitee's: a person signed in whom no account has added yet sees the invitations sent to an address they have signed in with, and joins by taking one up. One person, one account: somebody in an account already is refused. They join with a name - name, as their colleagues know them, one line of at most 200 characters; left out, the one Clerk holds for them, or the one they left with if they were in the account before - and where there is none of these it is 422, name required: their colleagues pick them by it, to approve and to sign off.
• PUT /v1/me/name is for a person signed in who joined before a name was asked for: they give it, once. The same name again is answered as it stands; another, once they have one, is 409 (named_already). A key has no name: 403.
• POST /v1/people/{person_id}/role changes a role, from now. POST /v1/people/{person_id}/remove removes a person: nobody signs in as them again, and their address goes, while every answer, confirmation, decision and approval that names them keeps naming them, by the same id and the same name. Nobody changes their own role or removes themselves, a person a setting names — who approves, who signs off — is removed once it names somebody else (409 named-in-settings, listing the settings), and your account always keeps an admin (409 last-admin).

A person who left, invited again, comes back as themselves, under the same id. An action they approved before they left stays approved by them: a report of it, a completion or a correction sent later names them as it did. Anything new — a proposal, a setting, a decision — names somebody who is here (left_the_account otherwise). These calls are made from live, like the keys'.

Rate limits

Each key may make 600 requests a minute with a live key and 60 with a test key. A person signed in to the console may make 600 a minute, in live or in test. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Past the limit, a request gets 429 with the problem type rate-limited, and nothing is done.

When a key is refused