Base URL
Authentication
Every request carries anAuthorization: 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.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.
Request conventions
Content type. Endpoints takeapplication/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 usepage 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 as403 with a message naming the reason. See
Roles and permissions for the role half.