PROTOCOL V1 · 协议 v1

The HTTP API behind the draft.草稿背后的 HTTP API。

A small authenticated API for creating WeChat drafts, querying uncertain results, and managing scheduled jobs. It creates drafts only; it never mass-sends or publishes publicly.一组经过鉴权的小型 API：创建公众号草稿、查询未知结果、管理排程任务。它只创建草稿，不群发、不公开发布。

Get a server first先准备服务器 →Full protocol notes完整协议说明

Base URLBase URL
https://your-publy-server
Self-hosted. The hosted API is not open; there is no public key issuance or checkout yet. 自托管地址。托管 API 尚未开放，目前没有公开发 key 或结账入口。

Authentication鉴权

One header.一个请求头。

Every data endpoint requires x-api-key. The admin key manages users/accounts; user keys can only publish to accounts they own and consume their own quota.所有数据接口都需要 x-api-key。admin key 管理用户/账号；用户 key 只能投递自己名下的公众号，并消耗自己的配额。

curl https://your-publy-server/health

curl -H "x-api-key: publy_…" \
  https://your-publy-server/v1/accounts

curl -H "x-api-key: publy_…" \
  https://your-publy-server/v1/quota

Endpoints接口

Draft, query, schedule.投递、查询、排程。

Method	Path	Purpose用途	Key可用 key
`POST`	`/v1/publish`	Create a WeChat draft (article or image post)创建公众号草稿（文章或图片消息）	user / admin
`GET`	`/v1/publish-result/:key`	Reconcile a lost response: `confirmed` or `unknown`对账丢失的回执：`confirmed` 或 `unknown`	user / admin
`GET`	`/v1/accounts`	Account names available to this key该 key 可用的公众号名称	user / admin
`GET`	`/v1/quota`	Current quota state当前配额状态	user / admin
`GET`	`/v1/jobs`	Scheduled jobs排程任务	user / admin
`DELETE`	`/v1/jobs/:id`	Cancel a pending job取消等待中的任务	user / admin
`POST`	`/v1/jobs/:id/retry`	Reconcile or retry a proven-safe job (never blind resend)对账或重试可证明安全的任务（绝不盲目重发）	user / admin
`GET`	`/v1/history`	Recent delivery events visible to this key该 key 可见的最近投递事件	user / admin

Create a draft创建草稿

POST /v1/publishPOST /v1/publish

The CLI and plugin render Markdown to the HTML payload. If you integrate directly, send the rendered article HTML and attachments yourself. Always send a stable idempotencyKey for retry safety.CLI 和插件会先把 Markdown 渲染成 HTML。若直接集成，需要自己发送渲染后的 HTML 与附件；务必带上稳定的 idempotencyKey 以保证重试安全。

POST /v1/publish
x-api-key: publy_…
content-type: application/json

{
  "account": "My Account",
  "type": "article",
  "title": "A draft title",
  "html": "<div id=\"publy\">…</div>",
  "images": [
    { "name": "cover.png", "contentType": "image/png", "data": "<base64>" }
  ],
  "cover": "cover.png",
  "idempotencyKey": "report-2026-11-09"
}

Success returns { mediaId, deduped, account, title, requestId }. A scheduled request returns { jobId, runAt, scheduled: true }. A lost response returns HTTP 409 DRAFT_OUTCOME_UNKNOWN; do not resend — query /v1/publish-result/:key and check the WeChat draft box. 成功返回 { mediaId, deduped, account, title, requestId }；定时请求返回 { jobId, runAt, scheduled: true }。回执丢失时返回 HTTP 409 DRAFT_OUTCOME_UNKNOWN：不要重发，先查 /v1/publish-result/:key 并核对微信草稿箱。

Outcomes结果语义

Never guess from a timeout.不要用超时猜测结果。

confirmedconfirmed

WeChat acknowledged the draft. The result names the account, title and request ID that were actually submitted.微信已确认创建草稿；结果会带上实际提交的公众号、标题与 request ID。

unknownunknown

The request may have landed. Keep the same request ID, inspect the WeChat draft box, then query and decide. A retry with the same key dedupes if it already exists.请求可能已落地。保留同一个 request ID，检查微信草稿箱后再查询并决定；同 key 重试若已存在会自动去重。

rejected / failedrejected / failed

The server or WeChat explicitly refused. Read the code/message; do not treat this as an unknown outcome.服务端或微信明确拒绝。查看 code/message；这不属于结果未知。

scheduledscheduled

A server-side job was accepted. Jobs found running after a restart are marked interrupted and never auto-resent.服务端已接受排程任务。重启时仍在运行的任务会标记为 interrupted，绝不自动重发。

Errors错误码

Stable codes.稳定的错误码。

Code	HTTP	Meaning含义
`UNAUTHORIZED`	401	Missing or invalid API key缺少或无效的 API key
`ACCOUNT_NOT_OWNED`	403	User key cannot publish to that account用户 key 无权投递该公众号
`BAD_REQUEST`	400	Invalid input or unsupported field输入无效或字段不支持
`QUOTA_EXCEEDED`	429	Monthly allowance exhausted; no send attempted本月配额用尽，未发送
`IDEMPOTENCY_CONFLICT`	409	This key already identifies different content该 key 已绑定不同内容
`DRAFT_OUTCOME_UNKNOWN`	409	Unknown result; inspect drafts before another submission结果未知；再次提交前先核对草稿
`WECHAT_*`	502	Explicit WeChat API rejection; message carries the errcode微信 API 明确拒绝，message 中带 errcode

Exit codes for the CLI and the full JSON contract are documented in the Agent CLI guide. Hosted billing and public key registration are not open.CLI 退出码与完整 JSON 契约见 Agent CLI 指南。托管计费与公开 key 注册尚未开放。