{"authentication":"Authenticate with a session cookie from POST /api/login, or a machine token as `Authorization: Bearer <token>`.","operations":[{"access":"open","method":"POST","name":"session.login","path":"/api/login","summary":"Exchange an operator's email and password for a session cookie."},{"access":"open","method":"GET","name":"control.health","path":"/api/health","summary":"The orchestrator's own liveness, and whether it can reach its database."},{"access":"read","method":"POST","name":"session.logout","path":"/api/logout","summary":"End this session everywhere by deleting its row."},{"access":"read","method":"GET","name":"session.whoami","path":"/api/whoami","summary":"The calling operator and the grants this credential holds."},{"access":"operate","method":"POST","name":"token.create","path":"/api/tokens","summary":"Mint a machine token. Shown once. Its grants may not exceed yours."},{"access":"read","method":"GET","name":"token.list","path":"/api/tokens","summary":"Machine tokens and their grants. Never the tokens themselves."},{"access":"operate","method":"DELETE","name":"token.revoke","path":"/api/tokens/{id}","summary":"Revoke a machine token. Takes effect on the next request."},{"access":"read","method":"GET","name":"operator.list","path":"/api/operators","summary":"Who can log in."},{"access":"spend","method":"POST","name":"operator.create","path":"/api/operators","summary":"Create an operator. The generated password is in the response and nowhere else"},{"access":"spend","method":"PUT","name":"operator.grants","path":"/api/operators/{id}/grants","summary":"Replace an operator's grants. Never more than the caller holds, and never your own"},{"access":"spend","method":"PUT","name":"customer.dormancy","path":"/api/customers/{id}/dormancy","summary":"Set one customer's dormancy windows in days. Null uses the default, 0 means never"},{"access":"read","method":"GET","name":"audit.list","path":"/api/audit","summary":"What was done, by whom, and whether it succeeded."},{"access":"certs","method":"POST","name":"certificate.report","path":"/api/certificates/events","summary":"Report certificate events: a JSON array of at most 500 of the box's events.jsonl objects (id, ts, host, ca, kind, result, error, not_after, served_ca, start). ca is actalis or letsencrypt, kind is attempt or served, result is ok, failed or not_due. A malformed or oversized batch is a 400 and nothing is stored; an id already stored is skipped. 200 {\"received\", \"new\"}. Needs certs, which read does not imply."},{"access":"read","method":"GET","name":"certificate.list","path":"/api/certificates","summary":"Every host's certificates: the box's own hosts from the events it reported, then customer routes and custom domains. Each has served_ca, needs_attention with its reasons (fallback, under_21_days, failing, no_report_26h), last_event_at and one slot per CA with not_after, days_left, state (valid, expired, none) and failing. A customer row never carries an error text."},{"access":"read","method":"GET","name":"certificate.history","path":"/api/certificates/{host}","summary":"One host's certificate events and daily snapshots, newest first. ?days= is how far back, default 30, clamped to 1..366. 404 for a host nothing has ever been reported or recorded for."},{"access":"read","method":"GET","name":"backup.control","path":"/api/backups/control","summary":"Whether the control plane's off-box backups work, as the box's omniarc-offbox script last wrote it: {status, reasons}. status is null when the box has written none yet, else configured, last_push_at (the last attempt), last_push_ok, pending, oldest_pending, last_ok_at (the last push in which every upload succeeded), last_drained_at, last_escrow_at, last_drill_at, last_drill_ok and the two error lines last_error and last_drill_error (key names and HTTP codes, never a secret). reasons says why an operator should look, in this order: no_status or not_configured (alone), push_failing, no_push_2h, backlog, no_escrow, drill_failed, no_drill_8d. A status file that cannot be read is a 500 that does not quote it."},{"access":"spend","method":"POST","name":"node.create","path":"/api/nodes","summary":"Order a machine. Body: {type?, account?, zone?}: the type inside the named provider account (the default account when absent; a type is never matched across accounts); zone, if given, must be that account's. Requires spend, which operate does not imply."},{"access":"read","method":"GET","name":"node.offers","path":"/api/nodes/offers","summary":"What this orchestrator may buy, per provider account, with live stock, price and both ceilings."},{"access":"read","method":"GET","name":"node.orphans","path":"/api/fleet/orphans","summary":"Per provider account, each machine and pending order carrying omniarc's mark that no node row holds, with whose it is (ours, other-control-plane, unverified), how it was matched, and probable_node: the row it is named for when adopt would take it there -- a stuck row, or a bought node that joined without its machine id -- and null otherwise; an account the provider would not answer for has its error instead, and an account the order follower stopped for (its credential refused) is not asked at all: its error starts with paused:. stuck_rows: the rows at provisioning that hold no machine or order and whose order answer was lost (indeterminate, or an inline order call unanswered for 15 minutes). Only reads."},{"access":"spend","method":"POST","name":"node.adopt","path":"/api/nodes/{name}/adopt","summary":"Bind a machine or pending order node.orphans lists to a row stuck at provisioning, or a node's own machine (named for it) to a node that joined without its machine id. Body: {machine_id} or {order_id}, exactly one. A machine moves a provisioning row to installing and leaves a joined node's state alone; an order leaves the row at provisioning for the order follower. 409, naming why: the row is in no such state or already holds a machine or order, its order was refused, the account lists no such id, the id is marked for another control plane, another row holds it, or the machine is named for another live row (or, for an inline row or a joined node, not for this one); and, before any provider call, while the row's account is paused (the provider refused its credential; fix it and restart the orchestrator)."},{"access":"operate","method":"POST","name":"node.reinstall","path":"/api/nodes/{name}/reinstall","summary":"Install a Later-route node's machine again: forgets that an install was started (and why it failed) so the order follower installs on its next tick with a new join token, which revokes the old one. Never calls the provider itself and never orders. 202 {name, state: installing}. 409 for an inline node (release it and order another), a hand-enrolled node (it gets a new enroll command instead), a node in any other state than installing (or that left it while this ran), and a node whose account the order follower stopped for after its credential was refused (fix it, then restart the orchestrator)."},{"access":"operate","method":"POST","name":"node.add","path":"/api/fleet/by-hand","summary":"Enroll a machine omniarc did not order. Body: {vendor, zone, offer, monthly_eur?, hourly_eur?, setup_eur?, min_term_months?}: vendor is 1-40 characters of letters, digits, space, dot, underscore and hyphen, stored lower-cased; zone is the location label customers see as their arc's region; prices are euro decimal strings (at most nine decimals) the operator pays, net of VAT. Writes a hand-enrolled node at installing, named like an ordered one, and mints its single-use join token (60 minutes). 201 {name, command, script_sha256, expires_at, prerequisites, note}: command is the one line to run on the box, which fetches /enroll.sh, checks it against script_sha256 and hands it the token on stdin, never in a URL. 503, writing nothing, when this orchestrator could not enroll a box: no published guest, no agent URL or checksum, or no mesh hub."},{"access":"operate","method":"POST","name":"node.enroll_command","path":"/api/nodes/{name}/enroll-command","summary":"A new enroll command for a hand-enrolled node still installing (its command expired, or the agent or guest image changed under it): mints a new join token (60 minutes), which revokes the previous one. 200 with node.add's body. 409 for a node that was ordered (it installs from its order) or is no longer installing, naming its state."},{"access":"read","method":"GET","name":"node.list","path":"/api/nodes","summary":"Every node, gone ones included, with whether it is answering, its stage and who it is waiting on, and usual_minutes: the median minutes from order to joined over its account's past nodes, null under three of them or for a node no account bought."},{"access":"read","method":"GET","name":"node.get","path":"/api/nodes/{name}","summary":"One node: its row, what it holds, and its live metrics."},{"access":"read","method":"GET","name":"node.arcs","path":"/api/nodes/{name}/arcs","summary":"One node's arcs, asked of that node alone so a slow one costs only its own row."},{"access":"read","method":"GET","name":"node.metrics.series","path":"/api/nodes/{name}/metrics/series","summary":"One node's sampled history, as buckets: the charts on its detail page."},{"access":"read","method":"GET","name":"fleet.availability","path":"/api/availability","summary":"How much of a window each node was up, down, or unwatched. Three numbers, never two."},{"access":"read","method":"GET","name":"fleet.events","path":"/api/fleet/events","summary":"What the monitor sees, as it sees it: the fleet list, live."},{"access":"read","method":"GET","name":"fleet.builds","path":"/api/fleet/builds","summary":"The agent builds that can be shipped, newest binary first: sha, checksum, size, build time, when main was moved to it. `newest` is main's latest build, not necessarily the first."},{"access":"read","method":"GET","name":"fleet.upgrades","path":"/api/fleet/upgrades","summary":"Agent upgrades and rollbacks with their state and error, newest first. ?node=<name> for one node."},{"access":"read","method":"GET","name":"fleet.upgrade","path":"/api/fleet/upgrades/{id}","summary":"One upgrade: queued, running, succeeded or failed, where it is, and why it failed."},{"access":"operate","method":"POST","name":"fleet.node_upgrade","path":"/api/nodes/{name}/upgrade","summary":"Queue moving a node's agent to a catalogue build (default main's newest). Answers 202 with the upgrade; 409 for an older build while its arcs hold branch env records, unless `ignore_branch_envs` is true."},{"access":"operate","method":"POST","name":"fleet.node_rollback","path":"/api/nodes/{name}/rollback","summary":"Queue moving a node's agent back to the build it ran before. Answers 202 with the upgrade; 409 while its arcs hold branch env records, unless the body is {\"ignore_branch_envs\": true}."},{"access":"operate","method":"POST","name":"fleet.upgrade_cancel","path":"/api/fleet/upgrades/{id}/cancel","summary":"Fail an open upgrade as cancelled, freeing its node for another. 409 when it already finished."},{"access":"read","method":"GET","name":"node.peers","path":"/api/nodes/peers","summary":"Every node that should be a WireGuard peer. Read by omniarc-mesh sync."},{"access":"open","method":"POST","name":"node.join","path":"/api/nodes/join","summary":"Trade a join token for a mesh address. Called by a node's cloud-init, once."},{"access":"operate","method":"POST","name":"node.enroll","path":"/api/nodes/{name}/enroll","summary":"Register a machine nobody bought, give it a mesh address, and record its zone and offer if given."},{"access":"operate","method":"POST","name":"node.verify","path":"/api/nodes/{name}/verify","summary":"Check a joining node answers over the mesh, and mark it ready."},{"access":"operate","method":"POST","name":"node.drain","path":"/api/nodes/{name}/drain","summary":"Stop placing on a node. Its branches keep serving."},{"access":"operate","method":"POST","name":"node.placement","path":"/api/nodes/{name}/placement","summary":"Open a node to new customer arcs, or close it. Placement still skips it until it is ready and not smoke."},{"access":"spend","method":"DELETE","name":"node.destroy","path":"/api/nodes/{name}","summary":"Release a node: the row goes to gone, its mesh address is given back and its unused join tokens (an enroll command not yet run) are revoked. A bought machine is returned through its account and billing stops. A row holding no machine id asks no provider and returns nothing: for a lost order, a machine it did buy bills on until it is released at the provider (node.orphans lists it); a hand-enrolled box keeps running what is on it. 409 for a node holding a pending order (cancel it at the provider; the order follower then moves the row to gone), for a bought node that joined without its machine id (adopt its machine first, see node.orphans), and while the row's account is paused (the provider refused its credential; fix it and restart the orchestrator)."},{"access":"read","method":"GET","name":"move.targets","path":"/api/nodes/{name}/arcs/{arc}/move-targets","summary":"Where an arc could move: every other node with what it would have left or why it is refused, the suggested one, and the hold the move needs."},{"access":"operate","method":"POST","name":"move.start","path":"/api/nodes/{name}/arcs/{arc}/moves","summary":"Start moving an arc to another node, the suggested one unless `to` names it. The arc keeps serving; 202 with the move."},{"access":"read","method":"GET","name":"move.get","path":"/api/moves/{id}","summary":"One move: its state, step, copy progress, hold and kept copy."},{"access":"read","method":"GET","name":"move.list","path":"/api/moves","summary":"Moves, newest first (50), optionally of one node (`node`) or one arc (`arc`, with `node`, or an id)."},{"access":"operate","method":"POST","name":"move.cancel","path":"/api/moves/{id}/cancel","summary":"Cancel a move that has not begun its cutover; the copy on the target is discarded. 409 once it is cutting or over."},{"access":"operate","method":"POST","name":"move.cutover","path":"/api/moves/{id}/cutover","summary":"Cut a ready move over now, one started with manual_cutover. 409 when the ingress cannot hold requests yet."},{"access":"operate","method":"POST","name":"move.discard_kept","path":"/api/moves/{id}/discard-kept","summary":"Discard a moved arc's kept copy on its old node now, rather than at 24 h. 409 unless the move is moved."},{"access":"operate","method":"POST","name":"move.discard_target","path":"/api/moves/{id}/discard-target","summary":"Take again what a cancelled, failed or rolled-back move left on its target. 409 when nothing is left."},{"access":"read","method":"GET","name":"fleet.arcs","path":"/api/arcs","summary":"Every arc across the fleet, each on the node it lives on."},{"access":"read","method":"GET","name":"fleet.arc","path":"/api/arcs/{node}/{arc}","summary":"One arc: its branch tree, origins and per-application sizes."},{"access":"operate","method":"DELETE","name":"fleet.arc_delete","path":"/api/arcs/{node}/{arc}","summary":"Destroy an arc and every branch under it."},{"access":"operate","method":"POST","name":"fleet.branch_create","path":"/api/arcs/{node}/{arc}/branches","summary":"Branch an arc: a complete copy of its data, in seconds."},{"access":"operate","method":"DELETE","name":"fleet.branch_delete","path":"/api/arcs/{node}/{arc}/branches/{branch}","summary":"Destroy one branch. Irreversible, and does not ask twice."},{"access":"operate","method":"POST","name":"fleet.branch_sleep","path":"/api/arcs/{node}/{arc}/branches/{branch}/sleep","summary":"Stop a branch's containers. Its data stays."},{"access":"operate","method":"POST","name":"fleet.branch_wake","path":"/api/arcs/{node}/{arc}/branches/{branch}/wake","summary":"Start a sleeping branch's containers again."},{"access":"open","method":"POST","name":"account.signup","path":"/api/account/signup","summary":"Redeem a beta invite into an account, an organization and a session"},{"access":"open","method":"POST","name":"account.login","path":"/api/account/login","summary":"Exchange an email and password for a customer session"},{"access":"open","method":"POST","name":"account.verify","path":"/api/account/verify","summary":"Prove an address with the token mailed to it, and start the session signup withheld"},{"access":"open","method":"POST","name":"account.reset_request","path":"/api/account/reset","summary":"Ask for a password reset. Answers the same whether or not the address exists"},{"access":"open","method":"POST","name":"account.reset_confirm","path":"/api/account/reset/confirm","summary":"Set a new password with a reset token, and end every session that person has"},{"access":"customer:member","method":"POST","name":"account.logout","path":"/api/account/logout","summary":"End this session"},{"access":"customer:member","method":"GET","name":"account.whoami","path":"/api/account/whoami","summary":"The person (email and person_id), the organization this session acts for, and every membership"},{"access":"customer:member","method":"POST","name":"account.password_change","path":"/api/account/password","summary":"Change the password. Requires the old one, and ends every other session"},{"access":"customer:member","method":"DELETE","name":"account.close","path":"/api/account","summary":"Anonymize this account and revoke every session. A sole owner must transfer or delete first"},{"access":"operate","method":"POST","name":"beta.invite","path":"/api/beta/invites","summary":"Invite an address into the closed beta"},{"access":"read","method":"GET","name":"beta.list","path":"/api/beta/invites","summary":"Every beta invite and whether it was redeemed"},{"access":"operate","method":"DELETE","name":"beta.revoke","path":"/api/beta/invites/{id}","summary":"Revoke an unredeemed beta invite"},{"access":"customer:member","method":"GET","name":"member.list","path":"/api/members","summary":"Every member of the active organization, and the role each holds"},{"access":"customer:admin","method":"POST","name":"member.invite","path":"/api/members/invite","summary":"Invite an address into the active organization with a role"},{"access":"customer:admin","method":"POST","name":"member.role","path":"/api/members/{person}/role","summary":"Change a member's role. Granting or revoking owner needs the caller to be one"},{"access":"customer:admin","method":"DELETE","name":"member.remove","path":"/api/members/{person}","summary":"Remove a member. An organization always keeps at least one owner"},{"access":"customer:admin","method":"GET","name":"invite.list","path":"/api/invitations","summary":"Open invitations into the active organization"},{"access":"customer:admin","method":"DELETE","name":"invite.revoke","path":"/api/invitations/{id}","summary":"Revoke an open invitation"},{"access":"open","method":"POST","name":"invite.accept","path":"/api/invitations/accept","summary":"Join an existing organization by redeeming an invitation"},{"access":"customer:member","method":"POST","name":"customer.create","path":"/api/customers","summary":"A second organization. The creator becomes its owner"},{"access":"customer:member","method":"GET","name":"customer.get","path":"/api/customer","summary":"The organization this session currently acts for"},{"access":"customer:admin","method":"PATCH","name":"customer.rename","path":"/api/customer","summary":"Rename the active organization"},{"access":"customer:member","method":"POST","name":"customer.switch","path":"/api/customer/switch","summary":"Change which organization this session acts as. Writes an audit row"},{"access":"customer:owner","method":"POST","name":"customer.transfer","path":"/api/customer/transfer","summary":"Hand ownership to another member of the active organization"},{"access":"customer:owner","method":"DELETE","name":"customer.delete","path":"/api/customer","summary":"Soft-delete the active organization. Refused while it holds arcs"},{"access":"customer:admin","method":"POST","name":"key.create","path":"/api/customer/keys","summary":"Mint an API key. Shown once. Its role may not exceed yours, and never outlives it."},{"access":"customer:member","method":"GET","name":"key.list","path":"/api/customer/keys","summary":"This organization's API keys and what each may do. Never the keys themselves."},{"access":"customer:admin","method":"DELETE","name":"key.revoke","path":"/api/customer/keys/{id}","summary":"Revoke an API key. Takes effect on the next request."},{"access":"customer:member","method":"GET","name":"arc.list","path":"/api/customer/arcs","summary":"Every arc this organization owns, with its region and its branches."},{"access":"customer:member","method":"GET","name":"arc.get","path":"/api/customer/arcs/{arc}","summary":"One arc: its branches, their sizes, and which are awake."},{"access":"customer:admin","method":"POST","name":"arc.create","path":"/api/customer/arcs","summary":"Create a new arc by name; deploy it with `omniarc deploy`. Placement chooses the node; the caller never names one. 402 billing_hold while the organization is on billing hold (an invoice unpaid for 14 days; paying it lifts the hold), else 402 payment_method_required when billing is on, the customer is enrolled and has no card (and no operator exemption)."},{"access":"customer:owner","method":"DELETE","name":"arc.delete","path":"/api/customer/arcs/{arc}","summary":"Destroy an arc and every branch under it. Irreversible, and does not ask twice."},{"access":"customer:admin","method":"PUT","name":"arc.dormancy","path":"/api/customer/arcs/{arc}/dormancy","summary":"Set how long this arc survives unused, in days. Null uses your organization's, 0 never reaps it"},{"access":"customer:admin","method":"POST","name":"arc.deploy","path":"/api/customer/arcs/{arc}/deploys","summary":"Deploy a bundle (your compose project and arc.yaml) to a branch, or redeploy a stored revision ({revision}). {revision, arc_yaml} redeploys production's compose project with that arc.yaml in place of its own: revision must be the one production runs (409 otherwise), and the deploy's source is dashboard. Answers 202; poll the deploy. 400 for a branch whose env would copy a live-looking value (Stripe, Mollie, AWS key, SMTP server, Sentry DSN) that no rule covers: the reply names the variables and their kinds, never a value; an Admin must add a rule (copy keeps it on purpose)."},{"access":"customer:member","method":"GET","name":"arc.deploys","path":"/api/customer/arcs/{arc}/deploys","summary":"This arc's deploy history, newest first."},{"access":"customer:member","method":"GET","name":"arc.deploy_get","path":"/api/customer/arcs/{arc}/deploys/{id}","summary":"One deploy: its state, findings, notes and per-service health."},{"access":"customer:member","method":"GET","name":"arc.deploy_log","path":"/api/customer/arcs/{arc}/deploys/{id}/log","summary":"One deploy's step log, from a line number on."},{"access":"customer:member","method":"GET","name":"arc.deploy_bundle","path":"/api/customer/arcs/{arc}/deploys/{id}/bundle","summary":"The bundle (compose project and arc.yaml) one deploy ran, as a .tar.zst."},{"access":"customer:member","method":"GET","name":"arc.config_get","path":"/api/customer/arcs/{arc}/config","summary":"The arc.yaml one branch runs, read from the bundle of the revision its node reports."},{"access":"customer:member","method":"GET","name":"arc.config_draft_get","path":"/api/customer/arcs/{arc}/config/draft","summary":"The arc's shared arc.yaml draft: {arc_yaml, base_revision, author, updated_at}; 404 when there is none."},{"access":"customer:admin","method":"PUT","name":"arc.config_draft_put","path":"/api/customer/arcs/{arc}/config/draft","summary":"Save the arc's shared arc.yaml draft, replacing the last one: {arc_yaml, base_revision} where base_revision is the production revision it was started from. Not validated. 413 over 64 KiB, 400 when base_revision is not a revision of this arc."},{"access":"customer:admin","method":"DELETE","name":"arc.config_draft_delete","path":"/api/customer/arcs/{arc}/config/draft","summary":"Discard the arc's shared arc.yaml draft: {deleted} says whether there was one."},{"access":"customer:admin","method":"GET","name":"arc.env_list","path":"/api/customer/arcs/{arc}/env","summary":"The names in the arc's .env, its revision, and the branches still on an older one. Never a value."},{"access":"customer:admin","method":"PUT","name":"arc.env_replace","path":"/api/customer/arcs/{arc}/env","summary":"Replace the arc's .env with the uploaded file, verbatim. Takes effect at each branch's next deploy. When the saved file leaves a live-looking value (Stripe, Mollie, AWS key, SMTP server, Sentry DSN) that no branch rule covers and the arc has a branch, the reply adds live_unruled [{name, live}]: a branch on the arc's .env may read it when it wakes, and every branch's next deploy is refused until it has a rule. For one a rule covers, while a branch the node lists has no file of its own, it adds live_reaching [{name, live, branches}]: those branches read the arc's whole .env when they wake until they are redeployed. Names, kinds and branch names, never a value. Both also come with the 503 or 502 of a save stored but not delivered (live_reaching only when the node listed its branches). The save is never refused for them."},{"access":"customer:admin","method":"PUT","name":"arc.env_set","path":"/api/customer/arcs/{arc}/env/{name}","summary":"Set one line of the arc's .env. Takes effect at each branch's next deploy. When the saved file leaves a live-looking value (Stripe, Mollie, AWS key, SMTP server, Sentry DSN) that no branch rule covers and the arc has a branch, the reply adds live_unruled [{name, live}]: a branch on the arc's .env may read it when it wakes, and every branch's next deploy is refused until it has a rule. For one a rule covers, while a branch the node lists has no file of its own, it adds live_reaching [{name, live, branches}]: those branches read the arc's whole .env when they wake until they are redeployed. Names, kinds and branch names, never a value. Both also come with the 503 or 502 of a save stored but not delivered (live_reaching only when the node listed its branches). The save is never refused for them."},{"access":"customer:admin","method":"DELETE","name":"arc.env_delete","path":"/api/customer/arcs/{arc}/env/{name}","summary":"Remove one variable from the arc's .env. Takes effect at each branch's next deploy. When the saved file leaves a live-looking value (Stripe, Mollie, AWS key, SMTP server, Sentry DSN) that no branch rule covers and the arc has a branch, the reply adds live_unruled [{name, live}]: a branch on the arc's .env may read it when it wakes, and every branch's next deploy is refused until it has a rule. For one a rule covers, while a branch the node lists has no file of its own, it adds live_reaching [{name, live, branches}]: those branches read the arc's whole .env when they wake until they are redeployed. Names, kinds and branch names, never a value. Both also come with the 503 or 502 of a save stored but not delivered (live_reaching only when the node listed its branches). The save is never refused for them."},{"access":"customer:admin","method":"GET","name":"arc.branch_env_rules","path":"/api/customer/arcs/{arc}/branch-env/rules","summary":"The arc's effective branch env rules: {rules: [{name, rule (copy, new or {modify, with}), source (arc.yaml, dashboard or dashboard_differs), arc_yaml_rule (when it differs), value (set or missing for a new rule, else null)}], drift (how many rules differ from arc.yaml), hooks: [{service, exec, timeout_secs}]}. Never a value."},{"access":"customer:admin","method":"PUT","name":"arc.branch_env_rule_set","path":"/api/customer/arcs/{arc}/branch-env/rules/{name}","summary":"Set the dashboard's rule for one variable: {rule: copy, new or {modify, with}}. It wins over arc.yaml. 400 with the arc.yaml validation error's slug as `code` when the rule is not valid. Takes effect at each branch's next deploy."},{"access":"customer:admin","method":"DELETE","name":"arc.branch_env_rule_reset","path":"/api/customer/arcs/{arc}/branch-env/rules/{name}","summary":"Drop the dashboard's rule for one variable, so it follows arc.yaml again: {deleted}. Takes effect at each branch's next deploy."},{"access":"customer:admin","method":"PUT","name":"arc.branch_env_value_set","path":"/api/customer/arcs/{arc}/branch-env/values/{name}","summary":"Set the value every branch takes for a `new` variable: {value}. Write-only. Answers {name, branch, used (whether a `new` rule names it; null when the rules cannot be read), applies}. Takes effect at each branch's next deploy."},{"access":"customer:admin","method":"DELETE","name":"arc.branch_env_value_delete","path":"/api/customer/arcs/{arc}/branch-env/values/{name}","summary":"Remove the all-branches value of a `new` variable: {deleted}. Takes effect at each branch's next deploy."},{"access":"customer:admin","method":"PUT","name":"branch.env_value_set","path":"/api/customer/arcs/{arc}/branches/{branch}/env/{name}","summary":"Set one branch's own value of a `new` variable, winning over the all-branches one: {value}. Write-only. 400 for production. Answers {name, branch, used (whether a `new` rule names it; null when the rules cannot be read), applies}. Takes effect at the branch's next deploy."},{"access":"customer:admin","method":"DELETE","name":"branch.env_value_delete","path":"/api/customer/arcs/{arc}/branches/{branch}/env/{name}","summary":"Remove one branch's own value of a `new` variable: {deleted}. 400 for production."},{"access":"customer:admin","method":"GET","name":"arc.branch_envs","path":"/api/customer/arcs/{arc}/branch-env/branches","summary":"Each branch's env state: {branches: [{branch, state (arc_env, up_to_date, behind, live_values or missing_values; live_values wins over the first three, missing_values over all), reasons (production env changed, parent changed, rules changed, values changed, URL changed, not deployed), missing (the `new` variables no value covers), overrides (names the branch has its own value for), origins (per ruled variable: copied, modified or new, names only), copied ({from: production or the parent branch whose record the text is, variables: [{name, live}]}: every variable no rule names that the branch's next create or deploy would copy, live being the kind of live-looking value (stripe_live_key, mollie_live_key, aws_key, smtp_server, sentry_dsn) or null; names and kinds, never a value), reads_arc_env (true when the branch has no env file of its own, rules or not: until a deploy gives it one, it reads the arc's .env as it is when it wakes, unchecked)}], listing (complete, or partial when the node could not be asked: a branch with no record is then missing)}."},{"access":"customer:admin","method":"GET","name":"arc.branch_env_arc_yaml","path":"/api/customer/arcs/{arc}/branch-env/arc.yaml","summary":"Download production's arc.yaml with its `branches:` block replaced by the effective rules, every other byte as deployed (text/yaml attachment). 404 when production has no deploy. No values."},{"access":"customer:member","method":"POST","name":"branch.create","path":"/api/customer/arcs/{arc}/branches","summary":"Branch an arc: a complete isolated copy of its data. By default it answers when the copy is done: 200 {ok, anonymize (per service: rules, rows), notes, url/url_state when the branch has a public URL}, 422 {error, service, rule} when anonymize failed (the copy was removed), 503 when the node did not make it. Large PII databases can take up to two hours; send `Prefer: respond-async` to get 202 with the create {id, parent, name, state} at once instead, and poll branch.create_get until state is created, anonymize_failed, failed or interrupted (409 while a create of that name is still running). 402 billing_hold while the organization is on billing hold (an invoice unpaid for 14 days; paying it lifts the hold), else 402 payment_method_required when billing is on, the customer is enrolled and has no card (and no operator exemption). 400 when the branch would copy a live-looking value (Stripe, Mollie, AWS key, SMTP server, Sentry DSN) that no rule covers: the reply names the variables and their kinds, never a value, and says an Admin must add a rule; nothing is created."},{"access":"customer:member","method":"POST","name":"branch.create_check","path":"/api/customer/arcs/{arc}/branches/check","summary":"Whether branch.create with this body would be refused before it writes anything: the same body, the same role (a Member's env refused the same way), and the create's own 4xx answer when it would be (402 billing, 400 a name, 403/400 an env, 400 a live-looking value no rule covers, 400 a `new` variable no value covers; a value stored for a branch of that name is not counted, since deleting the branch drops it); else 200 {ok: true}. Writes nothing and calls no node, so what only the node can say (a branch of that name already there, a copy that fails) is not checked."},{"access":"customer:member","method":"GET","name":"branch.create_get","path":"/api/customer/arcs/{arc}/branch-creates/{id}","summary":"One branch create started with `Prefer: respond-async`: its state (dispatching, creating, then created, anonymize_failed, failed or interrupted) and, once settled, its outcome: anonymize reports, notes and url/url_state, or error (with service and rule for an anonymize failure)."},{"access":"customer:member","method":"DELETE","name":"branch.delete","path":"/api/customer/arcs/{arc}/branches/{branch}","summary":"Destroy one branch. Irreversible, and does not ask twice."},{"access":"customer:member","method":"POST","name":"branch.sleep","path":"/api/customer/arcs/{arc}/branches/{branch}/sleep","summary":"Stop a branch's containers. Its data stays."},{"access":"customer:member","method":"POST","name":"branch.wake","path":"/api/customer/arcs/{arc}/branches/{branch}/wake","summary":"Start a branch's containers again. 402 billing_hold while the organization is on billing hold (an invoice unpaid for 14 days; paying it lifts the hold)."},{"access":"customer:admin","method":"POST","name":"arc.shell_open","path":"/api/customer/arcs/{arc}/branches/{branch}/shell","summary":"Open a root shell (or run one command) in a branch. Answers a single-use ticket for arc.shell_attach, valid 30 seconds; wakes a sleeping branch first."},{"access":"customer:admin","method":"GET","name":"arc.shell_attach","path":"/api/customer/shell/{ticket}","summary":"Attach to a shell opened by arc.shell_open (WebSocket; binary frames are channel-prefixed bytes, text frames JSON control messages)."},{"access":"customer:member","method":"GET","name":"branch.url","path":"/api/customer/arcs/{arc}/branches/{branch}/url","summary":"A branch's public HTTPS URL and whether it serves yet: pending, ready or failed (retried automatically)."},{"access":"customer:member","method":"GET","name":"branch.services","path":"/api/customer/arcs/{arc}/branches/{branch}/services","summary":"A branch's containers, as `docker compose ps` shows them: per container its service, state, exit code, restarts, start and exit times, status text, image and last_exit (how its newest run ended). A branch that is not running answers its instance state and no services. 404 no such branch, 501 the node cannot report services yet, 503 the node could not be reached."},{"access":"customer:member","method":"GET","name":"arc.urls","path":"/api/customer/arcs/{arc}/urls","summary":"Every branch's public HTTPS URL with its state and custom domains, from the routes table; the node is never dialled."},{"access":"customer:admin","method":"POST","name":"domain.add","path":"/api/customer/arcs/{arc}/branches/{branch}/domains","summary":"Bind your own domain to a branch. Answers the two CNAME records to create; renewals then need nothing from you."},{"access":"customer:admin","method":"DELETE","name":"domain.remove","path":"/api/customer/arcs/{arc}/branches/{branch}/domains/{domain}","summary":"Unbind a custom domain from a branch. It stops being served; its records can then be removed."},{"access":"customer:member","method":"GET","name":"usage.arc","path":"/api/customer/arcs/{arc}/usage","summary":"What this arc used, per branch, for every metered resource, raw and unpriced (costs.get prices it). meters lists each meter (key, label, unit); totals (the arc) and each branch's totals are keyed by meter key, and each branch's series has one value per bucket in buckets. Quantities are billing units as decimal strings floored to 3 places: CPU in vCPU·h, memory and storage in GB·h (storage integrated over time), egress in GB, awake time in h; null for a meter no reading measured (not zero); the arc's totals are sums of the rounded branch lines, so they can read below costs.get's quantities by up to a thousandth per extra branch, never above. Each branch also has current_storage_gb (its latest reading, null if the branch is gone or unread for two sweeps; current_storage_at is when it was last read) and gap_hours (hours inside its sampled span with no reading). rollup_pending: a reading not counted yet can still change this window's figures. from/to: RFC 3339, floored to the hour, to exclusive (default this UTC month to date); step=hour|day|month (default day; hour at most 31 days; any window at most 13 months); partial: the current hour is incomplete. Deprecated, removed after one release: each branch's awake_hours, cpu_hours, gb_hours, storage_gb and the top-level gaps."},{"access":"customer:member","method":"GET","name":"logs.search","path":"/api/customer/arcs/{arc}/logs/search","summary":"Search an arc's logs, newest first. q is Datadog-style (service:web level:error \"timeout\" -path:/health @http.status:>=500); from/to take RFC 3339 or now-15m (default the last 15 minutes); branch, limit (max 1000), and cursor for the next page."},{"access":"customer:member","method":"GET","name":"logs.histogram","path":"/api/customer/arcs/{arc}/logs/histogram","summary":"How many log lines matched over time, per severity, in at most ~120 buckets, with deploy, wake, sleep, restart, OOM and ingest-cap markers. Takes logs.search's q, from, to and branch."},{"access":"customer:member","method":"GET","name":"logs.facets","path":"/api/customer/arcs/{arc}/logs/facets","summary":"The top 20 values, with counts, of service, level, branch, stream and event (or fields=@attribute, one per fields= parameter, repeated for more) among the lines a search matches, and the most common attribute keys."},{"access":"customer:member","method":"GET","name":"logs.context","path":"/api/customer/arcs/{arc}/logs/context","summary":"The lines printed just before and after one log line by the same container: id from logs.search, before/after up to 200 each (default 50)."},{"access":"customer:member","method":"GET","name":"logs.tail","path":"/api/customer/arcs/{arc}/logs/tail","summary":"Follow an arc's logs live as server-sent events, in the order lines arrive (late ones included), resuming after Last-Event-ID. Takes q and branch. Closes after 30 minutes; reconnect to continue."},{"access":"customer:member","method":"GET","name":"metrics.arc","path":"/api/customer/arcs/{arc}/metrics","summary":"Per-service CPU (cores), memory (bytes), disk read/write and network rx/tx (bytes/s) and restarts over time, at most 300 points per series on a shared time axis t (null where no data), with restart, OOM, deploy, wake and sleep markers. from/to take RFC 3339 or now-6h (default the last 15 minutes, within the metrics retention, default 30 days); branch; metrics=cpu.usage_seconds,memory.bytes,io.read_bytes,io.write_bytes,net.rx_bytes,net.tx_bytes,restarts (default all); service to narrow. Series carry avg and max per step; restarts carry sum."},{"access":"read","method":"GET","name":"ops.logs.search","path":"/api/ops/logs/search","summary":"Search the platform's own logs, newest first. source=orchestrator is every control-box service (omniarc-control's events carry trace_id and a panic is an ERROR event with target omniarc_control::panic; omniarc-orchestrator is the same process's stderr, whose lines have no level (UNSPECIFIED), so find them by text, e.g. service:omniarc-orchestrator panicked); source=node&node=<name> is that node agent's log. q is Datadog-style: level:error service:omniarc-control target:omniarc_control::serve trace_id:<32 hex> \"timeout\" @http.route:/api/nodes -service:omniarc-site. from/to take RFC 3339 or now-1h (default the last 15 minutes; 30 days kept). limit 1-500 (default 100); cursor pages older. Bodies are cut at 4096 characters: a line's truncated: true means its body was cut (ops.logs.context shows up to 65536); an answer's truncated: true means more lines matched than limit. Pass a line's id to ops.logs.context for the lines around it, and its trace_id back as q=trace_id:<id> for the whole request. To follow new lines, pass the answer's position as after= and repeat the same source, node and q, with no from/to: lines come oldest first, newer than the position, with the next position (it moves even when no line came; one from a page cut at limit counts the older lines it cut off as seen, so the first poll brings only what arrived after the page); an answer's truncated: true then means call again at once. A line that arrives late is missed by polling (search still finds it) only when it is more than 5 seconds older than a line already returned, or stamped more than 60 seconds before now. A position more than an hour old resumes an hour back, and the answer's skipped_before says before when lines were skipped."},{"access":"read","method":"GET","name":"ops.logs.histogram","path":"/api/ops/logs/histogram","summary":"How many platform log lines matched over time, per severity (FATAL, ERROR, WARN, INFO, DEBUG, TRACE, UNSPECIFIED), in at most ~120 buckets, and markers where the build changed (deploys of omniarc-control, or of that node's agent; at most 50, the newest; markers_truncated is true if more existed, or, with no markers, if there were too many rows to compute any). Takes ops.logs.search's source, node, q, from and to. Find when errors began, then call ops.logs.search with that bucket's from/to."},{"access":"read","method":"GET","name":"ops.logs.facets","path":"/api/ops/logs/facets","summary":"The top 20 values, with counts, of service, level and target (source=orchestrator) or level and target (source=node) among the lines a search matches, or fields=@attribute (one per fields= parameter, at most 10), plus the 20 most common attribute keys. Takes ops.logs.search's source, node, q, from and to. Find the noisy service or module, then add it to q."},{"access":"read","method":"GET","name":"ops.logs.context","path":"/api/ops/logs/context","summary":"One platform log line and the lines just before and after it from the same service (orchestrator) or node, oldest first: id from ops.logs.search with the same source and node, before/after 0-200 each (default 20), within an hour either side. The line's own body up to 65536 characters, its neighbours' up to 4096 (truncated: true on a line whose body was cut). 404 for a line past the 30-day retention."},{"access":"read","method":"GET","name":"ops.logs.tail","path":"/api/ops/logs/tail","summary":"Follow the platform's logs live as server-sent events (not an MCP tool: poll ops.logs.search with after= instead). Takes source, node and q; resumes after Last-Event-ID (one more than an hour old resumes an hour back, with a tail_notice saying what was skipped); closes after 30 minutes; starts 60 seconds back. A line that arrives late is missed here (and still found by search) only when it is more than 5 seconds older than a line already sent, or stamped more than 60 seconds before now."},{"access":"read","method":"GET","name":"ops.errors","path":"/api/ops/errors","summary":"What is broken: error groups from failed requests (span errors), orchestrator ERROR log events (log) and node agent ERROR lines (node), each grouped by source, service, op and a fingerprint (the message with quoted strings, UUIDs, hex and numbers replaced). from/to take RFC 3339 or now-1h (default the last 24 hours; 30 days kept); filters: source=span|log|node, service, status=new|regressed|open|resolved|ignored, q (text in the fingerprint); limit 1-100 (default 50). Each group: group (16 hex), state (new = first seen in the range; regressed = seen again after it was resolved; ignored groups are hidden unless status=ignored or they are spiking, ten times their previous count), count and previous_count with trend, a 30-point sparkline, first_seen and last_seen over all 30 days, first_build and last_build (12-character commit; dev = built without one), nodes, customers and traces touched, sample_message and sample_trace_id. New, regressed and spiking groups come first. counts gives each state's total; truncated: true means more groups matched than were returned; crowded names ops with more than 20 distinct fingerprints (a flood), which are capped at 20 each. A warning appears when more than 2000 groups are triaged: the oldest-changed ones then show as open. Next: pass group to ops.errors.get; pass sample_trace_id to ops.trace with format=text."},{"access":"read","method":"GET","name":"ops.errors.get","path":"/api/ops/errors/{group}","summary":"One error group in depth: group is the 16-hex id from ops.errors. Everything ops.errors says about it plus its triage (status, note, changed_by, resolved_at), the 50 newest occurrences from the last 30 days whatever the range (occurrences_truncated says more exist), each with ts, node, build, op, customer, message (cut at 4096 characters, truncated: true), trace_id, span_id, http_status and attributes, and for log and node errors log_id with log_source; breakdowns over the range by build, node, hour (UTC, all 24) and http_status (top 20 each; breakdowns_truncated says which had more); and series, its occurrences over time with deploy markers (at most 50, the newest; markers_truncated is true if more existed, or, with no markers, if there were too many rows to compute any). from/to as ops.errors (default the last 24 hours). Next: pass an occurrence's trace_id to ops.trace with format=text; pass its log_id to ops.logs.context with source=<log_source> (and node=<node>); after a fix ships, ops.errors.resolve."},{"access":"read","method":"GET","name":"ops.red","path":"/api/ops/red","summary":"Which operation is failing or slow: per omniarc-control operation (omniarc.op), calls, rate (calls/s), errors (5xx) and error_ratio, and p50_ms/p95_ms/p99_ms interpolated from the latency buckets (5 ms to 10 s); p50_over, p95_over and p99_over say, each for its own quantile, that it is beyond 10 s (its value is then the 10 s bound: read it as > 10 s), and over is true if any of them is. With the slowest request's slowest_trace_id and the newest failure's last_error_trace_id; known is false for an op the stored metrics hold that this orchestrator no longer has (renamed or removed), which ops.red.series refuses. from/to take RFC 3339 or now-1h (default the last hour; 30 days kept). sort=errors (default), error_ratio, p95 or calls; at most 300 operations (truncated). From spanmetrics, flushed once a minute: the last minute may be missing. Next: pass op to ops.red.series; pass a trace id to ops.trace with format=text."},{"access":"read","method":"GET","name":"ops.red.series","path":"/api/ops/red/series","summary":"One operation over time: op (an operation name ops.red lists, e.g. node.list; anything else is a 400) and from/to as ops.red. points (at most ~120) with calls, rate, errors, error_ratio and p50/p95/p99 ms per step (and p50_over, p95_over, p99_over as in ops.red; a step with no spanmetrics rows has null, not 0); markers where omniarc-control's build changed (deploys; at most 50, the newest; markers_truncated is true if more existed, or, with no markers, if there were too many rows to compute any); slowest, the 5 slowest requests in the range, and recent_errors, the 5 newest failures, each with trace_id, and the failures with their error group. Next: pass a trace_id to ops.trace with format=text; pass a group to ops.errors.get."},{"access":"operate","method":"POST","name":"ops.errors.resolve","path":"/api/ops/errors/{group}/resolve","summary":"Triage an error group (needs operate): body {\"status\": \"resolved\" | \"ignored\" | \"open\", \"note\": optional, at most 500 characters}. resolved after a fix ships: the group shows as regressed if it occurs again after now. ignored hides it from ops.errors (status=ignored shows it) unless it starts spiking. open undoes either. The note is kept in the audit log with your name. group is the 16-hex id from ops.errors; a group with no occurrence in the last 30 days is a 404 and nothing is written. The answer is the group's new status, resolved_at and last_seen, and a warning when the last occurrence was under a minute ago (a burst still arriving will show as regressed)."},{"access":"operate","method":"POST","name":"ops.probe","path":"/api/ops/probe","summary":"Fail on purpose (needs operate): answers 500 \"ops probe: forced error\" and logs that sentence as an ERROR inside its own request, so within seconds ops.errors lists two groups carrying this deploy's build: a span group for op ops.probe and a log group for op omniarc_control::ops_probe (the logger's scope, so find it with source=log), and the trace opens in ops.trace. The post-deploy check that error tracking works end to end; resolve both groups afterwards."},{"access":"read","method":"GET","name":"ops.trace","path":"/api/ops/traces/{trace_id}","summary":"One request end to end: trace_id is 32 hex (from ops.errors, ops.errors.get, ops.red or a log line). Every span (at most 2000) depth-first with depth, offset_ms, duration_ms, status, message, build, attributes, orphan (its parent is missing), skew_ms (sticks out of its parent: clocks) and critical; up to 500 omniarc-control log lines with that trace id, each with its span_id; truncated says if either was cut. summary: root_op, duration_ms, span_count, errors (at most 20: span, op, message, group; errors_truncated says there were more, error_count is the whole count), slowest, critical_path (the chain that bounds the root's end), builds. format=text returns the same trace as an indented plain-text tree, one span per line with its logs under it, at most 400 lines: read that one. 404 when nothing has that id in 30 days. Next: an error span's group to ops.errors.get; a log line's id to ops.logs.context with source=orchestrator."},{"access":"billing","method":"GET","name":"billing.price_lists","path":"/api/billing/price-lists","summary":"Every price list, newest first, each with state current, upcoming or past and its prices in nano-EUR per billing unit (unit_price_nanos; 8000000 is €0.008), plus meters, the registry's key, label and unit. A meter missing from a list is unpriced. Needs billing."},{"access":"billing","method":"POST","name":"billing.price_list_create","path":"/api/billing/price-lists","summary":"Publish a complete price list: {\"effective_from\": a whole UTC hour in the future, \"note\": optional, at most 500 characters, \"prices\": [{\"meter\": a key from billing.price_lists' meters, \"unit_price_nanos\": 0 to 1000000000000}]}. Meters left out are unpriced. Once effective it can never change; 409 if a list already starts at that hour. Needs billing."},{"access":"billing","method":"DELETE","name":"billing.price_list_delete","path":"/api/billing/price-lists/{id}","summary":"Delete a price list that is not yet in effect (state upcoming). 409 once it is in effect: past prices never change. Needs billing."},{"access":"billing","method":"GET","name":"billing.discounts","path":"/api/billing/customers/{slug}/discounts","summary":"One customer's discount history, newest first: percent (\"12.50\"), effective_from, state, note, who set it and when, and current_percent in force now (\"0.00\" when none). 100 means metered but not billed. Needs billing."},{"access":"billing","method":"POST","name":"billing.discount_create","path":"/api/billing/customers/{slug}/discounts","summary":"Add a discount for one customer from a future whole UTC hour: {\"effective_from\", \"percent\": a string from \"0\" to \"100\" with at most two decimals, \"note\": optional}. Append-only: a later row supersedes it, nothing edits it. 409 if one already starts at that hour. Needs billing."},{"access":"customer:member","method":"GET","name":"prices.get","path":"/api/customer/prices","summary":"The price list in force now and any upcoming one, in nano-EUR per billing unit (unit_price_nanos; 8000000 is €0.008), each price with its meter's label and unit. current is null before any list is published. EUR."},{"access":"customer:admin","method":"GET","name":"costs.get","path":"/api/customer/costs","summary":"What this organization's usage costs, an estimate and not an invoice: totals (list_cents, discount_cents, net_cents, EUR cents floored), meters (quantity in billing units, the rates in force, unpriced), arcs then branches with gap_hours, series of net cents per meter per bucket, price_lists used, no_price_list, discounts, partial (the current hour is incomplete). from/to: RFC 3339, floored to the hour, to exclusive (default this UTC month to date); step=hour|day|month (default day; hour at most 31 days; any window at most 13 months). arc: one live arc's name, any case; totals, meters, series, arcs and no_price_list then cover that arc only (404 if no arc has that name)."},{"access":"billing","method":"GET","name":"billing.costs","path":"/api/billing/costs","summary":"Every customer's cost over a window, highest net first: slug, name, list_cents, discount_cents, net_cents (EUR cents, floored; each equals that customer's billing.customer_costs headline), discount_percent in force at the window's end, and series of net cents per bucket. Takes costs.get's from, to and step. Needs billing."},{"access":"billing","method":"GET","name":"billing.customer_costs","path":"/api/billing/customers/{slug}/costs","summary":"One customer's costs: exactly the body costs.get gives that customer (totals in EUR cents, meters, arcs, series, discounts), for the same from, to and step. Needs billing."},{"access":"billing","method":"GET","name":"billing.status","path":"/api/billing/status","summary":"Payments health: mode (off or test; live is refused by this build), key_present (whether a Mollie key was loaded, never the key), last_webhook_at and reconciler_last_run_at (RFC 3339, null before the first since this process started), and open_payments (payments Mollie has not finished: open, pending or authorized). In mode off every other payments operation answers 404 billing_off. Needs billing."},{"access":"billing","method":"POST","name":"billing.enrol","path":"/api/billing/customers/{slug}/enrol","summary":"Enrol one customer in billing for the running mode (test in this build): from now on it meets the card gate on arc.create and branch.create, and its first invoice period opens at the next whole UTC hour (usage before that is never invoiced). No body. 201 with billing.account_get's body; 409 if already enrolled or the customer is deleted; 404 billing_off when billing is off. Needs billing."},{"access":"billing","method":"PUT","name":"billing.exempt","path":"/api/billing/customers/{slug}/exempt","summary":"Exempt an enrolled customer from the card gate, or lift the exemption: {\"exempt\": true|false, \"note\": required when true, at most 500 characters}. Invoices are still issued, and charged when a card exists. 200 with billing.account_get's body; 404 not_enrolled before billing.enrol. Needs billing."},{"access":"billing","method":"GET","name":"billing.account_get","path":"/api/billing/customers/{slug}/account","summary":"One customer's billing account in the running mode: enrolled, account (enrolled_at, enrolled_by email, exempt, exempt_note, hold_since, period_start; null before billing.enrol), profile (the billing details the owner entered, tax_id_status from VIES), card (the valid mandate: label like Visa ···· 0000, expiry) and mandates (every card, revoked ones included; revoke_pending while Mollie's revoke of one is still being retried), periods (newest first: start, end (null while open), closed_at, invoice code, blocked: no_billing_profile while the closer holds the open one for missing billing details) and invoices (billing.invoices' fields). Also payments (newest first: mollie_id, purpose, attempt, invoice, amount_cents, status, failure_reason), events (the billing timeline, newest first: at, kind, detail, actor), outstanding_cents, unpaid ({code, status, amount_due_cents, issued_at, pay_link}), pay_link, period_start and accrued_cents. Needs billing."},{"access":"customer:admin","method":"GET","name":"billing_self.get","path":"/api/customer/billing","summary":"This organization's billing: mode (test, or off when billing is not running), enrolled, exempt, profile (the billing details), card (label like Visa ···· 0000 and expiry, or null), setup (the last card registration: id, state pending|added|failed, reason), hold ({since, reason}, or null), outstanding_cents (unpaid and disputed invoices), unpaid (oldest first: code, status, amount_due_cents, issued_at, pay_link), pay_link (the oldest open checkout among them, or null), period_start (the open invoice period) and accrued_cents (what the period has cost so far, the Costs page's net for it). Answers 200 with enrolled: false until an operator enrols the organization, and with mode: off when billing is off."},{"access":"customer:owner","method":"PUT","name":"billing_self.profile_set","path":"/api/customer/billing/profile","summary":"Replace the billing details printed on invoices (owner): {\"kind\": \"business\"|\"consumer\", \"legal_name\", \"tax_id\" (required for a business; a Spanish NIF, CIF or NIE is checked by its control character; another EU business's VAT number by its country's format, then VIES), \"country\" (ISO 3166-1 alpha-2), \"address_line1\", \"address_line2\" (optional), \"postal_code\", \"city\", \"invoice_email\"}. 400 names the rule that failed. VIES's answer goes in tax_id_status (valid, invalid, or unavailable when VIES is down), never a refusal. 404 not_enrolled before enrolment, 404 billing_off when billing is off."},{"access":"customer:owner","method":"POST","name":"billing_self.card_add","path":"/api/customer/billing/card","summary":"Start registering a card (owner): answers {\"checkout_url\", \"setup\"}; send the person's browser to checkout_url (a full-page navigation to Mollie's hosted checkout; the card number never reaches this API). Mollie returns them to /dashboard/billing?setup=…; poll billing_self.get until setup.state is added or failed. Replaces the current card once the new one is valid. A second call while one checkout is still open answers the same checkout. 409 no_billing_profile before billing_self.profile_set."},{"access":"customer:owner","method":"DELETE","name":"billing_self.card_remove","path":"/api/customer/billing/card","summary":"Remove the card on file (owner). Allowed, but afterwards arc.create and branch.create answer 402 payment_method_required (unless an operator exempted the organization), and the next invoice is paid through a pay link instead of charged. 404 when there is no card."},{"access":"billing","method":"GET","name":"billing.seller_get","path":"/api/billing/seller","summary":"The seller every invoice of the running billing mode names: {mode, seller: {legal_name, tax_id, address_line1, address_line2, postal_code, city, country, email, invoice_footer, updated_at, updated_by} or null until billing.seller_set}. Needs billing."},{"access":"billing","method":"PUT","name":"billing.seller_set","path":"/api/billing/seller","summary":"Replace the seller profile of the running billing mode: {\"legal_name\", \"tax_id\", \"address_line1\", \"address_line2\": optional, \"postal_code\", \"city\", \"country\": \"ES\" (the seller is Spanish), \"email\", \"invoice_footer\": optional, at most 500 characters}. Snapshotted onto each invoice at issue, so a change never alters an issued one. 400 names the field. Needs billing."},{"access":"billing","method":"POST","name":"billing.close_now","path":"/api/billing/customers/{slug}/close","summary":"Test mode only: close one enrolled customer's open period now, at the last whole UTC hour that ended at least 15 minutes ago (so that hour's usage sweeps have landed and the invoice equals costs.get for the window), into an invoice (series T: lines from the cost engine for exactly that window, Spanish VAT, a stored PDF), and charge it on issue. No body. 201 with the invoice; 409 period_empty when no such hour has ended since the period began (try again after a quarter past the hour), no_open_period when the closer closed it meanwhile, rollup_pending while usage is still being rolled up (retry in minutes), no_billing_profile, no_seller_profile; 404 not_enrolled. Next: billing.invoice_get. Needs billing."},{"access":"billing","method":"GET","name":"billing.invoices","path":"/api/billing/invoices","summary":"Every invoice and credit note of the running billing mode, newest first: code (T2026-000001, TR… for a credit note), kind, status (issued, paid, void, disputed), period_start, period_end, issued_at, net_cents, vat_cents, total_cents, amount_due_cents (EUR cents; negative on a credit note), paid_at, corrects, customer {slug, name}. status= filters. One customer's periods and invoices: billing.account_get. Needs billing."},{"access":"billing","method":"GET","name":"billing.invoice_get","path":"/api/billing/invoices/{code}","summary":"One invoice or credit note by code: billing.invoices' fields plus lines (description, quantity, unit_price_nanos, list_cents, net_cents; they sum to net_cents), vat_regime, vat_rate_bp, vat_percent, legend, seller and buyer as snapshotted at issue, reason, credit_notes, customer, and unpriced {no_price_list, meters}: usage in the period no price covered, which was not invoiced (null on a credit note). Next: billing.invoice_pdf. Needs billing."},{"access":"billing","method":"GET","name":"billing.invoice_pdf","path":"/api/billing/invoices/{code}/pdf","summary":"The PDF of one invoice or credit note exactly as rendered and stored at issue: application/pdf, Content-Disposition attachment; filename=\"{code}.pdf\". Needs billing."},{"access":"billing","method":"POST","name":"billing.credit_note","path":"/api/billing/invoices/{code}/credit-notes","summary":"Issue a credit note (series TR) against an invoice: {\"amount_cents\": optional, the gross to credit — default and maximum what is not yet credited, \"reason\": required, at most 500 characters, printed on it}. Same VAT regime and rate as the original; negative net, VAT and total, the VAT always the rule's for its net; one line \"Rectification of {code}: {reason}\". Unpaid: the amount due drops by it, and at zero the invoice is paid. Paid: the amount is refunded on its payment. 201 with the credit note; 400 names the cap, or the nearest amounts that can be credited (also as `nearest_cents`, ascending) when no net plus its VAT (rounded half up) comes to the one asked; 409 for a credit note, a disputed or void invoice, or one credited in full; 404 no invoice with that code. Audited against the invoice, with the reason. Needs billing."},{"access":"customer:admin","method":"GET","name":"billing_self.invoices","path":"/api/customer/billing/invoices","summary":"This organization's invoices and credit notes, newest first: code, kind, status, period_start, period_end, issued_at, net_cents, vat_cents, total_cents, amount_due_cents (EUR cents), paid_at, corrects. 404 not_enrolled before an operator enrols the organization; billing_off when billing is off."},{"access":"customer:admin","method":"GET","name":"billing_self.invoice_get","path":"/api/customer/billing/invoices/{code}","summary":"One of this organization's invoices or credit notes by code: the list's fields plus lines, vat_regime, vat_rate_bp, vat_percent, legend, seller, buyer, reason and credit_notes. 404 for a code that is not this organization's."},{"access":"customer:admin","method":"GET","name":"billing_self.invoice_pdf","path":"/api/customer/billing/invoices/{code}/pdf","summary":"One of this organization's invoices as the PDF stored at issue: application/pdf, Content-Disposition attachment; filename=\"{code}.pdf\"."},{"access":"billing","method":"POST","name":"billing.hold_release","path":"/api/billing/customers/{slug}/hold/release","summary":"Lift a customer's billing hold by hand: {\"note\": required, at most 500 characters, shown on their billing timeline and audited}. A hold refuses arc.create, branch.create and branch.wake with 402 billing_hold, and lifts on its own when the last unpaid invoice is paid; dunning does not put it back for the same invoice. 200 {\"released\": true}; 409 no_hold when there is none; 404 not_enrolled. Needs billing."},{"access":"billing","method":"POST","name":"billing.mark_paid","path":"/api/billing/invoices/{code}/mark-paid","summary":"Mark an unpaid or disputed invoice paid out of band, e.g. by bank transfer: {\"note\": required, at most 500 characters, on the timeline and audited}. Open card payments and pay links for it are cancelled where Mollie allows; one that still pays is refunded in full automatically. Lifts the hold when nothing else is owed and mails a receipt. 200 {\"invoice\", \"status\": \"paid\"}; 409 invoice_paid or nothing_due when nothing is owed. Needs billing."},{"access":"billing","method":"POST","name":"billing.charge_retry","path":"/api/billing/invoices/{code}/retry","summary":"Charge an unpaid invoice's amount due on the customer's valid card now, as a new attempt (Idempotency-Key {invoice_id}-{attempt}). 200 {\"invoice\", \"payment\": the Mollie payment id}; 409 payment_open while a charge or pay link for it is still open, no_valid_card, invoice_paid, invoice_disputed (a chargeback: use billing.mark_paid) or nothing_due; 502 when Mollie cannot be reached or refuses. Needs billing."},{"access":"customer:owner","method":"POST","name":"billing_self.pay","path":"/api/customer/billing/invoices/{code}/pay","summary":"Pay one of this organization's unpaid invoices now with any method Mollie offers (owner): answers {\"checkout_url\"}, the invoice's open pay link or a fresh one, never a second open payment; send the browser there. 409 payment_open while the card is being charged for it, invoice_paid once it is paid, invoice_disputed or nothing_due; 404 for a code that is not this organization's; 404 not_enrolled."},{"access":"billing","method":"GET","name":"billing.accounts","path":"/api/billing/accounts","summary":"Every customer enrolled in the running billing mode, by slug: exempt, enrolled_at, hold_since (null when not held), card ({label, expiry} or null), outstanding_cents (unpaid and disputed invoices), accrued_cents (costs.get's net for the open period so far), period_start, last_invoice ({code, status, total_cents, issued_at} or null). EUR cents. Needs billing."}],"service":"omniarc-control","version":"0.1.0"}