> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linkutm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Base URL, authentication, workspace resolution and request conventions for the linkutm API.

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

## Base URL

```
https://api.linkutm.com/api/v1
```

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.

> [card] API key
>
> `lk_live_…` — for server-to-server integrations. Created under **Settings → Developer → API keys**.

> [card] JWT
>
> Dashboard session token from `POST /auth/login`. Used by the linkutm app itself.

```bash theme={null}
curl https://api.linkutm.com/api/v1/links \
  -H "Authorization: Bearer lk_live_abc123..."
```

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.

| Auth method | `x-workspace-id` | If it is wrong |
| - | - | - |
| API key (`lk_live_…`) | Optional — filled in from the key | `401` when it names a different workspace than the key |
| JWT | **Required** | `400` when missing or blank; `403` when you hold no active seat there |

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.

> [!WARNING]
>
> 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.

```json theme={null}
{
  "links": [],
  "pagination": { "page": 1, "limit": 20, "total": 137, "pages": 7 }
}
```

> [!NOTE]
>
> `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](https://docs.linkutm.com/api/roles.md) for the role half.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.