delivery-desk/.agents/skills/upload-delivery-desk-work/references/api-contract.md

Delivery Desk upload contract

Current hierarchy and identity

operation group -> project -> work -> review round

• A project belongs to exactly one operation group.
• A work belongs to exactly one project.
• A review round belongs to exactly one work and contains exactly one proposal.
• externalId is unique within a project and is the only supported idempotency key for agent-created works.
• Product-facing operations do not accept a collection/delivery-set ID.

Authentication and scope

Send Authorization: Bearer <DELIVERY_DESK_API_KEY>.

Key scope	Readable projects	Create work	Create round
project	Its bound active project	Only in that project	Only for works in that project
platform	All non-archived projects	Any active project	Any work in an active project

Prefer project. Do not store the token in a plan file.

Discovery endpoints

GET /api/projects

Returns accessible projects. Relevant fields:

{
  "id": 12,
  "group_id": 3,
  "group_name": "示例运营组",
  "name": "光影内容计划",
  "slug": "light-notes",
  "status": "active",
  "review_status": "reviewing"
}

GET /api/projects/:projectId/works

Returns works in the exact project. Use ?externalId=<value> for exact external-ID lookup.

GET /api/works/:workId

Returns current work content, project identity, images, and rounds. Use ?round=N only when inspecting a historical round.

Mutation endpoints

POST /api/projects/:projectId/works

URL mode uses a JSON body:

{
  "externalId": "client-2026-001",
  "title": "作品标题",
  "description": "正文",
  "tags": ["#夏日"],
  "images": ["https://cdn.example.com/01.jpg"]
}

Constraints:

• title is required.
• images contains 1-30 public HTTP/HTTPS URLs.
• Array order is display order; item 1 is the cover.
• An active Tencent COS configuration is required. URLs on its configured public/CDN origin are reused; other public images are downloaded, validated, and stored in that COS before the work is created.
• Cross-origin images must be supported image responses no larger than 20 MB. Local, private, reserved, and non-standard-port targets are rejected.
• Repeating the same projectId + externalId returns the existing work with idempotent: true.

Local-file mode uses multipart/form-data with text fields externalId, title, description, tags and repeated file field images.

• Send tags as a JSON array string.
• Send 1-30 JPEG, PNG, GIF, WebP, or AVIF files, each no larger than 20 MB.
• File order is display order; file 1 is the cover.
• The server validates actual image content instead of trusting only the filename or declared MIME.
• With active Tencent COS configuration, accepted files are streamed from server temporary storage into COS.
• Do not send Base64 in JSON. The agent script reads local files directly into the multipart request; binary bytes never belong in the plan or conversation.

POST /api/works/:workId/rounds

JSON body:

{
  "title": "修改后的标题",
  "description": "修改后的正文",
  "tags": ["#第二轮"],
  "images": ["https://cdn.example.com/round-2.jpg"]
}

This endpoint is not idempotent. One successful call creates exactly one new round. Never blindly retry after a timeout. It applies the same COS reuse/import rules as work creation. It also accepts the same local-file multipart fields, except externalId is omitted.

State guards

• Only active projects accept new works or rounds.
• Closed or archived projects are read-only.
• A completed project may require an authorized administrator to reopen the relevant workflow before another round can be created.

  Status	Script action	Required next step
  400	revise	Correct malformed input, regenerate the plan, and obtain a new confirmation.
  401	ask_operator	Ask the operator to configure or replace DELIVERY_DESK_API_KEY.
  403	ask_operator	Report the exact group/project and ask an administrator to correct Key scope. Never select another target.
  404	ask_operator	Re-run read-only discovery, then ask the operator if the confirmed target is gone or inaccessible.
  409	ask_operator	Report the target state and wait for the operator or administrator to resolve it.
  413	revise	Replace or reduce the image, regenerate the plan, and obtain a new confirmation.
  422	revise	Replace the unreachable or unsupported public image URL, regenerate the plan, and obtain a new confirmation.
  502	ask_operator for writes	Do not retry the write automatically; inspect state and ask the operator to check Tencent COS.
  429, 503, 504	retry for reads only	Wait and retry the same read-only command without changing the target. Writes require ask_operator.

Do not work around 403 or 409 by selecting a different project. Report the exact target and ask the operator or administrator to resolve access/state.