arvore.link

API do arvore.link

para automatizar o que faria na mão: criar e editar links curtos, montar árvores e ler seus próprios cliques. de graça, sem depender de plano pago para ter acesso.

índice e busca

links
árvores
métricas
conta

comece aqui

  1. 1. crie sua conta — é só um código no e-mail, sem senha.
  2. 2. vá em painel → API e crie um token. ele aparece uma única vez: guardamos só um hash, então nem nós conseguimos mostrá-lo de novo.
  3. 3. mande o token no cabeçalho de cada requisição.
curl -X POST https://api.arvore.link/links \
  -H "Authorization: Bearer arv_seu_token" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://exemplo.com/uma-pagina"}'

# {"id":"a1b2c3d4","slug":"x7k2","short_url":"https://arvr.ink/x7k2", ...}

autenticação

um token começa com arv_ e não expira. ele faz o que você faz com links, árvores e métricas — mas não administra a conta: trocar e-mail, apagar a conta, encerrar sessões e criar outros tokens respondem 403 e exigem login de verdade.

isso não é uma limitação por acaso: é o que faz a revogação valer. um token vazado não consegue criar um segundo token para sobreviver à revogação do primeiro.

limites

no plano gratuito: um token ativo por conta e 100 requisições por hora por token. passando disso, a resposta é 429 com {"error":"RATE_LIMITED"} e um cabeçalho Retry-After em segundos.

revogar um token libera a vaga, então trocar de token é revogar e criar — o registro do antigo continua na lista, com a data em que parou de valer.

erros

todo erro vem como {"error":"CODIGO"} com um status HTTP coerente. error é sempre texto, nunca um objeto — dá para checar e ramificar sem inspecionar a estrutura. os mais comuns: UNAUTHORIZED (401), SESSION_REQUIRED (403), SLUG_ALREADY_IN_USE (409), RATE_LIMITED (429).

um 400 de validação traz também fields, com o que está errado em cada entrada — útil para apontar o campo num formulário: {"error":"VALIDATION_FAILED","fields":{"url":["Invalid URL"]}}. quando o schema tem um código próprio, ele vem no lugar de VALIDATION_FAILED — por exemplo INVALID_TAG.

especificação

a referência abaixo é gerada a partir da especificação, então esta página não consegue divergir dela. aponte seu gerador de cliente para /openapi.json — ou /openapi.yaml se preferir ler.

o que não está aqui

a API cobre o que dá para automatizar. de fora ficam o login (é código por e-mail, não dá para roteirizar), a administração da conta — trocar e-mail, encerrar sessões, apagar a conta, criar tokens —, o envio de fotos e os contadores internos do site.

a maior parte disso não é escolha de documentação: com um token, esses endpoints respondem 403 de propósito. é o que faz a revogação de um token valer alguma coisa.

referência

base: https://api.arvore.link · versão 1.0.0

árvores

GET/linktreestoken

listar suas árvores

200 Linktrees401 Unauthorized

resposta 200 · Linktree

{
  "linktrees": [
    {
      "id": "k9fx2n1a",
      "slug": "meu-perfil",
      "title": "minha página",
      "bio": "links que importam",
      "avatar_url": "https://example.com/foto.jpg",
      "published": false,
      "created_at": 1739111400000,
      "updated_at": 1739111400000
    }
  ]
}
id
— string
slug
— string. Path on the redirect domain, 1-50 chars of [0-9a-z-]
title
— string
bio
— string, pode ser null
avatar_url
— string, pode ser null
published
— boolean. Unpublished árvores 404 on the public page
created_at
— integer
updated_at
— integer
POST/linktreestoken

criar uma árvore

slug
— string, obrigatório. ex: meu-perfil
title
— string, obrigatório
bio
— string, opcional
avatar_url
— string, opcional

201 Linktree created400 Validation error409 SLUG_ALREADY_IN_USE

resposta 201 · Linktree

{
  "id": "k9fx2n1a",
  "slug": "meu-perfil",
  "title": "minha página",
  "bio": "links que importam",
  "avatar_url": "https://example.com/foto.jpg",
  "published": false,
  "created_at": 1739111400000,
  "updated_at": 1739111400000
}
id
— string
slug
— string. Path on the redirect domain, 1-50 chars of [0-9a-z-]
title
— string
bio
— string, pode ser null
avatar_url
— string, pode ser null
published
— boolean. Unpublished árvores 404 on the public page
created_at
— integer
updated_at
— integer
GET/linktrees/{id}token

ver uma árvore com seus itens

id
— path, obrigatório

200 Linktree with items401 Unauthorized404 Not found

resposta 200 · Linktree

{
  "id": "k9fx2n1a",
  "slug": "meu-perfil",
  "title": "minha página",
  "bio": "links que importam",
  "avatar_url": "https://example.com/foto.jpg",
  "published": false,
  "created_at": 1739111400000,
  "updated_at": 1739111400000,
  "items": [
    {
      "id": "p3qr7s2t",
      "title": "instagram",
      "url": "https://instagram.com/perfil",
      "short_url": "https://arvr.ink/x7y8",
      "position": 0,
      "active": true,
      "created_at": 1739111400000,
      "updated_at": 1739111400000
    }
  ]
}
id
— string
slug
— string. Path on the redirect domain, 1-50 chars of [0-9a-z-]
title
— string
bio
— string, pode ser null
avatar_url
— string, pode ser null
published
— boolean. Unpublished árvores 404 on the public page
created_at
— integer
updated_at
— integer
items
— LinktreeItem[]
PATCH/linktrees/{id}token

editar o perfil, o slug ou publicar uma árvore

id
— path, obrigatório
slug
— string, opcional
title
— string, opcional
bio
— string, opcional
avatar_url
— string, opcional
published
— boolean, opcional

