api

Overview ¶

Command api serves the public Arnakoff HTTP API.

It listens on ARNAKOFF_ADDR (":8100" by default) and stops cleanly on SIGINT or SIGTERM, letting in-flight requests finish. /healthz answers while the process runs, /readyz once every snapshot is loaded.

GET /v1/check reads the lists of the snapshots the sync command stores and queries RDAP, SIRENE and BODACC by identifier, for at most ten seconds a check. The snapshots are restored at start, then looked for every minute and swapped in without a restart; the lists themselves are never downloaded here. A stored snapshot that cannot be reloaded is logged once, until it reloads again.

POST /v1/check/batch checks up to ARNAKOFF_BATCH_MAX_ITEMS inputs (50 by default) in one request, a few at a time, within the time of one check: an input still waiting then has its registries reported unavailable.

Both check routes require an API key, "Authorization: Bearer ark_live_…" (RFC 6750): its keyed digest is looked up in the PostgreSQL database of ARNAKOFF_DATABASE_URL under ARNAKOFF_API_KEY_SECRET, and only keys of ARNAKOFF_API_KEY_ENV ("live" by default) are accepted. Both variables are required to start. The database is not reached at start: while it is unreachable, the check routes answer 503, never unchecked. Keys are issued and the schema migrated by the admin command. At start, then once a day, the records of the keys revoked more than a year ago are deleted (ADR 0006), which the database role of the API must be allowed to do; a failed purge is logged and tried again the next day.

Each API key may send ARNAKOFF_RATE_LIMIT_KEY requests a minute to the check routes (60 by default), and each client address ARNAKOFF_RATE_LIMIT_IP to the routes needing no key (30 by default); the probes are never limited. Each client address may also send ARNAKOFF_RATE_LIMIT_AUTH refused keys a minute to the check routes (30 by default): over it, its keys are answered 429 without being looked up, so a flood of unknown keys cannot hold the key database. The limits are kept in memory, per instance. Behind a proxy, ARNAKOFF_TRUSTED_PROXIES lists its CIDR prefixes, whose X-Forwarded-For field then tells the client's address; "none" says no proxy stands in front. Behind a platform that overwrites a field with the client's address, such as X-Real-IP on Scaleway Serverless Containers, ARNAKOFF_CLIENT_IP_HEADER names that field instead: one valid address in it is the client's, otherwise the peer's. One of the two is required to start with live keys.

POST /v1/demo/check is the demo access of the site's checker: one check without a key, its input in the body. It is on when ARNAKOFF_DEMO_ORIGIN and ARNAKOFF_TURNSTILE_SECRET are both set: CORS then allows that origin only, and each request must carry a Cloudflare Turnstile token, checked once with siteverify for the origin's host. Each client address may send ARNAKOFF_RATE_LIMIT_DEMO demo checks a minute (10 by default), every client together ARNAKOFF_RATE_LIMIT_DEMO_GLOBAL (300 by default). Off, the route answers 503.

POST /v1/keys/request mails a login link, valid 15 minutes, to the address of its body, and POST /v1/keys/redeem trades the link's token for a free API key of ARNAKOFF_API_KEY_ENV, revoking the key the address had. They are on when ARNAKOFF_SMTP_ADDR is set, the "host:port" of a server speaking TLS at once (port 465), with ARNAKOFF_SMTP_USERNAME and ARNAKOFF_SMTP_PASSWORD, and the demo access is on: each link request carries a Turnstile token, and CORS allows the demo's origin only. The links are sent from ARNAKOFF_MAIL_FROM (contact@arnakoff.com by default) and open ARNAKOFF_LOGIN_LINK_URL (https://arnakoff.com/cle by default), the token in its fragment. Each client address may send ARNAKOFF_RATE_LIMIT_KEY_REQUEST requests a minute to both routes (5 by default), and each email address receive ARNAKOFF_RATE_LIMIT_KEY_REQUEST_ADDRESS links an hour (3 by default); over it, a request is answered the same and no link is sent. Off, the routes answer 503.

POST /mcp is the remote MCP endpoint, over the Streamable HTTP transport without session: the check and list_sources tools of the mcp command, behind the same API key and the same quota as the check routes, each request spending one.

Its errors are RFC 9457 problems typed under ARNAKOFF_PROBLEM_BASE_URL, the documentation of the errors on the site.

"api probe" asks GET /healthz of the API the same configuration serves, on 127.0.0.1 when ARNAKOFF_ADDR listens on every interface, and exits 0 when it answers 200 within two seconds, 1 otherwise: the health check of the container image, which has no shell. Any other argument exits 2.