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

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.

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.

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.