200 Linktree updated400 Validation error401 Unauthorized404 Not found409 SLUG_ALREADY_IN_USE

resposta 200 · Linktree

{
  "id": "k9fx2n1a",
  "slug": "meu-perfil",
  "title": "minha página",
  "bio": "links que importam",
  "avatar_url": "https://example.com/foto.jpg",
  "published": false,
  "created_at": 1739111400000,
  "updated_at": 1739111400000
}
id
— string
slug
— string. Path on the redirect domain, 1-50 chars of [0-9a-z-]
title
— string
bio
— string, pode ser null
avatar_url
— string, pode ser null
published
— boolean. Unpublished árvores 404 on the public page
created_at
— integer
updated_at
— integer
DELETE/linktrees/{id}token

apagar uma árvore

id
— path, obrigatório

204 Deleted401 Unauthorized404 Not found

resposta 204 sem corpo.

GET/linktrees/{id}/analyticstoken

ver as visitas e os cliques de uma árvore

id
— path, obrigatório
from
— query. Start of time range (Unix timestamp in milliseconds, inclusive)
to
— query. End of time range (Unix timestamp in milliseconds, inclusive)

200 Analytics data401 Unauthorized404 Not found

resposta 200 · LinktreeAnalytics

{
  "id": "k9fx2n1a",
  "slug": "meu-perfil",
  "title": "minha página",
  "published": true,
  "views": 128,
  "clicks": 41,
  "items": [
    {
      "id": "p3qr7s2t",
      "title": "instagram",
      "short_url": "https://arvr.ink/x7y8",
      "active": true,
      "count": 22
    }
  ]
}
id
— string
slug
— string
title
— string
published
— boolean
views
— integer. Visits to the public page in the range
clicks
— integer. Sum of item clicks in the range
items
— object[]
POST/linktrees/{id}/itemstoken

adicionar um item na árvore

id
— path, obrigatório
title
— string, obrigatório. ex: instagram
url
— string, obrigatório. ex: https://instagram.com/perfil
position
— integer, opcional

201 Item created400 Validation error401 Unauthorized404 Linktree not found

resposta 201 · LinktreeItem

{
  "id": "p3qr7s2t",
  "title": "instagram",
  "url": "https://instagram.com/perfil",
  "short_url": "https://arvr.ink/x7y8",
  "position": 0,
  "active": true,
  "created_at": 1739111400000,
  "updated_at": 1739111400000
}
id
— string
title
— string
url
— string. Final destination
short_url
— string. Short link the public page points at, so clicks are counted
position
— integer. Ascending order on the public page
active
— boolean. Inactive items are hidden from the public page
created_at
— integer
updated_at
— integer
PATCH/linktrees/{id}/items/{itemId}token

editar um item da árvore

id
— path, obrigatório
itemId
— path, obrigatório
title
— string, opcional
url
— string, opcional
position
— integer, opcional
active
— boolean, opcional

200 Item updated400 Validation error401 Unauthorized404 Linktree or item not found

resposta 200 · LinktreeItem

{
  "id": "p3qr7s2t",
  "title": "instagram",
  "url": "https://instagram.com/perfil",
  "short_url": "https://arvr.ink/x7y8",
  "position": 0,
  "active": true,
  "created_at": 1739111400000,
  "updated_at": 1739111400000
}
id
— string
title
— string
url
— string. Final destination
short_url
— string. Short link the public page points at, so clicks are counted
position
— integer. Ascending order on the public page
active
— boolean. Inactive items are hidden from the public page
created_at
— integer
updated_at
— integer
DELETE/linktrees/{id}/items/{itemId}token

apagar um item da árvore

id
— path, obrigatório
itemId
— path, obrigatório

204 Deleted401 Unauthorized404 Linktree or item not found

resposta 204 sem corpo.

métricas

GET/analyticstoken

ver os cliques de todos os seus links

link_id
— query
from
— query. Start of time range (Unix timestamp in milliseconds, inclusive)
to
— query. End of time range (Unix timestamp in milliseconds, inclusive)

200 Analytics data401 Unauthorized404 Link not found

resposta 200 · ClickEvent

{
  "count": 128,
  "clicks": [
    {
      "ts": "1771849585571#k9fx2n1a",
      "timestamp": 1771849585571,
      "country": "BR",
      "region": "SP",
      "region_name": "São Paulo",
      "timezone": "America/Sao_Paulo",
      "lat": -23.673,
      "lng": -46.5302,
      "device": "desktop",
      "platform": "macOS",
      "browser": "Chrome 145",
      "referer": "https://twitter.com",
      "link_id": "a1b2c3d4"
    }
  ]
}
ts
— string. Sort key in the format "{timestamp_ms}#{random}"
timestamp
— integer. Unix timestamp in milliseconds
country
— string, pode ser null
region
— string, pode ser null
region_name
— string, pode ser null
timezone
— string, pode ser null
lat
— number, pode ser null
lng
— number, pode ser null
device
— string
platform
— string, pode ser null
browser
— string, pode ser null
referer
— string, pode ser null
link_id
— string

conta

GET/accounttoken

descobrir de quem é o token e qual workspace ele acessa

200 Account401 Unauthorized

resposta 200 · Account

{
  "user": {
    "id": "a1b2c3d4",
    "email": "voce@exemplo.com",
    "name": "Rafael",
    "avatar_url": "https://assets.arvore.link/avatars/w1/user-a1b2c3d4-k9fx2n1a.webp",
    "created_at": 1739111400000
  },
  "workspace": {
    "id": "w1x2y3z4",
    "name": "Pessoal"
  }
}
user
— object
workspace
— object