Use the TinyLink API

Steps

1. Open Library, then the Integrations tab: the TinyLink API card comes first.
2. Click Generate a token: a panel opens on the right. Choose the token's scopes — Read, Write (create, edit, add links, generate QR codes) and Delete — then confirm. Only tick what your tool needs.
3. The token appears at the top of the panel, hidden like a password: the eye shows it, the button next to it copies it. It stays available there, and you can come back for it later with the card's Manage button.
4. Send it in the header of every request: Authorization: Bearer tl_…, to https://api.tinylink.fr/v1.

One token per environment

The token only opens the environment it was generated in: your other spaces stay out of reach. It acts on behalf of the admin who generated it, and stops working if that person is no longer an admin of the environment.

The Manage panel is for admins only: they alone see the token and change it. It is stored encrypted at TinyLink. The scopes change without changing the token: your tools have nothing to update. Regenerate creates a new one and disables the old one right away — do it if you think it has leaked. Revoke deletes it. The panel also shows the date of the last call and the number of calls.

First call

Every response is JSON. GET /v1/me checks the token and returns the environment, the scopes and the plan limits:

curl https://api.tinylink.fr/v1/me \
  -H "Authorization: Bearer tl_your_token"

Pages

A page is referred to by its id or its custom address (slug). On creation, name is required; description, slug, password, tags (ids), qr_code (true or a template) and links (links to add in one go) are optional.

• GET /v1/pages — the list, with ?search=, ?tag=, ?page= and ?per_page= (100 at most)
• POST /v1/pages — create a page
• GET /v1/pages/{id} — a page and its links
• PATCH /v1/pages/{id} — name, description, slug, password (null removes the address or the password)
• DELETE /v1/pages/{id} — delete the page

curl -X POST https://api.tinylink.fr/v1/pages \
  -H "Authorization: Bearer tl_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My page",
    "slug": "my-page",
    "qr_code": true,
    "links": [
      { "title": "My website", "url": "https://example.com" },
      { "title": "Contact", "url": "hello@example.com" }
    ]
  }'

Page links

A link has a title, a url (a web address, an e-mail or a phone number), a description, a format (LIST, BANNER, SQUARE, SOCIAL, or TITLE for a section title), a size (FULL or HALF), visible and position (1 = top). Your plan's link limits apply as in the app.

• GET /v1/pages/{id}/links — the links, in order
• POST /v1/pages/{id}/links — add a link, or several with {"links": [ … ]} (100 at most)
• PATCH /v1/pages/{id}/links/{link} — edit, move (position), hide (visible) or archive (archived)
• DELETE /v1/pages/{id}/links/{link} — delete the link

Short links

On creation, url is required; slug, password, tags and qr_code are optional.

• GET /v1/links — the list (same filters as pages)
• POST /v1/links — shorten an address
• GET /v1/links/{id}, PATCH /v1/links/{id} (url, slug, password), DELETE /v1/links/{id}

curl -X POST https://api.tinylink.fr/v1/links \
  -H "Authorization: Bearer tl_your_token" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/promo", "slug": "promo", "qr_code": "none" }'

Tags

• GET /v1/tags, POST /v1/tags (name, color as #1E90FF)
• GET, PATCH, DELETE /v1/tags/{id}; GET /v1/tags/{id}/elements — the pages and links that carry it
• PUT /v1/pages/{id}/tags/{tag} sets a tag, DELETE removes it — same on /v1/links/{id}/tags/{tag}. Removing a tag edits the element without deleting anything: the Write scope is enough.

QR codes

The QR code encodes the element's short address: it stays valid if you change the destination or the custom address.

• POST /v1/pages/{id}/qr-code or /v1/links/{id}/qr-code — generate, with {"template": "classic"} (TinyLink logo), "none" (no logo) or the id of one of your templates
• GET …/qr-code — the addresses of the PNG (2048 px) and the SVG; ?format=png or ?format=svg returns the file itself
• GET /v1/qr-templates — the templates available in the environment

Stats

GET /v1/pages/{id}/stats (views) and GET /v1/links/{id}/stats (clicks) accept ?days=1, 7, 30 (default), 90 or 0 for all time. The response gives the period total, the change against the previous period, the total since creation, the daily series (monthly for 0), and the breakdown by source, country and device. For a page, the clicks on each of its links come on top.

If your plan changes

The token follows the plan of the environment's owner. If it moves to a plan without the API, the token is suspended: the card says so and every call returns 403 plan_required. It is not deleted and resumes as soon as you are back on a Pro or Business plan. An admin can revoke it at any time, plan or not.

Errors and limits

An error returns an HTTP status and an object {"error": {"code": "…", "message": "…"}}. The most common: 401 missing, invalid or revoked token; 403 missing scope (insufficient_scope), plan limit reached (plan_limit_reached) or plan without the API; 404 element not found in the environment; 409 custom address already taken; 422 invalid field (details.field names it) or address flagged as suspicious; 423 element blocked by moderation; 429 too many requests.

Each token gets 120 requests per minute; the X-RateLimit-Remaining and X-RateLimit-Reset headers tell you where you stand. Content created through the API goes through the same review as content from the app: a link may show as pending_review while it happens.