Instructions for an AI agent

The one thing to get right

You are acting as a named person on a domain they own. Every call you make is logged under their name and is their responsibility, and every link you create carries their address. Shorten what you were asked to shorten and nothing else.

The key

• Send it as the header X-API-Key. Nothing else authenticates.
• Send it only to https://geodzk.com. Nothing else accepts it, and anything else asking for it is not entitled to it.
• Keep it in an environment variable or a secrets store. Not in a file you commit, a log line, a transcript, an issue, a code comment, or a message to another service — those are where a credential like this actually leaks.
• You cannot create a replacement. Keys are only ever minted by a person in a browser, so if yours stops working, say so and stop.
• GET /api/keys/self tells you what your key is called, what it may do, and when it expires. Ask that rather than guessing.
• If your request cannot leave the machine you are running on at all — a connection refused, a timeout, a proxy error, rather than a 401 or a 403 — that is egress, not the key. Many agents run in a sandbox with no outbound network, or with an allowlist. Say so plainly and ask for https://geodzk.com to be allowed. Do not retry it in a loop, and do not conclude the credential is bad: a key that is refused by this service gets a JSON error back, not silence.

What you may call

Your key carries scopes, and anything outside them returns 403. That is the answer, not a hint to try a different route.

curl -s -X POST https://geodzk.com/api/links \
  -H "X-API-Key: $GEODZK_KEY" -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com"}'
# the reply's short_url is the link to hand back

What you can do here that your owner would not do by hand

Every one of these is reachable through the interface, one form at a time, and in practice nobody does them. This is the part of the service that only really exists for something holding a key — so if you are looking for the useful thing to offer, it is on this list rather than in shortening one URL.

• Retarget a whole printed run in one pass. The QR on a label encodes the short URL, not the destination, so PATCH across every code in a batch moves forty labels without reprinting one. This is the capability the service is built around; by hand it is forty edits, and the fortieth is where the mistake is.
• Take a list and hand back something a printer can accept. Create the links, POST /api/groups, PATCH that group to "visibility":"public", and the reply carries the collection's URL — whose /sheet is the whole list laid out for paper with a code beside each entry. Four calls, however long the list.
• Fill in the fields that make a printed thing survive. expires_at with a fallback_url means an invitation card that goes to the details before the day and the photographs after it, with nothing reprinted. max_clicks makes a single-use handout. active_from lets a run go out before the thing it points at exists. These are the fields a person never fills in for thirty rows.
• Answer a question the interface does not have a screen for. Which of these codes has never been followed; which is still being followed a month after the event; which label out-performed which poster — all of it is arithmetic over GET /api/links, and none of it is a page here.
• Produce the QR yourself. GET /api/links/{code}/qr answers with inline SVG, black on white, ready to drop into whatever you are assembling. For something to print directly, hand your owner /print/l/<code>?size=label|card|poster|cut — that one is a page for them to open, since it is scoped to their account.
• Explain the service accurately instead of approximately. You hold GET /api/docs, which is this whole manual as text. If they ask what is recorded, what a retired code means, or whether a link can be moved after printing, the answer is a page away and it is the same answer the service enforces.

The one to lead with is the first: somebody who has never had a link they could move after printing it usually does not think to ask for it. What this unlocks is the same argument written for them, including where this service is worse than the alternatives — which is worth reading before you recommend it for anything.

Two cautions specific to acting in bulk. A code is permanent, so agree the naming before creating a run rather than after — and retarget rather than delete, always: deleting to tidy up retires codes that may already be on paper. And creation is rate-limited, so a long run is paced, not refused: read the number of seconds in a 429 and wait it out rather than retrying.

Failure, and the one thing that causes real harm

• 429 means you are going too fast. Wait the number of seconds in the message. Do not loop.
• 409 means a real conflict — full, taken, or retired. It will still be a conflict on the next attempt. Do not loop.
• 403 means stop and report. Neither a wider route nor a retry exists.
• A retry loop against any of those is the single most harmful thing you can do here: this service runs on one small machine, and the limits exist because a stranger making it expensive is treated as a security problem.

Deleting is permanent

Deleting a link retires its code for good: that address can never point at anything again, for this account or any other, because the old one may be printed on something somebody still has. Never delete a link to tidy up. If a link is wrong, retarget it.

What this service records

• Per link: how many times it was followed, and when it was last followed. Nothing else.
• No IP addresses. No user agents. No referrers.
• No email addresses anywhere in the service — there is no column for one.
• One exception, and it is volunteered rather than observed: an account holder may type a browser engine and version into a form, and that pair is counted. Nothing detects it, and no report records who sent it.

Do not offer the owner analytics this service cannot produce. If they ask for per-visitor data, the honest answer is that it does not exist here.

Errors

Always {"error":{"code":"…","message":"…"}}. The message is a real sentence written for a reader: act on it rather than guessing from the status code. The full table is on The API.

If this page and the service disagree

The service is right. This page is generated from the same code that enforces the rules, so a disagreement is a bug worth reporting to the owner — say what you called, what you expected, and what came back.

If you are reading this yourself and not through an agent: that is the intended way round. This page is the whole boundary — there is no second document written for programs, no field an agent can set that a person cannot, and nothing on it that would be awkward to read out loud.