Policies

A policy is your company's own rule set — a policy, a playbook, an SOP: what the company allows, whose approval something needs, how often, and which cases a named person decides. Where your account has one of our law sets switched on for its country, the policy is layered after the law, and the law decides the consequences — how much of a gift is deductible, whether input VAT may be claimed. Your policy decides the rest: a lower limit, an approval above an amount, a named person for the cases a word like "appropriate" leaves open. A policy may add limits, conditions and approvals; it can never change a consequence the law decides, and where the law sets a minimum owed to someone, a policy may never pay less.

A check answers the law first and then each of your published policies for the same domain, in layers.policies. Its overall state is the first, in order of not_covered, undetermined_missing_facts, contested, determined, that any layer reached.

A policy with no law under it

Your policy runs whether or not we hold law for your country. Where we hold a law set for its domain and country, the policy sits on it; where we hold none — or your account has not switched ours on — it stands alone, and it is the whole answer: layers holds your policies and no law, the answer states no legal consequence, and not_checked says so, { "topic": "the law", … }. Check against it by naming it: "rule_set": "policy.<your account>.<name>". Law is per country: a gift your German office books is answered by German law where your account has it on, one your US office books by your policy alone, and a gift booked in one country never counts toward another's limit.

A policy that stands alone says what is allowed, what needs whose approval and what a named person decides — each citing its clause. It sets no consequence, reads nothing of the law's answer (law.…) and grants no basis: goodwill: with no law beside it, nothing can tell a legal consequence from your company's own figure. Publishing refuses each, as consequence_without_law, law_read_without_law and goodwill_without_law.

A policy for several countries, or for any, says where each check falls through jurisdiction: where your account has our law on for one of those countries, a check against the policy that names none is 422 invalid-request, since which law applies turns on it.

Writing a policy

A policy is laid out like any rule set version: ruleset.yaml, the rules under rules/, its worked examples under tests/, and the policy document it cites under sources/. Post the files, and it is stored as a draft:

curl https://api.gethimmel.com/v1/policies \
  -H "Authorization: Bearer $HIMMEL_KEY" -H "Content-Type: application/json" \
  -d '{ "files": { "ruleset.yaml": "...", "rules/020-gifts.yaml": "...", "tests/policy.tests.yaml": "...", "sources/policy-gifts.md": "..." } }'

A policy is named policy.<your account>.<name>. A draft can be edited with PUT /v1/policies/{id} until it is published; a published version never changes.

GET /v1/policies/{id} runs, now, everything publishing would: lint, the consequence check, each of the policy's own cases over the law (or on their own, for a policy that stands alone), ten cases and a worked example for every rule, and the law floor. checks.blocking lists what would stop it, and sits_on the law versions it is layered over — the law of its domain and countries your account has switched on, and empty for a policy that stands alone. drafted_from names the document it was last drafted from (null for one posted as files), filled_from the template that filled it and your values (null otherwise), and review_items what that drafting raised, with each flag of a rule that stands flagged.

Starting from a template

A policy can start as one of our templates filled with your own figures. GET /v1/templates lists them — one so far, online_shop_support: a support playbook for an online shop, saying what its support team, its people and an AI assistant that asks before it acts, may give a customer — refunds, retention discounts and goodwill credits. Each template lists its blanks, each with its measure (money, days, percent or count), the clauses that say it and the least and most it takes; the order its words put them in; its choices, each a part of the playbook you pick between its words, with its options; the settings its rules read; and its document with each blank and choice shown by its name, 2.4 A refund of up to [refund_without_approval] needs no approval.

online_shop_support has one choice, refund_above_assistant (clause 2.7): what becomes of a refund above what the AI assistant gives on its own. hand_to_a_person - the assistant hands it to the team lead, and Himmel tells the team lead; or team_lead_approval - the assistant asks the team lead's approval first, Himmel asks the team lead, and the assistant gives it once they approve; above the team lead's band, the head of support's approval, as for any refund.

Every figure is a blank and every choice yours, and Himmel proposes none: the limits are your company's. Fill each one, in your account's currency, pick each choice, and post it in place of files:

curl https://api.gethimmel.com/v1/policies \
  -H "Authorization: Bearer $HIMMEL_KEY" -H "Content-Type: application/json" \
  -d '{ "template": "online_shop_support", "values": {
        "refund_without_approval": { "amount": 10000, "currency": "USD" },
        "refund_with_team_lead": { "amount": 50000, "currency": "USD" },
        "refund_by_assistant": { "amount": 4000, "currency": "USD" },
        "refund_days": 14,
        "discount_without_approval": 10, "discount_with_team_lead": 20,
        "credit_at_most": { "amount": 2500, "currency": "USD" },
        "credits_in_window": 3, "credit_window_days": 30,
        "credits_a_year": { "amount": 10000, "currency": "USD" },
        "refund_above_assistant": "team_lead_approval" } }'

