Saltar para o conteúdo
LinkdashLinkdash
Português
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

API HTTP

REST em https://api.linkdash.dev/v1 com uma chave bearer obtida no painel. As mesmas operações que a CLI e o MCP.

URL base: https://api.linkdash.dev/v1

Autenticação: Authorization: Bearer ldash_... (crie chaves em Painel → Chaves de API). Não invente chaves.

Referência da CLI: CLI. MCP: MCP. Preços / quotas: Preços. Descoberta (sem autenticação): GET https://api.linkdash.dev/v1. Markdown simples: 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), ou "kind": "folder" com um name (ver Pastas). 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). 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" }
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

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:

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:

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. 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).

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:

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.

{ "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 para conhecer o modelo.

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 para saber como funcionam as pastas e os visualizadores.

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 e domínios personalizados para esses endpoints.

Esta página foi útil?