API v2 + SDK TypeScript

API e SDK da Revolink
Gerencie seus links pelo código

Crie links com regras de roteamento, gerencie tags e domínios próprios e leia as análises de cliques por uma API REST com especificação OpenAPI 3.1 ou pelo SDK TypeScript tipado e sem dependências.

Obtenha sua chave de API Referência da API GitHub

Crie uma chave em Perfil → API

Última atualização: novembro de 2026

terminal

npm install revolink

Funciona no Node.js 18+ e em qualquer ambiente com fetch global. Sem dependências e com tipos TypeScript completos gerados a partir da especificação da API.

Início rápido

Do zero ao seu primeiro link curto em três passos.

Crie uma chave de API

Na Revolink, abra Perfil → API e crie uma chave. Escolha apenas as permissões de que ela precisa.

Copie o id do seu workspace

O id do workspace é enviado em cada requisição, então a chave sempre age em um único workspace.

Crie um link

Inicialize o cliente com a chave e o id do workspace e chame links.create.

Mantenha a chave no seu servidor. Quem a tiver pode agir no seu workspace dentro das permissões da chave.

Integre seu projeto sem esforço

Com o SDK da Revolink você cria links curtos com regras de roteamento em poucas linhas de código.

Obtenha sua chave de API Referência da API

index.ts

import {Revolink} from 'revolink';

const revolink = new Revolink({
  apiKey: process.env.REVOLINK_API_KEY!,
  workspaceId: process.env.REVOLINK_WORKSPACE_ID!,
});

const {shortLink} = await revolink.links.create({
  url: 'https://example.com',
});
console.log(shortLink); // https://rvlnk.link/k3x9a

Explore os endpoints da API

Requisição

TypeScript

await revolink.links.create({
  url: 'https://example.com',
});

Resposta

JSON

{
  id: "65f1c0a2e4b0a1d2c3b4a5f6",
  name: "example.com",
  domain: "rvlnk.link",
  slug: "k3x9a",
  shortLink: "https://rvlnk.link/k3x9a",
  url: "https://example.com",
  active: true,
  clicks: 0,
  ...
}

O que o SDK cobre

Quatro recursos e uma chamada me. Cada método corresponde a um endpoint REST.

Recurso	Métodos	O que faz
revolink.links	`createupsertgetlistiterateupdatedeletecreateManyupdateManydeleteMany`	Criar, ler, atualizar e excluir links, upsert por slug, listar com filtros e paginação, percorrer todas as páginas e operar em lote (até 100 por chamada).
revolink.tags	`listgetcreateupdatedelete`	Criar, listar, renomear e excluir tags.
revolink.domains	`listgetcreatedelete`	Adicionar um domínio próprio, verificar o status de verificação e removê-lo.
revolink.analytics	`linkworkspace`	Análises de cliques de um link ou de todo o workspace em um intervalo de datas.
revolink.me()		Quem age com a chave, o workspace e as permissões da chave.

Roteamento inteligente pelo código

Envie visitantes diferentes para destinos diferentes. Exatamente uma regra é a padrão; as outras valem por país, dispositivo, sistema operacional e outras condições.

routing.ts

await revolink.links.create({
  name: 'App download',
  rules: [
    {isDefault: true, targetUrl: 'https://example.com/download'},
    {
      isDefault: false,
      targetUrl: 'https://apps.apple.com/app/id1',
      device: ['mobile'],
      os: ['iOS'],
    },
  ],
});

Chaves de API e permissões

Cada chave carrega scopes. Um endpoint responde 403 quando falta o scope de que precisa, então dê a cada integração apenas o que ela usa.

Cabeçalhos de autenticação

Authorization: Bearer <key>

Envie a chave como token bearer.

X-Api-Key

Ou envie a chave neste cabeçalho.

X-Workspace-Id

Obrigatório. O workspace em que a requisição age. O dono da chave deve ser membro dele.

Scopes

Scope	Permite
`links:read`	Listar e ler links
`links:write`	Criar, fazer upsert e atualizar links
`links:delete`	Excluir links
`links:bulk`	Criar, atualizar e excluir em lote (até 100 links por requisição)
`analytics:read`	Ler análises de cliques
`tags:read`	Listar e ler tags
`tags:write`	Criar e atualizar tags
`tags:delete`	Excluir tags
`domains:read`	Listar e ler domínios próprios
`domains:write`	Adicionar domínios próprios
`domains:delete`	Excluir domínios próprios

