---
title: API HTTP
description: >-
  REST em https://api.linkdash.dev/v1 com uma chave bearer obtida no painel. As
  mesmas operações que a CLI e o MCP.
sidebar:
  label: API HTTP
  order: 4
---
URL base: `https://api.linkdash.dev/v1`

Autenticação: `Authorization: Bearer ldash_...` (crie chaves em [Painel → Chaves de API](https://linkdash.dev/dashboard/keys)). Não invente chaves.

Referência da CLI: [CLI](/pt/cli). MCP: [MCP](/pt/mcp). Preços / quotas: [Preços](/pt/pricing). Descoberta (sem autenticação): `GET https://api.linkdash.dev/v1`. Markdown simples: [api.md](https://linkdash.dev/api.md).

Os ids públicos são slugs (`deck`, `k3m9xq`), não o `_id` do Convex. Os nomes dos campos JSON correspondem ao stdout da CLI (`id`, `url`, `kind`, …).

## Convenções

- JSON com `Content-Type: application/json`, salvo indicação em contrário.
- A criação aceita exatamente um de `url`, `text` ou `storageId` (este após `POST /uploads`), **ou** um array `variants` (ver [Variantes](#variants)), **ou** `"kind": "folder"` com um `name` (ver [Pastas](#folders)). A emissão devolve `{ "uploadUrl", "storageId" }`. O host faz PUT dos bytes para `uploadUrl`. Os ficheiros pequenos podem continuar a usar multipart `file` em `POST /links`.
- Durações: `7d`, `24h`, `30m`, `1w` ou uma data ISO. Campos: `expires` / `expiresAt`, `starts` / `startsAt`.
- Limite de aberturas: inteiro positivo opcional `maxOpenings`. A ligação fica em pausa após esse número de aberturas bem-sucedidas. Aumente `maxOpenings`, ou use `clearMaxOpenings`, para voltar a servi-la. Omita `maxOpenings` para aberturas ilimitadas.
- Se um slug existir em dois dos domínios do proprietário, passe `?domain=` / `domain` no JSON.
- Erros: `{ "error": "..." }` mais um `code` opcional. Os slugs `lida.sh` já ocupados devolvem `409` com `code: "slug_taken"`.
- Acesso: as novas ligações e pastas são `restricted`, a menos que o corpo defina `access` (ver [Acesso e partilha](#access-and-sharing)). O `url` nas respostas é o URL de partilha (`https://linkdash.dev/s/<token>`), exceto se a ligação for pública; nesse caso, é o URL curto.
- As escritas contam para a quota mensal de eventos (incluindo partilhar, deixar de partilhar e repor). List / get / stats / export / lista de partilhas / shared / list/get de webhooks não contam. A ingestão de visitas / transferências / reproduções continua a contar.

## Endpoints

| CLI | HTTP | MCP |
| --- | --- | --- |
| `auth whoami` | `GET /me` | `whoami` |
| `links list` | `GET /links` (`?q=&tag=&kind=&status=&folder=&limit=&cursor=`) | `links_list` |
| `links get <id>` | `GET /links/:id` (`?domain=`) | `links_get` |
| `links create --url/--file/--text/--folder` | `POST /links` | `links_create` |
| `links update <id>` | `PATCH /links/:id` | `links_update` |
| `links move <id>` | `POST /links/:id/move` | `links_move` |
| `links copy <id>` | `POST /links/:id/copy` | `links_copy` |
| `links delete <id>` | `DELETE /links/:id` (`?contents=keep\|delete`) | `links_delete` |
| `links share <id> --email <e>` | `POST /links/:id/shares` | `links_share` |
| `links unshare <id> --email <e>` | `DELETE /links/:id/shares/:email` | `links_unshare` |
| `links shares <id>` | `GET /links/:id/shares` | `links_shares` |
| `links shares` (sem id) | `PATCH /links/:id/shares/:email` | `{ "role": "viewer" \| "editor" }` | `{ "id", "email", "role" }` |
| `POST /links/:id/unlock` | `{ "variant"?, "password"?, "variantPassword"? }` | `{ "_id", "variant", "unlocked": true, "minutes": 30, ...target }` |
| `GET /links/:id/activity` | — | `{ "items": [{ "_id", "_creationTime", "action", "detail"?, "actor" }], "cursor" }` |
| `GET /shares` | `links_shares` (sem `id`) |
| `links shared` | `GET /shared` | `links_shared` |
| `links leave <_id \| share URL>` | `DELETE /shared/:id` | `links_leave` |
| `links role <id> --email <e> --role viewer\|editor` | `PATCH /links/:id/shares/:email` | `links_share_role` |
| `links unlock <_id \| share URL>` | `POST /links/:id/unlock` | `links_unlock` |
| `links activity <id>` | `GET /links/:id/activity` | `links_activity` |
| `links reset-link <id>` | `POST /links/:id/reset-link` | `links_update` (`resetShareLink: true`) |
| `links stats --last 24h` | `GET /links/:id/stats?last=24h` | `links_stats` |
| `links export` | `GET /links/export` | `links_export` |
| `links import` | `POST /links/import` | `links_import` |
| `links variants list <id>` | `GET /links/:id/variants` | `variants_list` |
| `links variants add <id>` | `POST /links/:id/variants` | `variants_add` |
| `links variants update <id> <name>` | `PATCH /links/:id/variants/:name` | `variants_update` |
| `links variants remove <id> <name>` | `DELETE /links/:id/variants/:name` | `variants_remove` |
| (PUT do host após a emissão) | `POST /uploads` | `files_upload_url` |
| | `DELETE /uploads/:storageId` | `files_discard` |
| `webhooks list/create/get/rotate/delete` | `GET/POST /webhooks`, `GET/DELETE /webhooks/:id`, `POST /webhooks/:id/rotate` | `webhooks_*` |
| `domains list/add/connect/verify/remove` | `GET/POST /domains`, `GET /domains/:host/connect`, `POST /domains/:host/verify`, `DELETE /domains/:host` | `domains_*` |

`auth create`, `auth login` e `auth logout` são fluxos de dispositivo no navegador. Não são rotas Unkey.

## `GET /me`

Conta com sessão iniciada. `{ "userId": "...", "email": "...", "name": "..." }`. O email e o nome são omitidos quando desconhecidos.

## Criar uma ligação de URL

```bash
curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","slug":"welcome","access":"public"}'
```

O corpo JSON aceita exatamente um de `url`, `text` ou `storageId`, mais os campos opcionais `access` (`restricted` por omissão \| `link` \| `public`), `slug`, `name`, `tags`, `starts`, `expires`, `maxOpenings`, `password`, `domain`, `previewName`, `previewDescription`, `previewImageStorageId`, `sticky`, `forwardParams`, `utm` (apenas ligações de URL) e `folder` (+ `folderDomain`) para criar dentro de uma pasta. A forma abreviada cria uma variante chamada `main`; `password`, `starts`, `expires` e `maxOpenings` de nível superior constituem a barreira da ligação. Resposta: `{ "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }`.

`GET /links` devolve uma página, `{ "items": [...], "cursor" }`: `?limit=` vai de 1 a 100 (por omissão 50); passe `?cursor=` da página anterior até ser `null`. `q` corresponde a palavras inteiras (a última como prefixo), ordenadas por relevância. Os itens são `{ id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id }` (as linhas de pasta acrescentam `items`); o filtro `kind` acrescenta `folder` e `group`, o filtro `status` acrescenta `mixed`, e `folder=<slug>|root` (+ `folderDomain`) lista uma pasta ou o nível superior. `GET /links/:id` devolve a ligação completa com `access` e `variants`; o conteúdo (`destinationUrl` / `textContent` / `fileName`) encontra-se em cada variante.

## Carregar um ficheiro

Emita um URL de carregamento (`{uploadUrl,storageId}`), faça PUT dos bytes a partir do host e, em seguida, crie a ligação no mesmo fluxo:

```bash
curl https://api.linkdash.dev/v1/uploads \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"fileSize":12345}'

curl -X PUT -H "Content-Type: application/pdf" --data-binary @./deck.pdf "$uploadUrl"

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"storageId":"…","fileName":"deck.pdf","fileType":"application/pdf","fileSize":12345}'
```

Os ficheiros pequenos podem continuar a usar multipart em `POST /links`:

```bash
curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -F "file=@./deck.pdf" \
  -F "expires=7d" \
  -F "slug=deck"
```

Campos multipart opcionais: `access`, `slug`, `name`, `tags`, `starts` / `startsAt`, `password`, `expires`, `maxOpenings`, `domain`, `previewName`, `previewDescription`, `previewImage`.

## Atualização, estatísticas, CSV

`PATCH /links/:id` aceita JSON ou multipart. Substitua os bytes do ficheiro com `storageId` após `POST /uploads` + PUT do host, ou com o campo multipart `file` (apenas ligações com uma única variante). `--status` / `{ "status": "expired" }` é rejeitado — use `expires`. `{ "status": "scheduled" }` é rejeitado — use `starts`. O campo opcional `maxOpenings` coloca a ligação em pausa após esse número de aberturas; `clearMaxOpenings` remove o limite. `sticky` (booleano) e `restartSplit` (booleano) controlam a atribuição de variantes; `forwardParams` (booleano) reencaminha a query string do visitante, ver [Reencaminhar parâmetros de consulta](#forward-query-parameters). `access` altera quem a pode abrir; `resetShareLink: true` emite um novo URL de partilha. Resposta: `{ "id", "url", "access", "status", "variantStatuses" }`.

`GET /links/:id/stats?last=24h` devolve `visits`, `downloads`, `plays`, `visitsInLast`, `countries`, `referrers`, `variants` (totais por variante), `visitors` e `crawlers` (`[{ "crawler", "company", "category", "hits", "lastSeen" }]`: bots e pré-visualizações de ligações que obtiveram a ligação, nunca contados como visitas; ver [Registo de crawlers](https://linkdash.dev/pricing.md)).

`GET /links/export` é um CSV com as colunas `slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access`, uma linha por variante (`folder` é o slug da pasta que a contém; `access` é `restricted`, `link` ou `public`). `POST /links/import` aceita CSV em bruto ou multipart `file`; as linhas são agrupadas por slug + domínio (a primeira linha cria a ligação com a respetiva variante e as linhas seguintes acrescentam variantes; nas ligações existentes, atualiza os campos e depois atualiza ou acrescenta variantes por nome). As linhas com `kind` `folder` (com um `name`) criam pastas, e a coluna `folder` coloca as ligações depois de todas as linhas existirem. Um `access` vazio torna as novas ligações restritas e deixa as ligações existentes como estão.

`DELETE /links/:id` numa pasta aceita `?contents=keep` (por omissão: os itens sobem um nível) ou `?contents=delete` (os itens e as pastas no interior também são eliminados).

## Variantes

Cada ligação é um contentor de uma ou mais **variantes**: conteúdo (`url` | `file` | `text`) mais a sua própria barreira (`password`, `paused`, `starts`, `expires`, `maxOpenings`), um `weight` e condições de visitante `when` opcionais. A ligação detém o slug, o domínio, o nome, as etiquetas, a pré-visualização, a sua própria barreira (que prevalece sobre as barreiras das variantes), `sticky` (por omissão `true`) e `splitVersion` (incrementado por `restartSplit`). Sem `variants`, uma ligação tem uma variante chamada `main`. Nomes: letras minúsculas, dígitos, hífenes internos, 1–40 caracteres, únicos por ligação. Máximo de 20 variantes por ligação.

Um visitante recebe uma variante: as variantes cujo `when` corresponde formam o conjunto (se nenhuma corresponder, usam-se as variantes incondicionais), seguindo-se uma escolha ponderada (hash fixo de visitante + ligação + `splitVersion`; caso contrário, aleatória). Os crawlers recebem a primeira variante incondicional ativa. O `kind` da ligação é `group` quando há várias variantes. O `status` da ligação é o da barreira da ligação, quando definida; caso contrário, o estado comum a todas as variantes; caso contrário, `mixed`. `variantStatuses` contabiliza `{ active, paused, expired, scheduled }`.

Criar várias variantes de uma só vez:

```bash
curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"slug":"promo","variants":[{"name":"a","url":"https://example.com/a"},{"name":"b","url":"https://example.com/b","weight":3,"when":{"countries":["DE","AT"]}}]}'
```

Cada variante: `name` (obrigatório), um de `url` | `text` | `storageId` (+ `fileName`, `fileType`, `fileSize`), `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when`. A criação multipart mantém-se apenas na forma abreviada.

| Rota | Corpo | Resposta |
| --- | --- | --- |
| `GET /links/:id/variants` | — | array de variantes |
| `POST /links/:id/variants` | JSON ou multipart `file`: `name` (obrigatório), conteúdo, `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when` | a variante |
| `PATCH /links/:id/variants/:name` | `name` (mudar o nome), `url`, `text`, `storageId` / `file`, `password`, `clearPassword`, `starts`, `clearStarts`, `expires`, `clearExpires`, `maxOpenings`, `clearMaxOpenings`, `status` (`active` \| `paused`), `weight`, `when`, `clearWhen`, `utm` | a variante |
| `DELETE /links/:id/variants/:name` | — | `{ "id", "variant", "deleted": true }` (a última variante não pode ser eliminada) |

Chaves de `when` (arrays de strings; todas as chaves definidas têm de corresponder): `countries` (ISO-2), `devices` (`mobile` | `tablet` | `desktop`), `os` (`windows` | `macos` | `android` | `ios` | `linux` | `other`), `browsers` (`edge` | `chrome` | `firefox` | `safari` | `other`), `languages` (prefixo), `referrerHosts` (sufixo do host).

### Regras de parâmetros de consulta

`when.params` é um array de até 10 regras sobre a query string do visitante (`lida.sh/promo?src=newsletter`); todas as regras têm de se verificar. Cada regra é `{ "key", "op", "value" }`, em que `op` é um de `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in` (`value` é uma lista separada por `|` ou por vírgulas) | `exists` | `missing`. `value` é obrigatório, exceto para `exists` / `missing`. As chaves distinguem maiúsculas de minúsculas e os valores são comparados de forma exata.

```json
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
```

Os valores dos parâmetros são avaliados no momento da abertura e nunca são guardados nas análises.

### Reencaminhar parâmetros de consulta

`forwardParams` (booleano na ligação, por omissão `false`; definível em `POST /links` e `PATCH /links/:id`, devolvido por `GET /links/:id`) acrescenta toda a query string do visitante às variantes de URL. Os valores do visitante sobrepõem-se aos guardados, incluindo `utm`. As variantes de ficheiro e de texto ignoram-no. Isto é encaminhamento, não controlo de acesso: qualquer pessoa pode acrescentar parâmetros. Os valores dos parâmetros não são guardados nas análises.

## Pastas

Uma pasta é uma ligação que lista os itens nela colocados. Consulte [Pastas](/pt/folders) para conhecer o modelo.

```bash
curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"kind":"folder","name":"Q4 launch","slug":"q4"}'

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/deck","folder":"q4"}'

curl https://api.linkdash.dev/v1/links/k3m9xq/move \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"folder":"q4"}'

curl "https://api.linkdash.dev/v1/links?folder=q4" -H "Authorization: Bearer ldash_..."
```

| Rota | Corpo | Resposta |
| --- | --- | --- |
| `POST /links` | `{ "kind": "folder", "name" }` mais os campos habituais de ligação; sem `url`, `text`, `storageId` nem `variants` | a pasta criada |
| `POST /links/:id/move` | `{ "folder": "<slug>" }` ou `{ "folder": null }` para o nível superior, `folderDomain` opcional | `{ "id", "folder" }` |
| `POST /links/:id/copy` | — | `{ "id", "url", "access", "kind", "variants", "folder", … }` (mesmo acesso, novo URL de partilha, sem pessoas) |

Mover e copiar contam, cada um, como um evento. Um slug de pasta desconhecido devolve `404` (`Folder "<slug>" not found`); um slug que não seja uma pasta, ou mover uma pasta para dentro de si própria ou de uma pasta abaixo dela, devolve `400`. As pastas podem ser aninhadas até um máximo de 32 níveis.

## Acesso e partilha

Cada ligação e cada pasta tem `access`: `restricted` (por omissão; o proprietário e as pessoas com quem é partilhada, com sessão iniciada, em `https://linkdash.dev/s/<token>`), `link` (qualquer pessoa com esse URL) ou `public` (qualquer pessoa, no URL curto). Defina-o em `POST /links` ou `PATCH /links/:id`. Passe `"access": "public"` para ligações destinadas a ser publicadas abertamente. Consulte [Partilha e acesso](/pt/sharing) para saber como funcionam as pastas e os visualizadores.

```bash
curl https://api.linkdash.dev/v1/links/q4/shares \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"emails":["anna@example.com","ben@example.com"]}'

curl https://api.linkdash.dev/v1/links/q4/shares -H "Authorization: Bearer ldash_..."

curl -X DELETE https://api.linkdash.dev/v1/links/q4/shares/ben%40example.com -H "Authorization: Bearer ldash_..."

curl -X POST https://api.linkdash.dev/v1/links/q4/reset-link -H "Authorization: Bearer ldash_..."

curl https://api.linkdash.dev/v1/shares -H "Authorization: Bearer ldash_..."

curl -X DELETE https://api.linkdash.dev/v1/shared/<_id> -H "Authorization: Bearer ldash_..."
```

| Rota | Corpo | Resposta |
| --- | --- | --- |
| `POST /links/:id/shares` | `{ "emails": [...] }` (1–50 emails) | `{ "id", "url", "access", "invited", "alreadyShared" }` |
| `DELETE /links/:id/shares/:email` | — | `{ "id", "email", "removed": true }` |
| `GET /links/:id/shares` | — | `[{ "email", "role": "viewer", "accepted", "invitedAt", "viaFolder"?: { "id", "name"?, "slug" } }]` |
| `GET /shares` | — | `{ "items": [{ "id", "name"?, "kind", "access", "url", "people": [{ "email", "accepted", "invitedAt" }] }], "cursor" }` (tudo o que foi partilhado) |
| `GET /shared` | — | `{ "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }` |
| `DELETE /shared/:id` | — | `{ "_id", "left": true }` (`:id` é o `_id` ou o token de partilha de `GET /shared`) |
| `POST /links/:id/reset-link` | — | `{ "id", "access", "url" }` |

`POST /links/:id/shares` aceita `"role": "editor"` para editores. Os editores alteram itens e veem estatísticas e atividade, mas nunca mexem em palavras-passe, slug, domínio, acesso ou partilha, nem eliminam, movem ou copiam (`403`); usam o `_id` do item ou o token de partilha como `:id`, e uma variante protegida por palavra-passe mantém-se `locked: true` até `POST /links/:id/unlock` (30 minutos; dez palavras-passe erradas por hora e, depois, `429`). Guardar depois de outra pessoa ter guardado devolve `409` apenas quando o pedido envia `expectedVersion`. Todas as rotas de partilha aceitam `?domain=` quando o slug se repete. `accepted` é `false` até esse email ter uma conta verificada; `viaFolder` significa que o acesso provém de uma pasta acima. Até 200 pessoas por item e 100 emails de convite por conta por dia. `GET /shares` e `GET /shared` devolvem uma página de cada vez: `?limit=` vai de 1 a 100 (por omissão 50); passe `?cursor=` da página anterior até `cursor` ser `null`. Partilhar, deixar de partilhar e repor contam, cada um, como um evento; sair não conta. O acesso através de uma pasta partilhada acima mantém-se depois de sair.

## Erros

| Estado | Quando |
| --- | --- |
| 400 | Validação, corpo em falta, tipos de criação misturados |
| 401 | Chave bearer em falta ou inválida |
| 404 | Slug, domínio ou pasta desconhecidos |
| 409 | Slug já ocupado (`code: "slug_taken"`) |
| 429 | Quota mensal de eventos atingida |
| 503 | Chaves de API não configuradas nesta implementação |

Consulte [webhooks](/pt/webhooks) e [domínios personalizados](/pt/domains) para esses endpoints.
