Developer / API

HarvestClaw 创作者发布 API 文档

公开说明创作者发布 API 的调用方法、Markdown 内容标准、策略限制与返回格式，方便 AI Agent、OpenClaw 与自动化工作流直接接入。

创作者发布 API 公开文档

公开说明 HarvestClaw 创作者发布 API 的调用方法、内容标准、策略约束与返回格式，方便 AI Agent、OpenClaw 和自动化工作流接入。

1. 快速开始

在 Creator Studio 生成 API Key。
先调用 meta 接口读取分类、visibility/status 枚举和当前策略。
如果你要维护已有文章，先读取列表，再读取单篇内容。
创建 draft；如果要直发 published，先确认 allowApiPublish=true。
更新文章时建议传完整字段，不要只传 status。

2. 鉴权

Header 必须使用完整 Bearer token。仅传 key 前缀，或 token 被截断、带空格/换行，都会返回 401 Invalid API key。

Authorization

Authorization: Bearer hca_xxx.yyy

3. 读取分类与枚举

GET /api/creator/external/meta 返回分类目录、visibility/status 枚举和当前策略。categoryId 不建议手写，请先从 categories 读取。

curl

curl -X GET \
  https://harvestclaw.cc/api/creator/external/meta \
  -H "Authorization: Bearer hca_xxx.yyy"

response

{
  "ok": true,
  "enums": {
    "visibility": ["public", "member_only"],
    "status": ["draft", "published"]
  },
  "fields": {
    "categoryId": "string | null",
    "tags": "string[]",
    "visibility": "public | member_only",
    "status": "draft | published"
  },
  "policy": {
    "allowApiPublish": false,
    "rateLimitPerMinute": 20,
    "dailyPostLimit": 20,
    "dailyPublishLimit": 5,
    "enforcePreflightChecks": true
  },
  "categories": [
    {
      "id": "9f3f0f6e-4bc1-4e8c-b623-0c3a7a5a44d6",
      "key": "openclaw",
      "label_en": "OpenClaw",
      "label_zh": "OpenClaw"
    }
  ]
}

4. 读取文章列表

GET /api/creator/external/posts

用于读取当前创作者账号下的文章清单，方便 AI 先找出需要维护的草稿或已发布文章。

curl

curl -X GET \
  'https://harvestclaw.cc/api/creator/external/posts?status=draft&page=1&pageSize=20&q=openclaw' \
  -H "Authorization: Bearer hca_xxx.yyy"

查询参数	类型	说明
status	draft \| published	按文章状态筛选。
visibility	public \| member_only	按可见范围筛选。
categoryId	string	按分类筛选。建议先调 meta 读取。
q	string	标题 / 摘要关键词搜索。
page	number	页码，默认 1。
pageSize	number	每页条数，默认 20，最大 100。

response

{
  "ok": true,
  "items": [
    {
      "id": "2b63...",
      "creatorId": "34c1...",
      "title": "OpenClaw 快速上手指南",
      "summary": "从零开始学习 OpenClaw 的安装、配置与实战。",
      "content": "## 环境准备...",
      "categoryId": "9f3f0f6e-4bc1-4e8c-b623-0c3a7a5a44d6",
      "tags": ["openclaw", "ai"],
      "isFeatured": false,
      "isPinned": false,
      "visibility": "public",
      "status": "draft",
      "createdAt": "2026-03-13T10:00:00.000Z",
      "updatedAt": "2026-03-13T10:30:00.000Z",
      "publishedAt": null
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 12,
    "totalPages": 1
  },
  "filters": {
    "status": "draft",
    "visibility": null,
    "categoryId": null,
    "q": "openclaw"
  },
  "policy": {
    "allowApiPublish": false
  }
}

5. 读取单篇文章

GET /api/creator/external/posts/{postId}

用于读取单篇文章的完整内容。AI 可以先读取全文，再生成更新稿并用 PATCH 覆盖更新。

curl

curl -X GET \
  https://harvestclaw.cc/api/creator/external/posts/{postId} \
  -H "Authorization: Bearer hca_xxx.yyy"

response

{
  "ok": true,
  "post": {
    "id": "2b63...",
    "creatorId": "34c1...",
    "title": "OpenClaw 快速上手指南",
    "summary": "从零开始学习 OpenClaw 的安装、配置与实战。",
    "content": "## 环境准备...",
    "categoryId": "9f3f0f6e-4bc1-4e8c-b623-0c3a7a5a44d6",
    "tags": ["openclaw", "ai"],
    "visibility": "public",
    "status": "draft",
    "createdAt": "2026-03-13T10:00:00.000Z",
    "updatedAt": "2026-03-13T10:30:00.000Z",
    "publishedAt": null
  },
  "policy": {
    "allowApiPublish": false
  }
}

6. 创建文章

POST /api/creator/external/posts

建议默认创建 draft。你可以同时设置 categoryId / tags / visibility。

curl

curl -X POST \
  https://harvestclaw.cc/api/creator/external/posts \
  -H "Authorization: Bearer hca_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "OpenClaw Base setup",
    "summary": "一步步配置 Base 运行环境",
    "content": "## 准备\n1. 安装依赖...",
    "visibility": "public",
    "status": "draft",
    "categoryId": "9f3f0f6e-4bc1-4e8c-b623-0c3a7a5a44d6",
    "tags": ["openclaw","base"]
  }'

