Skip to main content
The linkutm REST API lets you create and manage short links, custom domains, folders, tags and click analytics programmatically.

Base URL

Every path in this reference is relative to that base.

Authentication

Every request carries an Authorization: Bearer <token> header. Two kinds of token are accepted.

API key

lk_live_… — for server-to-server integrations. Created under Settings → Developer → API keys.

JWT

Dashboard session token from POST /auth/login. Used by the linkutm app itself.
An API key stops working the moment its owner’s workspace membership is removed, their account is deactivated, or the key passes its expiry date. Revoking the seat revokes the key.

The workspace header

x-workspace-id names the workspace a request operates in. It accepts either the workspace UUID or its slug. Because the header is resolved from the key, an API-key integration never has to know its own workspace ID. That is why the endpoint pages do not list it — with an API key you never send it.
A JWT request with no x-workspace-id is rejected with 400. No endpoint falls back to “all workspaces”: every query, update and delete is filtered by workspace before it runs.

Request conventions

Content type. Endpoints take application/json. POST /links and PATCH /links/{id} additionally accept multipart/form-data, where the JSON body is sent as a string in a payload part alongside an optional ogImageFile upload. Strict bodies. Request bodies are validated with whitelist and forbidNonWhitelisted, so an unrecognised field is a 400 rather than being silently dropped. Check your spelling against the field list on each page. Identifiers. All resource IDs are UUID v4 strings. Some routes (/domains/{id}, POST /folders/set-default) validate the format and answer 400 for a non-UUID; others simply find nothing and answer 404. Timestamps. Every timestamp in and out is ISO 8601 in UTC.

Pagination

List endpoints use page and limit query parameters and return a pagination object.
GET /domains is the exception: its pagination object names the field totalPages rather than pages. GET /tags and GET /folders are not paginated at all.
GET /links is the only paginated endpoint in this reference that uses pages.

Plan limits

Most write endpoints are gated twice — by the caller’s role, and by the workspace’s plan. Both failures come back as 403 with a message naming the reason. See Roles and permissions for the role half.