REST API 参考

了解认证、资源列表、内容创建、错误处理和 BlendDuck OpenAPI 3.1 规范。

BlendDuck v1 API 使用 HTTPS 和 JSON，并由 Bearer API Key 选择唯一组织。OpenAPI 3.1 规范包含全部 25 个操作、请求和响应 Schema，也是生成 SDK 与兼容性检查的事实来源。

Base URL 与认证

https://blendduck.com/api/v1

从控制台 → 开发者 → API Key创建和管理组织 Key。完整 Key 只在创建时显示一次，请保存到密钥管理器，并仅从受信任的服务端代码发送：

Authorization: Bearer $BLENDDUCK_API_KEY
Content-Type: application/json

Key 只选择一个组织。标准 v1 请求不接受 workspace_id，也不会使用浏览器当前工作区 Cookie 作为认证回退。

第一个请求

curl --fail-with-body https://blendduck.com/api/v1/tenant \
  -H "Authorization: Bearer $BLENDDUCK_API_KEY"

成功响应使用 data 包装，并在 meta.requestId 与 X-Request-ID Header 中返回相同请求 ID。

Endpoint 列表

资源	操作
Tenant	`GET /tenant`
Channels	`GET /channels`、`GET /channels/{channelId}`、`DELETE /channels/{channelId}`
Posts	`GET /posts`、`POST /posts`、`GET/PATCH/DELETE /posts/{postId}`
Analytics	`GET /analytics`
Media	`GET /media`、`POST /media`、`GET /media/{mediaId}`
Providers	`GET /providers`、`GET /providers/{providerId}`
Webhooks	`GET/POST /webhooks`、`GET/PATCH/DELETE /webhooks/{webhookEndpointId}`
Webhook 操作	Secret 轮换、测试事件、Delivery 列表/详情和失败重放

所有 Parameter、Enum、字段、响应和 Scope 请以 OpenAPI 文件为准。各语言客户端参见 SDK。

创建多渠道内容

集成初期建议先创建草稿。把示例 UUID 替换为 GET /channels 返回的真实渠道 ID：

curl --fail-with-body https://blendduck.com/api/v1/posts \
  -X POST \
  -H "Authorization: Bearer $BLENDDUCK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-post-2026-08-09" \
  --data '{
    "content": "Hello from BlendDuck",
    "mode": "draft",
    "targets": [
      { "channelId": "00000000-0000-4000-8000-000000000000" }
    ]
  }'

post.id 标识一条逻辑内容，targets[] 是各渠道独立发布目标。目标可覆盖 content、publishAt、media、settings 或 thread。发布方式包括 draft、schedule、next_available、prioritize 和 publish_now。

所有写操作应发送 Idempotency-Key。使用相同 Key 和相同 Payload 重复请求会返回原结果；同一 Key 搭配不同 Payload 会返回冲突。

分页与日期

列表接口接受 1–100 的 limit 和不透明 cursor。读取 meta.pagination.nextCursor 并原样传回；当其为 null 时停止。不要解析或自行生成 Cursor。

各接口的筛选和排序参数以 /openapi.json 为准。日期时间使用 RFC 3339，并包含 Z 或明确时区偏移。

错误格式

{
  "error": {
    "code": "validation_error",
    "message": "The request could not be accepted",
    "details": []
  },
  "meta": { "requestId": "request-id" }
}

状态码	含义	客户端处理
`400`	请求语法或传输错误	修改请求后再发送。
`401`	Key 缺失、无效或已撤销	更换或轮换凭据。
`403`	有效 Key 缺少访问权限	授予所需 Scope 或角色。
`404`	当前组织看不到该资源	检查 ID 与 Tenant。
`409`	资源状态或幂等冲突	先读取当前资源。
`422`	字段或平台验证失败	根据 `error.details` 修改输入。
`429`	达到配额或限流	遵守 `Retry-After`。
`5xx`	BlendDuck 或依赖故障	仅对安全/幂等操作进行退避重试。

响应会包含 RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset 和 RateLimit-Policy；限流响应还会包含 Retry-After。

安全与追踪

可发送 X-Request-ID 关联跨系统流程，也可以记录服务端生成的值。日志必须排除 Authorization Header、Webhook Secret、社交 Token 和不必要的客户内容。

每个环境和集成使用独立 Key，只授予最小 Scope。怀疑泄露时立即轮换，绝不能把组织 Key 打包进浏览器或移动端应用。

版本兼容

响应通过 X-BlendDuck-API-Version 标识版本。v1 可以增加兼容字段，客户端应忽略未知响应字段；删除或不兼容变更需要新版本。旧的 workspace-addressed 路径只为现有集成保留，不出现在 OpenAPI、SDK 和新示例中。

本页目录