Litport API

Litport API可让集成程序访问您自己的令牌、套餐和按流量计费（PPG）数据，并提供少量写入操作：令牌位置、轮换、新IP和套餐IP白名单。

基础URL：

https://litport.net/api/v1

分区#

认证#

在设置页面创建API密钥。创建或轮换后，其完整值仍可在该页面查看。

export LITPORT_API_KEY='lit_replace_with_your_key'
curl 'https://litport.net/api/v1/tokens' \
  -H "Authorization: Bearer $LITPORT_API_KEY"

外部客户端须严格使用Bearer方案。不要在查询字符串、JSON请求体、Cookie或代理用户名中发送密钥。请将其作为机密保存，仅限服务端工作负载访问，并在可能泄露时轮换密钥。

这些文档页面上的运行控件使用您已登录的Litport账户，且仅用于GET请求。所有写入操作都需要Bearer API密钥。

凭证边界#

API通用规则#

所有分区的每个端点都遵循相同的规则，因此集成只需学习一次。

标识符：使用公开的数字tokenId和packageId。通过authKey选择按流量计费代理池，通过IP本身指定白名单IP。任何端点都不接受或返回数据库ID。

命名：字段使用camelCase。新增的枚举值和slug使用小写kebab-case，例如awaiting-payment、more-allowed-ips、package-inactive。错误码保持UPPER_SNAKE。自由文本（标签、凭证、代理池名称）不受限制。少数值保留原有拼写，没有为统一而重命名：用量中的trafficBasis: "customer_chargeable"和timezone: "UTC"，以及令牌的type/status值。

取值：时间使用ISO-8601 UTC格式，以Z结尾。较大的字节数是十进制字符串，而不是JSON数字，因此客户端不会丢失精度。

响应结构：单个对象为{"data": {...}}。返回列表的端点始终响应{"data": [...], "page": {"nextCursor": ...}}。列表分为两种：

• 分页列表（GET /tokens、GET /packages、GET /pay-per-gb/geo）接受limit和cursor；
• 完整列表（GET /pay-per-gb/pools、GET /tokens/{tokenId}/location/options）始终返回全部条目，不接受limit或cursor，并返回page.nextCursor: null。

对象内部的数组，例如用量的buckets、IP白名单的ips或套餐的tokenIds，是普通字段，不是端点列表。

分页：limit为1–100，默认50。cursor是上一次响应中的page.nextCursor，原样传回；请将其视为不透明值。无效的limit返回400 INVALID_LIMIT；无效或不属于当前请求的cursor返回400 INVALID_CURSOR。持续使用page.nextCursor发起请求，直到其为null。

错误：每个错误的格式为{"error": {"code", "message", "requestId", "docsUrl"}}，需要等待时还会附带nextChangeAt。完整的状态码表和每个错误码的详细说明见API错误。

写入：所有写入操作都需要Bearer API密钥；已登录的文档会话只能读取。端点有请求体时发送JSON。不存在前置条件请求头：以最后提交的写入为准。除POST /tokens/{tokenId}/new-ip外，所有写入操作都可以安全重复执行。

速率限制#

有两项限制，均通过标准响应头返回。

• 每个API密钥每60秒120次请求。超出后返回429 RATE_LIMITED。
• 每个套餐每60秒20次IP白名单写入（PUT/DELETE /packages/{packageId}/allowed-ips…）。先检查密钥限制；通过该检查且同时属于IP白名单写入的请求，随后会检查套餐限制，并改为返回该限制器的响应头。

每个响应都应读取RateLimit-Limit、RateLimit-Remaining和RateLimit-Reset；被拒绝的请求还会携带Retry-After。

约定#

• 响应为JSON。
• X-Request-ID标识请求；报告故障时请附上。
• 已认证的响应带有Cache-Control: private, no-store和Vary: Authorization。
• 此API中没有ETag，也没有If-Match前置条件。

机器可读规范#

所有路径、参数、请求体和响应结构请以OpenAPI 3.1文档为准。在使用各端点的数据之前，先处理错误格式。