Docs
API 密钥与文档
API 密钥与文档
了解如何管理 API 密钥进行编程访问，以及如何使用 REST API 与外部服务集成。
欢迎来到你的开发者中心。本指南提供管理 API 密钥和以编程方式操作内容所需的一切。我们的 REST API 让你可以构建自定义集成、自动化工作流，并扩展平台功能。
API 密钥管理
API 密钥提供对你账户数据的安全认证访问。你可以创建多个拥有不同权限的密钥，用于不同的应用。
创建新 API 密钥
要开始使用 API，首先需要创建一个 API 密钥。
-
在控制台中进入 API 密钥 页面。
-
点击 「创建 API 密钥」 按钮。
-
在弹出的对话框中填写以下信息：
- 名称：为密钥取一个描述性的名称，方便后续识别（如「Zapier 集成」、「我的自定义应用」）。
- 过期日期（可选）：为增强安全性，你可以设置密钥自动过期的日期和时间。留空表示永不过期。
- 权限（作用域）：这是最关键的部分。选择该密钥拥有的特定权限。始终遵循最小权限原则：只授予应用绝对需要的权限。
-
点击 「创建 API 密钥」。
重要： 新 API 密钥创建后 只显示一次。请立即复制并保存到安全的地方。你将无法再次查看。
管理你的 API 密钥
创建后，你的 API 密钥会列在表格中。你可以在这里管理和监控它们：
- 查看密钥前缀：出于安全考虑，只存储和显示密钥的开头部分（
keyPrefix）。这帮你识别正在使用的密钥而不暴露完整密钥。 - 切换可见性：点击眼睛图标临时显示密钥前缀。
- 状态（活跃/停用）：你可以随时启用或停用密钥。停用的密钥无法用于 API 请求。这在需要临时禁用集成而不永久删除密钥时很有用。
- 最后使用：显示密钥最后一次成功调用 API 的时间，帮你识别未使用的密钥。
- 过期与创建时间：显示密钥的过期日期和创建日期。
- 操作：下拉菜单允许你 启用/停用 或永久 删除 密钥。
API 文档
我们的 API 设计简洁、易用。
API 概览
- 基础 URL：所有 API 端点相对于此 URL。
https://postion.app/api/v1- 格式：所有请求和响应均为
JSON格式。 - 频率限制：为确保稳定性，API 限制为 每分钟 100 次请求。每个响应都包含频率限制头。
认证
所有 API 请求必须在 Authorization 头中使用 Bearer Token 进行认证。
Authorization: Bearer pk_your_api_key_here将 pk_your_api_key_here 替换为你创建的 API 密钥。
cURL 请求示例
以下是使用 cURL 获取文章列表的示例：
curl -X GET "https://postion.app/api/v1/posts" \
-H "Authorization: Bearer pk_your_api_key_here" \
-H "Content-Type: application/json"安全最佳实践：
- 永远不要在客户端代码中暴露 API 密钥（如公开网站的 JavaScript）。
- 使用服务器上的环境变量安全存储密钥。
- 定期轮换 API 密钥。
- 每个密钥只授予最小必要权限。
端点
我们提供一系列端点来管理你的内容。以下是部分主要资源。
文章
Posts 端点允许你管理博客文章。
GET /api/v1/posts：列出所有文章。POST /api/v1/posts：创建新文章。GET /api/v1/posts/{id}：按 ID 获取特定文章。PUT /api/v1/posts/{id}：更新特定文章。DELETE /api/v1/posts/{id}：删除文章。
站点
Sites 端点允许你管理站点。
GET /api/v1/sites:列出所有站点。
Webhooks
Webhooks 允许你接收账户中发生事件的实时通知。
GET /api/v1/webhooks:列出所有 Webhooks。POST /api/v1/webhooks:创建新 Webhook。
代码示例
以下是不同编程语言使用 API 的实际示例。
JavaScript (Node.js) - 创建文章
const response = await fetch('https://postion.app/api/v1/posts', {
method: 'POST',
headers: {
'Authorization': 'Bearer pk_your_api_key_here',
'Content-Type': 'application/json',
},
body: JSON.stringify({
title: 'My New Post',
content: { /* JSON 格式的文章内容 */ },
description: 'A brief description of my post',
published: true,
tags: ['javascript', 'api']
})
});
const data = await response.json();
console.log('Created post:', data);Python - 获取文章
import requests
headers = {
'Authorization': 'Bearer pk_your_api_key_here',
'Content-Type': 'application/json'
}
response = requests.get(
'https://postion.app/api/v1/posts',
headers=headers,
params={'published': True}
)
if response.status_code == 200:
data = response.json()
posts = data['data']
print(f"Found {len(posts)} posts")
else:
print(f"Error: {response.status_code}")处理 Webhooks (Node.js/Express)
验证 Webhook 签名以确保请求的合法性至关重要。
// Express.js webhook handler
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
const signature = req.headers['x-webhook-signature'];
const payload = req.body;
// 验证签名
const expectedSignature = crypto
.createHmac('sha256', process.env.WEBHOOK_SECRET)
.update(payload)
.digest('hex');
if (signature !== expectedSignature) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(payload);
// 处理事件
switch (event.event.type) {
case 'post.published':
// 处理文章发布...
break;
default:
console.log('Unknown event type:', event.event.type);
}
res.status(200).send('OK');
});更多 API 端点
以下是更多可用于构建全面集成的端点。
订阅者
以编程方式管理你的订阅者群体。
| 方法 | 端点 | 说明 |
|---|---|---|
GET | /api/v1/subscribers | 列出所有订阅者 |
GET | /api/v1/subscribers/{id} | 获取订阅者详情 |
POST | /api/v1/subscribers | 添加新订阅者 |
PUT | /api/v1/subscribers/{id} | 更新订阅者信息 |
DELETE | /api/v1/subscribers/{id} | 移除订阅者 |
示例：获取订阅者
const response = await fetch('https://postion.app/api/v1/subscribers', {
headers: {
'Authorization': 'Bearer pk_your_api_key_here',
}
});
const { data: subscribers, pagination } = await response.json();
console.log(`Found ${subscribers.length} subscribers`);方案
管理站点的订阅方案。
| 方法 | 端点 | 说明 |
|---|---|---|
GET | /api/v1/plans | 列出所有方案 |
GET | /api/v1/plans/{id} | 获取方案详情 |
POST | /api/v1/plans | 创建新方案 |
PUT | /api/v1/plans/{id} | 更新方案 |
订阅
访问订阅者的订阅数据。
| 方法 | 端点 | 说明 |
|---|---|---|
GET | /api/v1/subscriptions | 列出活跃订阅 |
GET | /api/v1/subscriptions/{id} | 获取订阅详情 |
交易
查看收入和交易历史。
| 方法 | 端点 | 说明 |
|---|---|---|
GET | /api/v1/transactions | 列出所有交易 |
GET | /api/v1/transactions/{id} | 获取交易详情 |
标签
管理内容标签。
| 方法 | 端点 | 说明 |
|---|---|---|
GET | /api/v1/tags | 列出所有标签 |
POST | /api/v1/tags | 创建新标签 |
PUT | /api/v1/tags/{id} | 更新标签 |
DELETE | /api/v1/tags/{id} | 删除标签 |
频率限制详情
为确保平台稳定，API 请求受频率限制。
频率限制头
每个 API 响应都包含这些头：
| 头 | 说明 |
|---|---|
X-RateLimit-Limit | 每个时间窗口的最大请求数 |
X-RateLimit-Remaining | 当前窗口内剩余请求数 |
X-RateLimit-Reset | 窗口重置的 Unix 时间戳 |
各方案频率限制
| 方案 | 每分钟请求数 | 每日请求数 |
|---|---|---|
| Free | 30 | 1,000 |
| Launch | 60 | 5,000 |
| Pro | 100 | 20,000 |
| Enterprise | 自定义 | 自定义 |
处理频率限制
超出限制时，你会收到 429 Too Many Requests 响应：
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please slow down.",
"retry_after": 30
}
}最佳实践：
- 收到 429 时实现指数退避
- 尽可能缓存响应
- 使用 Webhooks 替代轮询获取实时更新
错误处理
所有 API 错误遵循统一格式。
错误响应格式
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": {}
}
}常见错误码
| 错误码 | HTTP 状态码 | 说明 |
|---|---|---|
UNAUTHORIZED | 401 | API 密钥无效或缺失 |
FORBIDDEN | 403 | 密钥缺少所需权限 |
NOT_FOUND | 404 | 资源不存在 |
VALIDATION_ERROR | 400 | 请求参数无效 |
RATE_LIMIT_EXCEEDED | 429 | 请求过多 |
INTERNAL_ERROR | 500 | 服务端出错 |
分页
列表端点支持大数据集的分页。
查询参数
| 参数 | 类型 | 说明 | 默认值 |
|---|---|---|---|
page | number | 页码 | 1 |
limit | number | 每页条数 | 20 |
sort | string | 排序字段 | created_at |
order | string | asc 或 desc | desc |
分页响应
{
"data": [...],
"pagination": {
"page": 1,
"limit": 20,
"total": 150,
"total_pages": 8,
"has_next": true,
"has_prev": false
}
}API 更新日志
了解 API 更新动态。
版本历史
| 版本 | 日期 | 变更 |
|---|---|---|
| v1.2 | 2025-08 | 新增订阅者和交易端点 |
| v1.1 | 2025-06 | 新增方案和订阅端点 |
| v1.0 | 2025-01 | API 初始发布 |
版本控制： API 通过 URL 路径进行版本控制（/api/v1/）。破坏性变更将作为新版本发布。