API v2 + TypeScript SDK

Revolink API 与 SDK
用代码管理你的链接

通过带 OpenAPI 3.1 规范的 REST API，或带类型且零依赖的 TypeScript SDK，创建带路由规则的链接、管理标签和自定义域名，并读取点击分析。

在个人资料 → API 中创建密钥

最后更新：2026 年 11 月

终端

npm install revolink

支持 Node.js 18+ 以及任何带全局 fetch 的运行时。零依赖，附带由 API 规范生成的完整 TypeScript 类型。

快速开始

三步从零到第一条短链接。

创建 API 密钥

在 Revolink 中打开个人资料 → API 并创建密钥。只选择该密钥需要的权限。

复制工作区 ID

工作区 ID 会随每个请求发送，因此密钥始终只在一个工作区内操作。

创建链接

用密钥和工作区 ID 初始化客户端，然后调用 links.create。

请把密钥保存在你的服务器上。拥有密钥的人可以在其权限范围内操作你的工作区。

无缝集成到你的项目

借助 Revolink SDK，只需几行代码即可创建带路由规则的短链接。

获取 API 密钥 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

探索 API 端点

请求

TypeScript

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

响应

JSON

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

SDK 覆盖的内容

四类资源加一个 me 调用。每个方法对应一个 REST 端点。

资源	方法	功能
revolink.links	`createupsertgetlistiterateupdatedeletecreateManyupdateManydeleteMany`	创建、读取、更新和删除链接，按 slug upsert，带筛选和分页的列表，遍历所有页面，以及批量操作（每次最多 100 条）。
revolink.tags	`listgetcreateupdatedelete`	创建、列出、重命名和删除标签。
revolink.domains	`listgetcreatedelete`	添加自定义域名、查看验证状态并删除。
revolink.analytics	`linkworkspace`	按日期范围读取单个链接或整个工作区的点击分析。
revolink.me()		密钥以谁的身份操作、所在工作区以及密钥的权限。

用代码实现智能路由

把不同的访客送往不同的目的地。有且仅有一条默认规则，其余规则按国家、设备、操作系统等条件匹配。

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'],
    },
  ],
});

API 密钥与权限

每个密钥都带有 scope。缺少所需 scope 时端点返回 403，因此请只授予每个集成实际用到的权限。

认证请求头

Authorization: Bearer <key>

把密钥作为 bearer 令牌发送。

X-Api-Key

或者通过此请求头发送密钥。

X-Workspace-Id

必填。请求所操作的工作区。密钥所有者必须是该工作区成员。

Scope

Scope	允许
`links:read`	列出并读取链接
`links:write`	创建、upsert 和更新链接
`links:delete`	删除链接
`links:bulk`	批量创建、更新和删除（每次请求最多 100 条链接）
`analytics:read`	读取点击分析
`tags:read`	列出并读取标签
`tags:write`	创建和更新标签
`tags:delete`	删除标签
`domains:read`	列出并读取自定义域名
`domains:write`	添加自定义域名
`domains:delete`	删除自定义域名

API 调用会计入工作区所有者套餐的每月 API 配额。当套餐上限阻止了某个请求时，错误码为 license_limit_reached。

错误与重试

每个失败的请求都会抛出 RevolinkError，包含 HTTP 状态、机器可读的错误码，以及说明该修正什么的消息。

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
  }
}

绝不会重复创建链接的重试

429 总会在 Retry-After 指定的延迟后重试。网络错误和 5xx 响应仅对 GET、PUT 和 DELETE 重试。可能已被处理的 POST 或 PATCH 绝不会重发，因此不会重复创建链接。默认每次尝试超时 30 秒，重试 2 次；把 maxRetries 设为 0 即可关闭重试。

错误码	含义
`invalid_request`	请求有误（400）。消息会说明原因。
`unauthorized`	没有密钥，或密钥无效、已过期（401）。
`forbidden`	密钥缺少权限，或你的角色无法执行此操作（403）。
`license_limit_reached`	已达到套餐上限：链接、标签、域名或 API 调用（403）。
`not_found`	此工作区中没有该项目（404）。
`conflict`	已存在，例如 slug 或标签名已被占用（409）。
`rate_limited`	该密钥每分钟请求超过 300 次（429）。
`network_error`	无响应：网络故障或超时（状态为 0）。

文档、规范与源码

交互式 API 参考

在浏览器中试用 API v2 的每个端点。

OpenAPI 3.1 规范

用任意语言生成你自己的客户端。

GitHub 上的 SDK

TypeScript SDK 的源码、README 和 issue。

npm 上的 revolink

安装软件包并查看最新版本。

常见问题

必须使用 SDK 吗？

不必。SDK 只是 REST API 之上一层轻量的带类型封装。你可以用任意语言，凭 API 密钥和 X-Workspace-Id 请求头直接调用 https://api.revolink.link/apiv2，也可以用 OpenAPI 3.1 规范生成客户端。

SDK 支持哪些运行时？

Node.js 18 或更高版本，以及任何带全局 fetch 的运行时。它没有依赖，提供 ESM 和 CommonJS 构建，并附带由 API 规范生成的 TypeScript 类型。

速率限制是多少？

每个 API 密钥每分钟最多 300 个请求。超出后 API 返回 429 和 Retry-After 请求头，SDK 会自行等待并重试。另外，API 调用会计入工作区所有者套餐的每月配额。

API v1 会怎样？

API v1 已冻结，其响应带有 Deprecation 请求头。新的集成应使用 API v2。

重试时 SDK 会创建重复链接吗？

不会。可能已被处理的 POST 或 PATCH 绝不会重试。只有 429 响应和幂等请求（GET、PUT、DELETE）会被重试。

能从 AI 智能体使用 Revolink 吗？

可以。Revolink MCP 服务器让 Claude、Cursor 等 MCP 客户端用自然语言管理链接。SDK 则适合你自己的代码和脚本。

继续探索

Revolink MCP

在 Claude、Cursor 或任何 MCP 客户端中管理链接。

Zapier 集成

无需写代码即可自动创建链接。

点击追踪

可通过 API 获取的分析数据。

准备好开始使用 Revolink 了吗？

加入通过智能路由控制每次点击的团队和创作者。启动更智能的营销活动，实时优化流量，无限增长。

免费开始

免费计划 · 无需信用卡 · 随时取消

已经有链接了？导入它们

Revolink API 与 SDK 用代码管理你的链接

一行命令安装