Link API

The API creates anonymous short links, returns their click statistics, changes their settings and deletes them. Requests and responses use JSON. CORS is enabled, so calls work from browser code as well.

Base address:

http://anonym.es/api/v1

Quick start

To create a short link, send the destination address:

curl -X POST http://anonym.es/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

With an account token the same call puts the link into your dashboard and counts it against your plan:

curl -X POST http://anonym.es/api/v1/links \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

The response contains the short address, the link id and the token that manages this link. Keep the token: it is needed to read or delete the link later.

{
  "ok": true,
  "link": {
    "id": 4821,
    "short": "http://anonym.es/k7m2q",
    "url": "https://example.com/article",
    "status": "active",
    "password": false,
    "created_at": "2026-09-05T14:02:11Z",
    "expires_at": null,
    "max_hits": null,
    "self_destruct": false,
    "delay": null,
    "no_countdown": false,
    "adult": false,
    "note": null,
    "tags": [],
    "clicks": 0,
    "uniques": 0
  },
  "token": "3f9c1b7e2d4a4c0e9b8f7a6d5c4b3a21",
  "left": 4
}

Fields of the link object

All endpoints that return a link use this structure. Timestamps are ISO 8601 in UTC. The clicks and uniques counters cover the entire lifetime of the link.

Authorization

Authorized requests carry the token in the Authorization header. The X-API-Key header is accepted as an alternative. Tokens are never passed in the query string.

Authorization: Bearer YOUR_TOKEN

An account token starts with anon_. A link token consists of 32 characters. Generating a new account token invalidates the previous one.

Example:

curl http://anonym.es/api/v1/me \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Generate an account token in the dashboard

Endpoints

Request bodies may be sent as application/json or as application/x-www-form-urlencoded. Parameter names and error codes are identical across all endpoints.

The cost is given in rate-limit units, see Rate limits.

Creating a link

POST /api/v1/links

The minimal request contains only the url field:

curl -X POST http://anonym.es/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

With an account token the link belongs to the account and counts against its plan. Without a token it is a guest link on the IP quota:

curl -X POST http://anonym.es/api/v1/links \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

A successful request returns status 201 together with the link, its token and the number of links left in the current quota period.

Fields of the response:

Link with a custom name

The short address gets the name my-article if it is free and meets the rules below.

curl -X POST http://anonym.es/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article","name":"my-article"}'

Name rules:

• Latin letters, digits, hyphen and underscore. From 5 characters on the Free plan and from 3 on paid plans, up to 32. Case does not matter: Promo and promo are the same link.
• Page names, language codes and service words are reserved.
• Brand names and offensive words are refused. Names pass a word list and an automated review. The number of custom names per hour is limited by plan.
• A taken name returns status 409 with free alternatives in suggest.
• A subdomain name (sub: true, Max plan) is one DNS label: letters, digits and hyphens, no hyphen at either end, no underscore. Names such as www, mail or ns1 are reserved.

A name can be checked before the link is created:

curl "http://anonym.es/api/v1/names/check?name=my-article"

Fields of the check response:

Several links at once

The urls field accepts up to 50 addresses, as a JSON array or as text with one address per line. Each address becomes its own link with its own token, and the other fields apply to all of them. A custom name is not available in a batch.

curl -X POST http://anonym.es/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com/a","https://example.com/b","https://example.com/c"]}'

The response contains batch: true and a results array with one entry per address, in the order sent. A faulty address produces an entry with ok: false and the error code without stopping the rest.

Additional settings

curl -X POST http://anonym.es/api/v1/links \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "name": "my-article",
    "expires_days": 30,
    "max_hits": 1000,
    "self_destruct": true,
    "password": "secret",
    "note": "Available until the end of the month",
    "delay": 5,
    "tags": "blog,promo",
    "qr": true,
    "qr_size": 300,
    "qr_format": "png"
  }'