The answer is your policy, as a draft: its document saying your figures — "2.7 The AI assistant gives refunds of up to $40 on its own." — dated today, each figure written into the rule that reads it, and its worked examples worked out around your figures: at a limit, above it, within it. Your rule owner confirms each rule with its examples on the confirmation page, as for any policy; the examples are set by that confirmation, and the policy publishes once every rule is confirmed. Who approves — the team lead and the head of support — and when your financial year starts are settings, which your owner names. filled_from on the version says what filled it: the template, its version and your values - and so does each version GET /v1/policies lists. It is posted as your policy's 1.0.0, or the next version of the one you have; while a draft of it waits, posting again is 409 with that draft's policy_id, and PUT /v1/policies/{id} with template and values fills the draft again — with a figure changed, say: the rules the change reaches wait for your owner again, and the rest keep their confirmations.

A filling is refused rather than mended, each figure by values.<name> in errors: one left out (required), in another currency than your account's (other_currency), not a whole number (not_a_whole_number), outside what the blank takes (below_minimum, above_maximum), a choice left out (required) or not one of its options (not_an_option), or out of the order the template's words put them in (out_of_order, with the clauses): for online_shop_support, the team lead's approval covers refunds above what needs none, what the AI assistant gives on its own needs nobody's approval, the discounts' team-lead step is above the free one, and one credit is within a year's. A template is written in English; a playbook your owner confirms in another language is uploaded as a document instead.

Starting from a document

A policy usually starts as a document: upload it with POST /v1/policies/documents — PDF, DOCX or Markdown — and list the names in it that must not be kept, one names field each. Those names, every name your account's documents hid before, every person in your account, every word that reads as a name — a given name followed by a capitalised word, such as "Casey Wagner" — and every email address, IBAN and phone number are replaced by placeholders such as [[NAME-1]] before anything is stored; the file itself is not kept. The answer is the masked text with one anchor per clause - a PDF's running header and footer, repeated on its pages, left out - and masked, each placeholder with its kind and why: listed, person, found or shape. Read it: if a name is still there — a first name on its own, or one written in a way no list knows — hide it where it stands with POST /v1/policies/documents/{id}/names — { "names": ["Sam"] } — and it is masked in the copy that is stored, numbered after the document's own placeholders, as long as nothing has been drafted from it. A word hidden because it reads as a name, and that is none — a branch called after a city, a product — is shown again with POST /v1/policies/documents/{id}/shown — { "placeholders": ["[[NAME-3]]"] } — and the list leaves it alone in that document from then on; GET /v1/policies/documents/{id} shows each such word (value) to a person signed in who is shown names, an admin or ops, and to no key. A name you listed, a person in your account and an address stay hidden. A document you do not want, never sent to drafting, is withdrawn with POST /v1/policies/documents/{id}/withdraw: it is removed, its text with it, and the audit log keeps only that it was withdrawn and by whom. Once a document has been sent to drafting it stays as it is, since what was drafted from it cites it: upload it again with the name listed, and draft that one.

A Word document is read as Word prints it: where its clauses are in one of Word's numbered lists — 1. a section, 1.1 its clauses — they carry those numbers and become clauses, as typed numbers do; a list numbered at one level only, 1., 2. under each heading, reads as the text it sits in. Its tables are read where they stand, a row to a line and the cells joined by |, so an approval matrix is part of the text.

domain is your name for the policy's set of books — customer_support, say — short, lower case, its parts joined by dots; where the policy is to sit on one of our law sets, it is that law set's domain.

Drafting rules from it is an optional step: POST /v1/policies/documents/{id}/draft asks a language model to draft the rules from the masked text, and only ever the masked text — masked again as the draft is asked for, against the people in your account as they are then, so that a colleague who joined after the upload is hidden too. A document is drafted over the law your account has switched on for its domain; with none, it is drafted as your own rules standing alone — covering wherever your company acts, dated by a fact of their own, and in the currency your account keeps its books in. It takes minutes and runs as a job. A call that fails costs that call, never the draft: each reply is kept as it comes back, so a retry starts from the first call not done; an error no retry mends — the model provider refusing the server's key, or the account it drafts with out of credit — stops the drafting at once; and a drafting that stops leaves the document failed, its latest entry in drafts saying why in words (reason), and can be drafted again at once, reading the replies already back while the document reads the same. First the playbook's terms are written - what every rule and example will name: its facts, its settings, its outcomes, the questions a person decides - and checked; then two drafts are made over them, side by side, each its own way, and compared by what they answer. Where both can run an example and decide it differently, that is a review item under the rule it concerns, a few to a rule, each draft's answer under its name and chosen naming the draft your version holds; an example one of them cannot run is counted, never raised. While it runs, GET /v1/policies/documents/{id} says where it is in progress: the step - queued, terms, drafts, examples, gaps, again (a rule your owner flagged, drafted again), or waiting to try again, with when and why - since when, and each call thinking, writing and how far, or back. Before the draft reaches you it is held to what publishing will ask once every rule is confirmed: where a rule has too few examples, those alone are asked for, and each comes into the draft only once it comes out as it says - one that does not is a review item beside its rule; what would still stand in the way is listed in the drafting's entry (once_confirmed). Each example is then run again with one fact altered at a time, and an altered example a rule could not answer at all is a review item under that rule; every gap a third pass finds is one too. What a model drafts is a draft: every worked example arrives marked proposed - Himmel writes the mark, whatever the model wrote - and your rule owner sets it against the document by confirming the rule it is an example for — publishing refuses a drafted policy until each rule is confirmed, and then writes its examples as confirmed by the owner. Nothing runs until the rules are confirmed. A deployment with no model configured answers 503 drafting-not-configured, and a policy can always be written as files instead.