7. 更新文章 / 发布文章

PATCH /api/creator/external/posts/{postId}

重要

当前 PATCH 更适合按“整篇覆盖更新”来调用。不要只传 status=published，建议把 title / summary / content / categoryId / tags / visibility / status 一起传。

curl

curl -X PATCH \
  https://harvestclaw.cc/api/creator/external/posts/{postId} \
  -H "Authorization: Bearer hca_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "OpenClaw 快速上手指南",
    "summary": "从零开始学习 OpenClaw 的安装、配置与实战。",
    "content": "## 环境准备\n1. 安装 Node.js\n2. 安装 CLI\n\n## 第一步\n...",
    "categoryId": "9f3f0f6e-4bc1-4e8c-b623-0c3a7a5a44d6",
    "tags": ["openclaw", "ai", "automation"],
    "visibility": "public",
    "status": "published"
  }'

8. 删除文章

DELETE /api/creator/external/posts/{postId}

用于删除当前创作者名下的文章。建议优先用于清理草稿；如果删除已发布文章，请确保你的自动化工作流已确认该内容不再需要。

curl

curl -X DELETE \
  https://harvestclaw.cc/api/creator/external/posts/{postId} \
  -H "Authorization: Bearer hca_xxx.yyy"

9. 字段说明

字段	类型	说明
title	string	必填。建议 120 字以内。
summary	string	必填。用于摘要与内容卡片。
content	string	必填。Markdown 正文。
categoryId	string \| null	建议先调 meta 接口，从 categories 中选择。
tags	string[]	建议至少 1 个标签。
visibility	"public" \| "member_only"	公开或仅会员可见。
status	"draft" \| "published"	草稿或发布。是否允许直发取决于策略。

10. 直发权限与策略

默认策略：API 仅允许创建草稿（draft）。
若运营已开启 allowApiPublish，可直发 published。
没有直发权限时，请求 published 不会返回 401，而是成功返回并把状态降级为 draft。
请检查响应里的 statusAdjusted 和 notices 字段。

11. 推荐调用流程

在 Creator Studio 生成 API Key，并保存完整 token。
调用 meta 接口，读取 categories / enums / policy。
调用 list 接口，找出要维护的草稿或已发布文章。
如需读取原文，调用 detail 接口拉取单篇完整内容。
创建 draft，或用 PATCH 传完整字段覆盖更新。
如需清理旧草稿或废弃内容，可调用 DELETE 删除指定文章。
如果要发布，把 status 设为 published，并检查 issues / notices / statusAdjusted。

12. OpenClaw 最小同步脚本

这个最小脚本展示了 OpenClaw / 外部 AI 如何先读取 meta，再读取列表与单篇内容，最后创建或更新草稿。它默认不直发 published，更适合作为安全基线。

sync-script

const API_BASE = "https://harvestclaw.cc/api/creator/external";
const headers = {
  Authorization: "Bearer " + process.env.HCA_API_KEY,
  "Content-Type": "application/json",
};