Options marked as paid are ignored for guests and on the Free plan. The response reflects the settings the link actually received.

Listing links

GET /api/v1/links

Requires an account token. Links are returned newest first.

curl "http://anonym.es/api/v1/links?page=1&per=50" \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Search and the tag filter can be combined:

curl "http://anonym.es/api/v1/links?q=example&tag=promo" \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Fields of the response:

Finding a link by its short address

A link is addressed by its numeric id (the id field, for example 4821), not by the name in the short address. When only the short address is known, the id can be looked up with any token that manages the link:

curl --get http://anonym.es/api/v1/links/lookup \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "short=http://anonym.es/k7m2q"

Link details and statistics

GET /api/v1/links/{id}

Returns the settings of the link, its status, the number of visits and the number of unique visitors for its whole life:

curl http://anonym.es/api/v1/links/4821 \
  -H "Authorization: Bearer YOUR_TOKEN"

With an account token, a visits report can be added with the stats parameter:

curl "http://anonym.es/api/v1/links/4821?stats=day" \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Fields of the response: stats

Editing a link

PATCH /api/v1/links/{id}

Only the fields sent change:

curl -X PATCH http://anonym.es/api/v1/links/4821 \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"max_hits": 2000, "delay": 3, "tags": "blog,updated"}'

Clearing a value

• password, note and tags: an empty string removes the value.
• expires_days and max_hits: null, an empty string or 0 removes the limit. self_destruct turns off when neither a cap nor a lifetime is left.
• delay: null or an empty string restores the plan default. 0 means an instant redirect.
• url cannot be emptied, and a note-only link keeps needing a note.

curl -X PATCH http://anonym.es/api/v1/links/4821 \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password": "", "note": "", "expires_days": null, "max_hits": null, "delay": 0}'

Deleting a link

DELETE /api/v1/links/{id}

curl -X DELETE http://anonym.es/api/v1/links/4821 \
  -H "Authorization: Bearer YOUR_TOKEN"

After deletion the custom name becomes free again. The statistics are deleted together with the link.

Fields of the response:

QR code

For an HTML img tag, request the code by the short address. This endpoint needs no token: the short address itself is the key, and anyone who has it can generate the same code.

<img
  src="http://anonym.es/api/v1/qr?short=http%3A%2F%2Fanonym.es%2Fk7m2q&qr_size=400"
  alt="QR code"
>

Server-side code can also request the image by id with a token, or receive it base64-encoded in JSON by adding qr=true to the create or details call:

curl "http://anonym.es/api/v1/links/4821/qr?qr_size=400&qr_format=svg" \
  -H "Authorization: Bearer YOUR_TOKEN" -o qr.svg

Parameters of both image endpoints:

The qr member in JSON responses:

Account details

GET /api/v1/me

Requires an account token. Returns the plan, its limits and the remaining quota:

curl http://anonym.es/api/v1/me \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Errors

Errors are returned in a single JSON format:

{
  "ok": false,
  "error": "taken",
  "message": "This name is already taken.",
  "field": "name",
  "suggest": ["my-article-26", "my-my-article", "my-article-link"]
}

field contains the name of the faulty parameter, or null when the error does not concern a specific field. A taken name adds suggest, a paid option adds upgrade, quotas and rate limits add the Retry-After header.

Rate limits

Each call costs units, and each plan has a budget of units per minute (see Plans and limits). A read costs 1 unit, a list page 2, a QR code 3, an edit 3, a deletion 2, a creation 5 plus 1 per address. Every response carries these headers:

Plans and limits

The exact limits of each plan. Links are counted per day and IP address on Free, per month and account on paid plans. The last column lists the settings a plan can use.

OpenAPI specification

The complete technical description as an OpenAPI 3.1 document: http://anonym.es/api/v1/openapi.json

It contains schemas and examples of every request and response, the plan limits, the name rules and the error codes. It suits Swagger UI, Postman, Insomnia and client generators.