Link-API

De API maakt anonieme korte links, geeft hun klikstatistieken terug, wijzigt hun instellingen en verwijdert ze. Verzoeken en antwoorden gebruiken JSON. CORS is ingeschakeld, dus aanroepen werken ook vanuit browsercode.

Basisadres:

http://anonym.es/api/v1

Snel beginnen

Stuur het bestemmingsadres om een korte link te maken:

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

Met een accounttoken zet dezelfde aanroep de link in je dashboard en telt hij mee voor je abonnement:

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"}'

Het antwoord bevat het korte adres, de id van de link en het token dat deze link beheert. Bewaar het token: het is nodig om de link later te lezen of te verwijderen.

{
  "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
}

Velden van het linkobject

Alle endpoints die een link teruggeven gebruiken deze structuur. Tijdstempels zijn ISO 8601 in UTC. De tellers clicks en uniques beslaan de volledige levensduur van de link.

Autorisatie

Geautoriseerde verzoeken dragen het token in de Authorization-header. Als alternatief wordt de header X-API-Key geaccepteerd. Tokens worden nooit in de query string doorgegeven.

Authorization: Bearer YOUR_TOKEN

Een accounttoken begint met anon_. Een linktoken bestaat uit 32 tekens. Het aanmaken van een nieuw accounttoken maakt het vorige ongeldig.

Voorbeeld:

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

Een accounttoken aanmaken in het dashboard

Endpoints

De body van een verzoek kan als application/json of als application/x-www-form-urlencoded worden verzonden. Parameternamen en foutcodes zijn voor alle endpoints gelijk.

De kosten zijn in eenheden van de snelheidslimiet, zie Snelheidslimieten.

Een link maken

POST /api/v1/links

Het minimale verzoek bevat alleen het veld url:

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

Met een accounttoken hoort de link bij het account en telt hij mee voor het abonnement. Zonder token is het een gastlink op de 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"}'

Een geslaagd verzoek geeft status 201 terug met de link, het token en het aantal links dat in de huidige quotaperiode overblijft.

Velden van het antwoord:

Link met een eigen naam

Het korte adres krijgt de naam my-article als die vrij is en aan de regels hieronder voldoet.

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

Naamregels:

• Latijnse letters, cijfers, koppelteken en onderstrepingsteken. Vanaf 5 tekens in het Free-plan en vanaf 3 in betaalde plannen, maximaal 32. Hoofdletters maken geen verschil: Promo en promo zijn dezelfde link.
• Paginanamen, taalcodes en dienstwoorden zijn gereserveerd.
• Merknamen en beledigende woorden worden geweigerd. Namen gaan door een woordenlijst en een automatische controle. Het aantal eigen namen per uur is per plan beperkt.
• Een bezette naam geeft status 409 met vrije alternatieven in suggest.
• Een subdomeinnaam (sub: true, plan Max) is één DNS-label: letters, cijfers en koppeltekens, geen koppelteken aan de randen en geen onderstrepingsteken. Namen als www, mail of ns1 zijn gereserveerd.

Een naam kan worden gecontroleerd voordat de link wordt gemaakt:

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

Velden van het controleantwoord:

Meerdere links tegelijk

Het veld urls accepteert tot 50 adressen, als JSON-array of als tekst met één adres per regel. Elk adres wordt een eigen link met een eigen token, en de overige velden gelden voor alle links. Een eigen naam is in een batch niet beschikbaar.

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"]}'

Het antwoord bevat batch: true en een array results met één item per adres, in de verzonden volgorde. Een fout adres levert een item met ok: false en de foutcode op zonder de rest te stoppen.

Extra instellingen

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"
  }'

Opties die als betaald zijn gemarkeerd worden voor gasten en in het Free-plan genegeerd. Het antwoord geeft de instellingen weer die de link daadwerkelijk heeft gekregen.

Links weergeven

GET /api/v1/links

Vereist een accounttoken. Links worden van nieuw naar oud teruggegeven.

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

Zoeken en het tagfilter kunnen worden gecombineerd:

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

Velden van het antwoord:

Een link vinden via het korte adres

Een link wordt aangesproken met zijn numerieke id (het veld id, bijvoorbeeld 4821), niet met de naam in het korte adres. Als alleen het korte adres bekend is, kan de id worden opgezocht met elk token dat die link beheert:

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

Linkgegevens en statistiek

GET /api/v1/links/{id}

Geeft de instellingen van de link, de status, het aantal bezoeken en het aantal unieke bezoekers over de hele levensduur terug:

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

Met een accounttoken voegt de parameter stats een bezoekrapport toe:

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

Velden van het antwoord: stats

Een link bewerken

PATCH /api/v1/links/{id}

Alleen de verzonden velden veranderen:

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"}'

Een waarde wissen

• password, note en tags: een lege string verwijdert de waarde.
• expires_days en max_hits: null, een lege string of 0 heft de limiet op. self_destruct gaat uit als er geen limiet en geen levensduur meer over is.
• delay: null of een lege string herstelt de standaard van het plan. 0 betekent direct doorsturen.
• url kan niet worden leeggemaakt, en een link met alleen een notitie blijft een notitie nodig hebben.

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}'

Een link verwijderen

DELETE /api/v1/links/{id}

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

Na het verwijderen is de eigen naam weer vrij. De statistiek wordt samen met de link verwijderd.

Velden van het antwoord:

QR-code

Vraag voor een HTML-img-tag de code op via het korte adres. Dit endpoint heeft geen token nodig: het korte adres zelf is de sleutel, en iedereen die het heeft kan dezelfde code maken.

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

Servercode kan de afbeelding ook per id met een token opvragen, of base64-gecodeerd in JSON ontvangen door qr=true aan de aanroep voor maken of details toe te voegen:

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

Parameters van beide afbeeldingsendpoints:

Het veld qr in JSON-antwoorden:

Accountgegevens

GET /api/v1/me

Vereist een accounttoken. Geeft het plan, de limieten en de resterende quota terug:

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

Fouten

Fouten worden in één JSON-formaat teruggegeven:

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

field bevat de naam van de foutieve parameter, of null wanneer de fout geen specifiek veld betreft. Een bezette naam voegt suggest toe, een betaalde optie upgrade, quota en snelheidslimieten de header Retry-After.

Snelheidslimieten

Elke aanroep kost eenheden en elk plan heeft een budget aan eenheden per minuut (zie Plannen en limieten). Een leesactie kost 1 eenheid, een lijstpagina 2, een QR-code 3, een wijziging 3, een verwijdering 2, een aanmaak 5 plus 1 per adres. Elk antwoord draagt deze headers:

Plannen en limieten

De exacte limieten van elk plan. Links tellen per dag en IP-adres in Free en per maand en account in betaalde plannen. De laatste kolom noemt de instellingen die een plan kan gebruiken.

OpenAPI-specificatie

De volledige technische beschrijving als OpenAPI 3.1-document: http://anonym.es/api/v1/openapi.json

Het bevat schema's en voorbeelden van alle verzoeken en antwoorden, de planlimieten, de naamregels en de foutcodes. Het is geschikt voor Swagger UI, Postman, Insomnia en clientgeneratoren.