胡凭智

Quickstart

快速开始

Use this page as the canonical integration quickstart for the current review API contract.

Agent task route
/api/review/agent/tasks
Admin login route
/api/auth/login
Decision route
/api/review/tasks/:taskId/decision
Breaking contract update

The review API now expects structured candidates.bodyOptions items with { id, outline, focuses, content }. Decision payloads now support manualOverrides, and bodyDraft.sourceBodyCandidateId is required whenever a body draft is submitted.

There is no backward compatibility for the old upstream schema. Upstream integrators must stop sending legacy flat body candidate payloads.

Step 0

Read this before integrating

The visible examples on this page reflect the new upstream contract and override any stale generated schema elsewhere in the docs.

If you previously integrated against the old upstream review schema, treat this as a breaking migration. The API no longer accepts the old body candidate shape.

The most important change is that reviewers and publishers now need a stable link back to the selected upstream body candidate via bodyDraft.sourceBodyCandidateId.

Step 1

Base routes and role split

Task detail is now shared across agent and admin auth, while asset handling remains split between upload and library browsing.

Use /api/review/agent/tasks to create review tasks as the upstream agent.

Use /api/review/tasks/:taskId for shared task detail lookup with either an agent token or an admin session. Use /api/auth/login to establish the admin session, then /api/review/tasks/:taskId/decision to submit review decisions.

Use POST /api/assets/upload for local image uploads. Use GET /api/assets for shared material library browsing and asset picking.

Step 2

Authentication summary

Creation and rework patching use token auth; review decisions and destructive actions keep session-cookie auth.

Agent routes

Use the configured review agent token header when creating tasks, reading task detail, or patching rejected elements.

Agent authhttp
POST /api/review/agent/tasks
GET /api/review/tasks/:taskId
PATCH /api/review/agent/tasks/:taskId/elements

x-review-agent-token: agent-token-example

Admin routes

Use the admin session cookie for task review, decision submission, delete actions, and publish job management.

Admin authhttp
GET /api/review/tasks
GET /api/review/tasks/:taskId
POST /api/review/tasks/:taskId/decision
POST /api/review/tasks/:taskId/publish-jobs
POST /api/review/tasks/:taskId/publish-jobs/:jobId/retry

Cookie: review_admin_session=...

Step 3

Minimal request order

This sequence matches the current upstream integration flow from task creation through review and optional publishing.

Stage 1

1. 代理创建任务

携带代理令牌请求头提交任务创建负载。

调用 POST /api/review/agent/tasks，并通过 `x-review-agent-token` 传入账号、主题和候选内容集合。

主题模板不再作为创建任务的外部输入；正文工作台会在正文草稿层维护主题。

正文候选必须由上游直接提供结构化 `bodyOptions[]`，其中每个候选都要包含 `id`、`outline`、`focuses` 和 `content`。

`outline` 在实际接口中是单个字符串，多个大纲片段通过 `|` 分隔；`focuses` 是字符串数组。

成功后返回已落库的任务记录，初始状态为 `pending_review`。

Stage 2

2. 管理员执行审核

先登录建立管理员会话，再读取任务列表或任务详情。

通过 POST /api/auth/login 建立 `review_admin_session` Cookie。

再使用 GET /api/review/tasks 或 GET /api/review/tasks/:taskId 查看待处理任务。

Stage 3

3. 提交审核决策

选择一种审核动作，并提交完整的选中内容。

无论是否立即发布，只要审核通过，任务都会进入 `approved`。

如果审核员对标题、摘要、图片或正文做了人工修改，应一并提交 `manualOverrides`，用于保留候选项到最终采用值的审计关系。

如果希望审核通过后立刻排队发布，应使用 `approve_and_publish`，它会创建 `triggerMode: 'auto_after_approval'` 的发布任务。

若需整单驳回，可使用空的 `rejectedElements` 与 `lockedSelections`；若只驳回部分字段，则仍需同时提供两者。

Stage 4

4. 管理发布任务与重试

通过 publish-jobs 接口管理审核通过后的发布生命周期。

当任务已审核通过时，可用 POST /api/review/tasks/:taskId/publish-jobs 创建手动发布任务。

若已有失败发布记录，可用 POST /api/review/tasks/:taskId/publish-jobs/:jobId/retry 基于失败快照重新排队。

Step 4

Create-task example with structured body candidates

Use stable candidate ids so downstream review decisions can point back to the selected upstream candidate.

Requesthttp
POST /api/review/agent/tasks
x-review-agent-token: agent-token-example
Content-Type: application/json

{
  "externalContentId": "post_2026_04_21",
  "title": "Spring campaign recap",
  "summary": "Draft review request generated by the upstream agent.",
  "candidates": {
    "bodyOptions": [
      {
        "id": "candidate-primary",
        "outline": "Lead with campaign outcome | Explain the lesson learned | Close with CTA",
        "focuses": [
          "conversion",
          "retention"
        ],
        "content": "Primary long-form draft content"
      },
      {
        "id": "candidate-short",
        "outline": "Hook | Three bullets | CTA",
        "focuses": [
          "reach"
        ],
        "content": "Shorter alternative draft content"
      }
    ],
    "coverImages": [
      "https://example.com/cover-01.png"
    ]
  },
  "attachments": [
    {
      "kind": "image",
      "assetId": "asset_local_cover_01"
    }
  ]
}
Required candidate shape

Each entry in candidates.bodyOptions must provide id, outline, focuses, and content. Keep the id stable enough to round-trip through review decisions and rework.

outline is a single string in the live API. If you need multiple outline segments, join them with |.

Step 5

Decision example with manual overrides

Decision payloads can now carry explicit manual overrides, and body draft selections must include the source candidate id.

Requesthttp
POST /api/review/tasks/:taskId/decision
Cookie: review_admin_session=...
Content-Type: application/json

{
  "action": "approve_without_publish",
  "selections": {
    "title": "Spring campaign recap",
    "summary": "Approved summary text",
    "body": "Approved body draft content",
    "bodyImages": [
      "https://example.com/body-01.png"
    ],
    "coverImage": "https://example.com/cover-01.png"
  },
  "bodyDraft": {
    "markdown": "Approved body draft content",
    "sourceBodyCandidateId": "candidate-primary",
    "sourceBodyCandidate": "Primary long-form draft content",
    "bodyEditedFromCandidate": true,
    "themeTemplate": "cyan"
  }
}
Required field

If the decision payload includes bodyDraft, then bodyDraft.sourceBodyCandidateId is required. Do not submit synthesized body draft content without linking it to one of the provided upstream candidates.

Step 6

Asset routes

Uploading a local image and browsing the shared library are now separate integrations.

Local image uploads

Send local files to POST /api/assets/upload. Use the returned asset id in task payloads, decision payloads, or manual overrides.

Shared material library

Keep using /api/assets for shared library discovery and asset browsing. That route is no longer the entry point for local uploads.

Step 7

Next pages

Continue with the workflow and reference pages that expand on the same updated contract.

发布任务参考

手动排队发布任务与重试路由说明。

认证说明

审核相关接口的代理令牌与管理员会话认证约定。

审核流程

任务如何从待审核流转到通过、返工与发布。

发布流程

发布任务如何排队、重试和完成。