As chamadas à API contam na cota mensal de API do plano do dono do workspace. Quando um limite do plano interrompe uma requisição, o código do erro é license_limit_reached.

Erros e novas tentativas

Toda requisição que falha lança um RevolinkError com o status HTTP, um código legível por máquina e uma mensagem que diz o que corrigir.

errors.ts

import {RevolinkError} from 'revolink';

try {
  await revolink.links.create({url: 'https://example.com', slug: 'taken'});
} catch (error) {
  if (error instanceof RevolinkError) {
    error.status;              // 409
    error.code;                // 'conflict'
    error.licenseLimitReached; // true when the plan's limit stopped the request
    error.requiredPermission;  // e.g. 'tags:write' when the key lacks a scope
    error.retryAfter;          // seconds, on 429
  }
}

Novas tentativas que nunca duplicam um link

Um 429 é sempre repetido após o atraso de Retry-After. Erros de rede e respostas 5xx são repetidos apenas para GET, PUT e DELETE. Um POST ou PATCH que pode já ter sido processado nunca é repetido, então um link não é criado duas vezes. Padrões: 30 segundos de tempo limite por tentativa e 2 novas tentativas; maxRetries em 0 desativa as novas tentativas.

Código	Significado
`invalid_request`	A requisição está errada (400). A mensagem diz o quê.
`unauthorized`	Sem chave, ou chave inválida ou expirada (401).
`forbidden`	A chave não tem uma permissão, ou seu papel não pode fazer isso (403).
`license_limit_reached`	O limite do plano foi atingido: links, tags, domínios ou chamadas à API (403).
`not_found`	Esse item não existe neste workspace (404).
`conflict`	Já existe, por exemplo um slug ou nome de tag em uso (409).
`rate_limited`	Mais de 300 requisições por minuto para a chave (429).
`network_error`	Sem resposta: falha de rede ou tempo esgotado (o status é 0).

Documentação, especificação e código

Referência interativa da API

Teste cada endpoint da API v2 no navegador.

Especificação OpenAPI 3.1

Gere seu próprio cliente em qualquer linguagem.

SDK no GitHub

Código, README e issues do SDK TypeScript.

revolink no npm

Instale o pacote e confira a versão mais recente.

Perguntas frequentes

Preciso usar o SDK?

Não. O SDK é uma camada fina e tipada sobre a API REST. Você pode chamar https://api.revolink.link/apiv2 diretamente de qualquer linguagem com uma chave de API e o cabeçalho X-Workspace-Id, ou gerar um cliente a partir da especificação OpenAPI 3.1.

Quais ambientes o SDK suporta?

Node.js 18 ou mais recente e qualquer ambiente com fetch global. Não tem dependências e inclui builds ESM e CommonJS com tipos TypeScript gerados a partir da especificação da API.

Quais são os limites de requisições?

As requisições são limitadas a 300 por minuto por chave de API. Acima disso a API responde 429 com um cabeçalho Retry-After, e o SDK espera e tenta de novo sozinho. Separadamente, as chamadas à API contam na cota mensal do plano do dono do workspace.

O que acontece com a API v1?

A API v1 está congelada e suas respostas trazem cabeçalhos Deprecation. Novas integrações devem usar a API v2.

O SDK pode criar links duplicados em uma nova tentativa?

Não. Um POST ou PATCH que pode ter sido processado nunca é repetido. Apenas respostas 429 e requisições idempotentes (GET, PUT, DELETE) são repetidas.

Posso usar a Revolink a partir de um agente de IA?

Sim. O servidor MCP da Revolink permite que Claude, Cursor e outros clientes MCP gerenciem links em linguagem natural. O SDK é a escolha para o seu próprio código e scripts.

Continue explorando

Revolink MCP

Gerencie links pelo Claude, Cursor ou qualquer cliente MCP.

Integração com o Zapier

Automatize a criação de links sem escrever código.

Rastreamento de cliques

Que dados de análise você pode obter pela API.

Pronto para começar com o Revolink?

Junte-se a equipes e criadores que controlam cada clique com roteamento inteligente. Lance campanhas mais inteligentes, otimize o tráfego em tempo real e cresça sem limites.

Comece gratuitamente

Plano grátis · Sem cartão de crédito · Cancele a qualquer momento

Já tem links? Importe-os

API e SDK da Revolink Gerencie seus links pelo código

Instalação em uma linha