Public API
The linkable.id API lets your own systems, such as a CRM, a campaign tool or a script, create short links, fetch their QR codes and read their click statistics. It's a JSON REST API over HTTPS.
Availability: the Business, Agency and Enterprise plans. Ask us to turn it on for your account.
The OpenAPI document, to import into Postman, Insomnia or a client generator, is in linkable.id itself: sign in, open Settings → API tokens and click Download OpenAPI document under API reference. The same section shows your API's base URL with a button to copy it.
Quick start
- In Settings → API tokens, create a token with the permissions you need. See API tokens.
- Copy the base URL from API reference on the same page. It is
https://{admin-domain}/api/v1, where the admin domain is the address where you sign in to linkable.id. - Keep the token in an environment variable (so it isn't written into your scripts) and send it as a Bearer token:
export LINKABLE_API_TOKEN="paste-your-token-here"
curl https://your-admin-domain/api/v1/me \
-H "Authorization: Bearer $LINKABLE_API_TOKEN"/me answers with the token's workspace, permissions and expiry, which is a good first check.
A token works in one workspace. Everything it creates or reads belongs to that workspace.
Permissions
| Permission | Lets the token |
|---|---|
links:read | List and read links, and download their QR codes |
links:write | Create and update links |
stats:read | Read link click statistics |
A token can never do more than its owner's role allows. If an administrator removes a permission from your role, your tokens lose it at once.
Links
List links. Newest first, 25 per page (up to 100 with limit). Filter with search (name), tag and domain (hostname).
curl "https://your-admin-domain/api/v1/links?tag=spring&limit=50" \
-H "Authorization: Bearer $LINKABLE_API_TOKEN"Create a link. name, target and domain (one of your domains, by hostname) are required. Optional: description, tags (names; new ones are created) and the UTM parameters utm_id, utm_source, utm_medium, utm_campaign, utm_term, utm_content. The short address is generated, and the link gets your workspace's default QR theme.
curl https://your-admin-domain/api/v1/links \
-H "Authorization: Bearer $LINKABLE_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1234" \
-d '{"name": "Spring flyer", "target": "https://shop.example.com/spring", "domain": "go.example.com", "tags": ["spring"], "utm_source": "flyer"}'Read or update a link. GET /links/{id} and PATCH /links/{id}. A PATCH changes only the fields you send. An empty UTM value removes that parameter, and tags replaces the whole list. The short address never changes. The short link of a branded page, site or Custom Page always leads to its page, so its target can't be changed.
QR code. GET /links/{id}/qr.svg returns the link's QR code as SVG, in its QR theme.
Statistics
One link's clicks over time:
curl "https://your-admin-domain/api/v1/links/42/stats?from=2026-09-01&to=2026-09-30&interval=week" \
-H "Authorization: Bearer $LINKABLE_API_TOKEN"Clicks per link for a period: GET /stats/links, in pages like the link list.
Both accept from and to (dates as YYYY-MM-DD, default the last 30 days) and interval (auto, day, week, month, quarter or year). The window ends today at the latest and starts no earlier than your plan's analytics history allows. A long window asked for by day is grouped by a wider interval instead. Every answer states the from, to and interval it actually used.
Pages
Lists return data and next_cursor. Pass next_cursor as cursor to get the next page; it's null on the last page.
Retrying safely
Add an Idempotency-Key header (any unique string up to 255 characters) to a POST. If a successful request is retried with the same key and body within 24 hours, you get the first answer again, marked Idempotent-Replayed: true, instead of a second link. The same key with a different body is refused with 409, and so is a retry while the first request is still running. A refused request (for example a 422) isn't kept, so you can fix the body and retry with the same key.
Errors
Errors follow RFC 9457 (application/problem+json):
{
"type": "urn:linkable:problem:validation_failed",
"title": "Validation failed",
"status": 422,
"detail": "Some fields are not valid. See errors.",
"errors": { "domain": ["The selected domain is invalid."] }
}| Status | When |
|---|---|
| 401 | The token is missing, expired or revoked, or its owner left the workspace |
| 403 | The token lacks the permission, or your plan doesn't include the API |
| 404 | Nothing with that id exists in the token's workspace |
| 409 | An Idempotency-Key used with another body, or its first request is still running |
| 422 | Invalid fields (see errors) |
| 429 | Too many requests (see below) |
type is stable, so build your error handling on it rather than on the text. detail is in the token owner's language.
Limits
- Rate: 120 requests per minute per token, shown in the
X-RateLimit-LimitandX-RateLimit-Remainingheaders. Over that, you get 429 withRetry-After(seconds). Requests with a missing or invalid token are limited separately, per IP. - Monthly calls: your plan includes a number of API calls per month, shown in Plan & usage. Going over sends your administrators a notice and never stops the API.
Versioning
This is version 1 (/api/v1). Within v1 we only add things: new endpoints, new optional fields, new fields in answers. Make your integration ignore fields it doesn't know. A breaking change would come as /api/v2, announced in What's New at least six months before v1 stops.
With Claude
Claude doesn't use the public API: it works through the Claude connector, which covers far more than links and acts as the person who connected it. Use the API for your own integrations, with a token; use the connector to work with Claude.