A rule your owner flags with a comment, on a policy drafted from its document, is drafted again by itself, alone, from the document and what they said (Confirmations): its entry in the document's drafts says again, and what came of each rule - drafted, or not_taken or skipped with why - and the document stays drafted whatever comes of it. A policy changes through its document. To change a clause the company has changed, revise the playbook, upload it, and draft it: the drafter is given the version it revises, with the document that version was drafted from, and keeps every rule whose clause did not change as it was written. Where the policy has a draft, the new drafting replaces it in place — the same version — so a rule that reads as it did, beside the same clause, keeps its confirmation; otherwise it drafts the next version. A rule is confirmed with the clause it cites, so one whose clause changed waits for your owner again even where its words did not. One document of a policy is drafted at a time: while one is, drafting another answers 409, with the document_id it waits for.

Publishing

POST /v1/policies/{id}/publish publishes a draft, or refuses with 409 policy-blocked and every finding in blocking:

• a rule that sets a consequence the law decides, named — or, for a policy that stands alone, any consequence, a reading of the law's answer, or goodwill;
• one of the policy's own cases that does not come out as it says;
• a rule reached by fewer than ten cases;
• a rule no case names as its worked example (rule_without_example) — your rule owner confirms each rule with the examples written for it, so give each one a case whose rule is its id;
• a law case where the policy would pay less than the law says is owed, naming the case and the law's rule;
• a drafted example whose rule your rule owner has not confirmed (case_source_still_proposed, naming the rule to confirm), or one that names no rule, which your owner would never read (drafted_case_names_no_rule).

A version applies from the date you say: send effective_from — { "effective_from": "2026-09-01", "changelog": "Goodwill credits capped at $15." } — and an action of that date or later is checked against it, an earlier one against the version before. A version that replaces a published one must say it (422 invalid-request, required): its own date is its document's, and a revised document often still gives the first version's. It may not be dated before the version it replaces (before_the_version_it_replaces); the same date corrects that version from the start. A date in the past is allowed: the actions since then are checked again under the new version once its rules are confirmed, and every earlier answer stays on record. A first version left without a date applies from its own, its document's.

Once published, the version before it is superseded, your admins are told, and its rules run as soon as your rule owner confirms them on the policy's confirmation page. Until then, a check that reaches one answers not_covered with awaiting_confirmation, exactly as a rule of the law would — and the answers you were given before it was published stand as they are. Once its rules are confirmed, those it applies to are checked again with the policy in them, with one checks.rerun alert. Where your policy says nothing about the facts, its layer answers not_covered with policy_gap: your policy does not say.

Trying a version

POST /v1/policies/{id}/evaluate answers facts — or a booking already stored, by its transaction_id — twice: under the law alone, and with the version layered over it, side by side. For a policy that stands alone, law_only is null and with_policy is the policy's own answer. Nothing is stored, no recipient is created, and confirmations are not applied: it shows what the rules say.

Say who acts with actor, as a check's transaction.actor says it — { "facts": { … }, "actor": { "kind": "agent", "id": "agt_refunds" } } — to see what a rule that turns on who acts makes of them; left out, it is you, as a check would record you, and an agent's own key acts as its agent. A booking already stored brings who acted and when, so it takes no actor, and it is answered as its check answered it: one that falls outside the countries of the rule set its check named is not_covered on both sides, no_rule_set_for_jurisdiction, as its check was. Otherwise the law is the one its check was answered under, the law of the country it fell in, and a version for other countries than that one is not layered on it: with_policy is not_covered, no_rule_set_for_jurisdiction, saying where the version applies, beside the law's answer. A booking of another domain than the version's is 422 invalid-request (other_domain).

GET /v1/sandbox/policy-sample returns an invented policy, labelled so in its first line, as a document and as the files it drafts to — written to hold the hard cases, including a clause that tries to say what is deductible, which publishing refuses.