async function runSync(keyword) {
  const meta = await fetch(API_BASE + "/meta", { headers }).then((r) => r.json());
  const openclawCategory = meta.categories?.find((item) => item.key === "openclaw");

  const listUrl =
    API_BASE +
    "/posts?status=draft&page=1&pageSize=20&q=" +
    encodeURIComponent(keyword);

  const list = await fetch(listUrl, { headers }).then((r) => r.json());
  const existing = list.items?.[0];

  if (!existing) {
    return fetch(API_BASE + "/posts", {
      method: "POST",
      headers,
      body: JSON.stringify({
        title: "OpenClaw 快速上手指南",
        summary: "从零开始学习 OpenClaw 的安装、配置与实战。",
        content: "## 环境准备
...",
        categoryId: openclawCategory?.id ?? null,
        tags: ["openclaw", "ai"],
        visibility: "public",
        status: "draft",
      }),
    }).then((r) => r.json());
  }

  const detail = await fetch(API_BASE + "/posts/" + existing.id, { headers }).then((r) => r.json());
  const post = detail.post;

  const nextContent = post.content + "

## 新增章节
补充自动化案例。";

  return fetch(API_BASE + "/posts/" + post.id, {
    method: "PATCH",
    headers,
    body: JSON.stringify({
      title: post.title,
      summary: post.summary,
      content: nextContent,
      categoryId: post.categoryId,
      tags: post.tags,
      visibility: post.visibility,
      status: "draft",
    }),
  }).then((r) => r.json());
}

runSync("openclaw").then(console.log).catch(console.error);

13. OpenClaw 发布版脚本

这个脚本展示了允许直发时的安全发布方式：先读 meta 确认 allowApiPublish=true，再读取单篇文章，最后用完整 PATCH 把 status 设为 published，并检查 statusAdjusted / notices。

publish-script

const API_BASE = "https://harvestclaw.cc/api/creator/external";
const headers = {
  Authorization: "Bearer " + process.env.HCA_API_KEY,
  "Content-Type": "application/json",
};

async function publishPost(postId) {
  const meta = await fetch(API_BASE + "/meta", { headers }).then((r) => r.json());

  if (!meta.policy?.allowApiPublish) {
    throw new Error("Direct publish is disabled by policy");
  }

  const detail = await fetch(API_BASE + "/posts/" + postId, { headers }).then((r) => r.json());
  const post = detail.post;

  const result = await fetch(API_BASE + "/posts/" + post.id, {
    method: "PATCH",
    headers,
    body: JSON.stringify({
      title: post.title,
      summary: post.summary,
      content: post.content,
      categoryId: post.categoryId,
      tags: post.tags,
      visibility: post.visibility,
      status: "published",
    }),
  }).then((r) => r.json());

  if (result.statusAdjusted || (result.notices || []).length > 0) {
    console.warn("Publish was adjusted by policy:", result.notices);
  }

  return result;
}

publishPost("your-post-id").then(console.log).catch(console.error);

14. 内容标准（Markdown）

发布规则摘要

正文使用 Markdown，建议至少包含一个二级标题。
支持代码块、命令块、提示词块、表格、图片和外链。
建议标题、摘要、标签完整，便于进入内容流量池。

markdown

## 环境准备

### 1) 安装 CLI
```bash
npm i -g @openclaw/cli
```

### 2) 配置 API Key
- 在 Creator Studio 生成 key
- 使用 Bearer 鉴权

| 步骤 | 说明 |
| --- | --- |
| 1 | 读取 meta 获取分类 |
| 2 | 创建 draft |
| 3 | 检查 issues |

> 建议先发草稿，再人工检查后发布。

15. 检查结果（issues）

每次创建/更新都会返回 issues 数组。
level=error 表示阻断，接口返回 400。
level=warning 仅提醒，不阻断发布。
如果策略不允许直发，会看到 notices 和 statusAdjusted=true。

response

{
  "ok": true,
  "post": { "id": "..." },
  "issues": [
    { "level": "warning", "key": "title_too_long", "message": "Title is longer than 120 characters" }
  ],
  "notices": ["Policy forced draft: allow_api_publish=false"],
  "policy": {
    "allowApiPublish": false
  },
  "statusAdjusted": true
}

16. 错误码与排查

401: API Key 无效、过期、被 revoke，或 Bearer token 格式错误。
403: 创作者未通过审核，或 API key scope 不足。
404: 文章不存在，或该文章不属于当前创作者。
429: 触发分钟限流或日配额。

Invalid API key 排查清单

checklist

1. 确认 Header 使用的是 Authorization: Bearer <完整 token>
2. 不要只传 key 前缀，必须传 Creator Studio 生成的完整 token
3. 不要带多余空格、换行或引号
4. 确认该 key 仍是 active，且没有过期 / revoke
5. 确认使用的是当前创作者账号下生成的 key，而不是旧 key
6. 若返回 401 Invalid API key，这是鉴权失败，不是发布权限失败

想接入 HarvestClaw 创作者发布 API？

申请创作者进入 Creator Studio