The API

Base URL and hosts

/api/admin/* answers only on the admin host. Anywhere else those paths return 404, not 403: the admin surface is not discoverable from the main site. That gate sits in front of the role check and neither implies the other.

Authentication

Two mechanisms, both resolving to the same thing — an account. A key is for a script; a session cookie is for a browser.

curl -s https://geodzk.com/api/links -H "X-API-Key: $GEODZK_KEY"

• A key is not ambient, so it cannot be replayed by a hostile page and needs no CSRF token. Keys are stored as a digest; the secret is shown once and is not recoverable.
• A session cookie is ambient, so every state-changing request from a browser must also carry the session's X-CSRF-Token. The token is a property of the session, not of the account.
• There are two cookies in the whole service: the session, and a short-lived handle for an in-flight passkey ceremony. Both are HttpOnly, SameSite=Lax, and Secure whenever the browser's leg was HTTPS.
• Minting keys, adding passkeys and changing two-factor settings are session-only. A key can never mint another key, however broadly scoped — otherwise a narrow credential could widen itself.

Roles and scopes

A role belongs to a person and is the ceiling on what they can ever do. A scope belongs to a credential and is a subset of what its owner may do. The effective permission of any request is the intersection of the two, computed from the account's current role — so demoting somebody narrows every key they already hold in the same instant, with nothing to revoke and no cache to expire.

An unknown role grants nothing. That is not padding: a future migration that forgets a role string must lock the account down rather than open it up.

Conventions

• Request and response bodies are JSON. Send Content-Type: application/json.
• Timestamps are ISO 8601, UTC, second resolution. They sort correctly as strings, which is why they are stored that way.
• code is the full key as it appears after /l/ — either a bare root code or a namespaced one. Paths that take a code accept the slash, so DELETE /api/links/alice/reading is right.
• 0 in any limit field means no limit, never none allowed.
• A successful delete returns 204 with no body.
• Response fields are added, never removed or repurposed. Read the ones you know and ignore the rest.

Errors

One shape, everywhere. Branch on error.code; show error.message.

{"error": {"code": "quota_exceeded",
           "message": "You have used 500 of your 500 links."}}

No error path returns a stack trace, a SQL fragment or a library's internal message. The one exception to the shape is deliberate: anything under /l/ is followed by a person in a browser, so a dead short link answers with a page rather than JSON.

Rate limits and ceilings

The instance-wide buckets exist because a per-subject limit cannot defend the box on its own: an attacker picks the subject and can send a different one every time. For sign-in that subject is a username and each attempt costs a full password hash by design; for collections it is a slug, and a spread across many slugs is exactly how a flood defeats a cache. Both buckets must allow a request, and the global one is charged only after the per-subject one allows — so one noisy account cannot lock everybody else out.

Following a short link is never throttled. Throttling the product to protect against nothing is not a trade worth making.

Lowering a ceiling never deletes anything. PATCH /api/admin/settings answers with a warnings array when a new ceiling is below current usage, and creation simply stops until things are back under it.

Who may call what

The public surface

The redirect is the whole product, so its order of resolution is worth stating exactly. Referrer-Policy: no-referrer on every hop means the destination never learns which short link sent somebody, or that geodzk was involved at all.

A published collection as JSON, for anybody putting one on their own page:

{"slug":"reading-list","name":"Reading List","owner":"alice","count":2,
 "truncated":false,"limit":500,
 "links":[{"code":"alice/lwn","short_url":"https://geodzk.com/l/alice/lwn",
           "target_url":"https://lwn.net/","title":"LWN",
           "is_favorite":true}]}

• Sent with Access-Control-Allow-Origin: *, because a published collection is public by definition.
• Click counts and last-access times are not included. Those are the owner's operational data.
• truncated is true when the collection holds more than limit links and only the first limit came back. A client paginating on count alone would otherwise conclude it had everything.
• Cached as max-age=0, s-maxage=30: a shared cache absorbs a flood while the browser always revalidates, so unpublishing takes effect on the next request rather than half a minute later. The owner pressed Unpublish and expects it to mean now.

Links

{"code":"alice/hello","namespace":"alice","local_code":"hello",
 "short_url":"https://geodzk.com/l/alice/hello",
 "target_url":"https://example.com/hello","title":null,
 "group_id":null,"group_name":null,"is_favorite":false,
 "created_at":"2026-08-16T12:45:25+00:00","click_count":0,
 "last_click_at":null,"active_from":null,"expires_at":null,
 "max_clicks":null,"fallback_url":null,"disabled":false,
 "removed_tracking":[]}

Tracking parameters come off url and fallback_url before either is stored — utm_*, fbclid, gclid, and the rest of a short, fixed list of identifiers that route on no server anywhere. removed_tracking in the response names what came off, sorted, and empty when nothing did. Send "keep_tracking":true to store the URL exactly as given instead. ref is deliberately never touched: it selects a revision on some sites, so scrubbing it would silently retarget the link rather than clean it.

• PATCH edits target_url, title, group_id, is_favorite, active_from, expires_at, max_clicks, fallback_url and keep_tracking. A resubmitted URL that matches what is already stored is left alone rather than re-scrubbed — an unedited field is not a retarget, so keep_tracking only has anything to say when the URL is actually changing. The code, the namespace, the click count and the owner are not editable through the API at all. Retargeting writes an audit row.
• DELETE removes the link and retires its code permanently. A code that has been printed, pasted or turned into a QR outlives the row behind it, so letting somebody else claim it would silently retarget every one of those. Deleting an account retires all of its codes the same way.
• The QR route encodes the short URL, never the target. A QR of the destination cannot be retargeted, cannot be expired, counts no clicks, and prints somebody's destination onto the object in a form any camera reads.
• It answers with svg and print_svg: one drawn for a screen, one larger and asking for a higher error-correction floor, for something that will be folded or left on a window.
• The print route holds one card at 45×21mm, 85×55mm or 148×210mm, or cut: eight butted edge to edge on A4 with trim marks, so one cut serves two cards. A card carries the code, the short URL, an optional title and an optional date — never a click count and never a name.
• Both are owner-scoped: a code you do not own answers exactly as one that does not exist, because the difference would confirm it is there. Both are rate-limited despite being reads, because they turn a request into real arithmetic without touching a row.

Masked links

A masked link's target is sealed before this request is ever sent — the client generates a key and a code, encrypts the target under both, and this service is handed only the result. Every field is the client's own choice: the code (drawn the same way codes.new_masked_code draws one), the ciphertext, and the mode. Nothing here decrypts anything, and nothing here learns a target, in either mode.

• manage_hash is sha256(manage_token) hex, computed once by the client at creation. Only the client holds manage_token itself; retargeting or deleting presents the token, never the hash, and this service compares it in constant time against the stored hash.
• A masked link has no owner. Authority to retarget or delete it is manage_token alone — not an account, not a session, not the link's own key, which every recipient holds and which would make the link revocable by anybody it was sent to.
• PUT and DELETE both answer the identical 404 — same status, same body — for a code that does not exist and for the right code with the wrong token. The two are not told apart.
• Nothing on these three routes writes an audit row or logs a line naming the code or the caller. An audited "who created or changed code X" is exactly the attribution a masked link exists to remove.
• What masked links are for, the two modes, and their limits, in prose: Masked links.

Groups and collections

• {"visibility":"public"} allocates a slug on first publish and keeps it stable afterwards, so unpublishing and republishing does not break a URL you already shared — and renaming the group keeps the same slug, so a title is free to change without claiming more URL space. The reply carries public_url and embed_url.
• Deleting a group that was ever published retires its slug permanently. The allocator hands out the first free name matching the title, so without this Alice could publish "Reading" at /c/reading, share it, delete the group — and Bob's own "Reading" would then be given that slug, silently pointing everyone holding Alice's URL at Bob's collection.
• Groups are capped because every group can be published and every published group is a distinct unauthenticated URL that renders HTML — and distinct URLs are how a flood defeats a cache. GET /api/me carries group_quota so a client can show the allowance before it is reached.

Keys

{"name":"backup script","scopes":["links:read","docs:read"],
 "expires_in_days":90,"agent":false}

• Two independent gates: the requested scopes may not exceed your role, and may not exceed what the calling credential currently holds.
• docs:read arrives ticked on the form because it reads these public pages and touches no account data. Every other scope is left for a person to choose, and unticking this one is a click.
• "agent": true adds agent_brief to the reply: a plain-text briefing to hand over instead of a bare secret. It names the header, the base URL, the scopes and the endpoints they reach, the lifetime, whose account it acts as, where a secret may not be put, that a 429 or 409 is not fixed by retrying — and it points at AI instructions for the rest. The briefing contains the key, so the whole block is the secret.
• The agent flag is metadata: authentication never reads it, so an agent key is exactly as powerful as the same key without it. What it changes is that the key is labeled agent-held in the list, in the audit row, and in the admin plane's per-account summary.
• GET /api/keys/self answers a different question from GET /api/keys and needs no scope: which key am I holding? Without it an agent could not tell its owner "the key I am using is called reserch bot and expires in nine days" — the sentence that gets a typo noticed. A browser session gets a 400 pointing at GET /api/keys, because a session is not a key.
• PATCH takes a name and changes nothing else. A name is a label: correcting one never requires the key to be reissued — which for an agent key would mean redistributing a credential over a spelling mistake. It is session-only for a reason of its own: the list of names is what an owner reads to spot a key they do not recognize, so a stolen key able to relabel itself could hide in that list.

Documentation

The same pages you are reading. They are public HTML as well, so a refusal here names the URL that needs no credential rather than stopping at no.

Account and session

{"ok":true,"username":"alice","role":null,
 "mfa_required":true,"mfa_enrolment_required":false}

• role is null until the sign-in is actually finished. A password alone should not reveal whether it opens an admin account. Read the role from GET /api/me once the second factor has passed.
• A session carrying mfa_required or mfa_enrolment_required authenticates nothing: every endpoint but the two-factor ones answers 401 until the second factor is presented, and it expires in ten minutes rather than the usual fortnight.
• GET /api/me carries identity, scopes, the link and group quotas, and the rename state — enough for a client to show an allowance before it is reached.
• Sign-up is invitation-only or closed, and cannot be opened by an environment variable. An invitation is single-use, carries the role it will grant, and cannot grant admin.

Changing a username is not a cosmetic edit — a username is a namespace — so the endpoint is shaped accordingly.

• acknowledge: true is required, not a formality: without it the call is refused with a message naming the URLs that will stop working and the wait that will start.
• The wait is enforced in the WHERE clause of the single statement that performs the rename, so it holds across sessions, devices, keys, reloads and two requests arriving at once. Admins are bound by it too.
• The first change is always free — the common case is an invited account fixing a name somebody else chose.
• 409 code_collision means some of the account's codes already exist or are retired under the new name, and nothing was changed. Half a rename would be an account split across two namespaces.

Two-factor and passkeys

• Starting an enrollment changes nothing. The candidate secret is staged separately and promoted only once a code from it has been proved, so an abandoned re-enrolment leaves a working authenticator exactly as it was.
• A half-signed-in session may only enroll an account that has no authenticator yet. Replacing a confirmed one needs a fully authenticated session, or a pass phrase alone would be enough to walk past the second factor.
• Codes are single-use within their window — the accepted step is recorded, so the same code cannot be replayed for the rest of its thirty seconds — and drift tolerance is one step either side, no more.
• Passkey sign-in is usernameless: no credential list is sent, so the authenticator offers the account itself and the endpoint cannot be used to test whether a username exists.
• A passkey skips the six-digit step only when the assertion actually verified the user with a PIN or a biometric. One that merely proved presence is a single factor and gets the same second step a pass phrase does. An account can demand both anyway.
• Ceremony challenges are single-use, expire in five minutes, and are looked up by a handle in a short-lived cookie — never supplied in the request body, where a caller could choose their own.
• Registering does not ask for a name first: collecting one up front put a dialog between the user's gesture and the browser's credential call, which cost the ceremony its user activation on mobile. The reply carries the new id and name so a client can offer to rename it straight after.

Asking the operator for something

Three channels from an account holder to the operator, all of which exist because the alternative was a dead end. They split on attribution: a code request names its requester, because the answer is a code released into that person's namespace. Feedback and browser reports record nobody.

• A code request is accepted only for a code you could actually claim if it were released — your own namespace, or the root namespace if you are an admin. Anybody else's namespace is refused before anything is looked up, because the answer would otherwise confirm that another account's code exists.
• Feedback requires an account and records no author. Those two are separable and this is where they separate: authentication is what makes the rate limit real, while the stored row identifies nobody. There is no author column, no audit entry, and the note carries only the day it arrived, in no order — because the audit log does record who did what and when, the nightly backups record what arrived each day, and anything finer than either would be a correlation handle against them.
• A browser report is a counter, not a log: one row per engine and version holding a works count, a problems count and a day. No per-submission row exists at all, so two increments are indistinguishable from one person reporting twice.
• Reports change nothing by themselves. Promoting an engine to tested by user is a separate, audited action in the admin plane: taking a stranger's word is a decision somebody makes, not a thing that happens.
• Where anonymity gives up more than a note does, and the form says so: a sentence is drawn from an unbounded space and an engine-and-version pair is not. On a small instance a rare engine narrows to whoever is known to run it.
• Several reports travel in one request, because the limit is per submission. A limit with no way to batch would bound how much somebody can tell you rather than how much they can waste.

The admin plane

Answers only on the admin host, and only to an account with the admin role. Every write is audited.

• The account list deliberately returns no links, groups or keys — only counts. The admin plane manages who exists, not what they have.
• There is no admin rename endpoint: it would be a second path to the same state with a weaker guard on it. A username field in a user patch is ignored rather than applied, and an operator who needs to rename somebody does it on the box.
• Retired usernames and retired collection slugs have no release. A short code is scarce — summit is worth reclaiming — so releasing one is a real decision with a warning attached. A username is not scarce, so there is nothing to weigh against the harm of handing somebody a namespace that has already had links published under it.
• Granting a code request releases the code in the same action, because marking it granted and forgetting to release it leaves the requester looking at an answer they cannot use. That is safe only because a request is accepted for the requester's own namespace, so the release opens the code to exactly one person.
• Moderation is the one place an admin looks another account's link up on purpose. Running a shared service on your own domain means being able to answer an abuse report, and pretending otherwise makes the capability undocumented rather than absent. So it is narrow — one code, no listing, no search — and every use writes an audit row naming the admin, the code and the target they saw. That is true of ordinary links only: a masked link is not in the table this reads, and its counterpart can turn one off or on and nothing more. It cannot say where a masked link goes or who made it, so its answer and its audit row carry the code and the decision, and no target.
• The honest caveat: the audit log is not a listing, but it is not blind either. It records a creation with its code and a retarget with its new URL, so an admin reading far enough back can learn codes and some targets without touching moderation. That is kept deliberately — retargeting is the change most worth reconstructing after the fact — so the accurate claim is that no route enumerates another account's links, not that an admin cannot learn of them. An operator who wants neither can purge the log. Masked links are not in it: nothing is audited when one is made, changed or deleted, and the only masked row it can hold is an admin turning a code off or on.

The metrics endpoint has three properties worth knowing before reading a chart drawn from it. Every point is the peak of its bucket rather than the mean, because averaging is precisely how a spike disappears and spikes are the reason anybody looks. The limits come from the samples, so a percentage is against the ceiling that actually applied. And a rate needs two readings, so the first sample in a window carries no figure and a long gap is left as a gap rather than drawing a plateau over an outage.

Stability

This is a small service shared with people its operator knows, not a public platform, and it is versioned accordingly: there is no /v1/ prefix and there will not be one until something outside this repository depends on it.

• Response fields are added, not removed or repurposed. A client that reads the fields it knows and ignores the rest keeps working.
• error.code values are stable. Branch on those, never on error.message, which is prose written for a person and gets reworded.
• Paths are stable — /l/{code} most of all, since every short link ever issued depends on it. That is why the interface claims /, /api/*, /c/…, /embed/…, /docs/… and /healthz, and redirects live under /l/ alone.
• There is no served OpenAPI document, and every route is kept out of the schema. An interactive schema browser on a public host is a map of the attack surface for no benefit to the handful of people using this. If a real integration ever needs a machine-readable schema, the right move is to generate it into the repository as a file rather than serve it live.

What is deliberately not here

Absences a client author would otherwise waste time looking for.

• No analytics endpoints. A click count and a last-access time per link, and nothing else. The web server's own access log is off for the same reason.
• No email, anywhere. There is no email column in the schema and no mail is ever sent. That is a privacy decision with a real cost: recovery is single-use codes or an operator reset, not a link in an inbox. Invitations are delivered by a person.
• No pass phrase reset endpoint, and no two-factor reset endpoint. Both are commands on the box, for the same reason: the operation is not something a request should be able to reach, and anybody who can run it already holds the database file.
• No bulk or search endpoints across accounts. Every query that touches account data takes an account id, which is a property of the storage layer rather than a rule route authors have to remember.
• No pagination, except on the audit log. Quotas bound every other collection to a size that fits in one response. The exception is a public collection page, whose ceiling is about the cost of one anonymous request rather than about storage — so it must not move when a quota does.
• No webhooks or callbacks. The service makes no outbound HTTP requests at all, which is why a shortened target can never be used to make it fetch something.
• No search endpoint. The largest read here is bounded by the link quota, so a client fetches the list and filters it — which is what the dashboard does.