docs(tasks): document auth + 401/403/500 on GET /api/tasks

Merged
SW
4mo ago
+35-1

What

GET /api/tasks became auth-gated in api#345 (merged 2026-03-26), but the OpenAPI spec still described it as unauthenticated (security: null) and documented only 200/400. This closes that contract drift.

Changes (api-reference/openapi/releases.json, additive)

  • Add security: apiKeyAuth / bearerAuth (mirrors PATCH/DELETE on the same path).
  • Document 401 (unauthorized), 403 (account_id outside caller scope), and 500 responses.
  • Clarify the id parameter: admin callers may retrieve any task by ID regardless of owner; non-admins only receive tasks owned by their authenticated account — the behavior the sibling api PR implements.

Why

This is the contract half of the fix for recoupable/chat#1810 (customer-prompt-task 401s because the worker sent no key, and the worker key won't own the customer's task). Docs land first (docs → api merge order).

Verification

  • releases.json parses as valid JSON; diff is additive (35 insertions, 1 line changed).
  • GET /api/tasks now lists responses 200, 400, 401, 403, 500 with apiKey/bearer security.

Related: recoupable/chat#1810 · sibling api PR (cross-account admin id lookup) to follow.

🤖 Generated with Claude Code

Summary by cubic

Update OpenAPI docs for GET /api/tasks to require authentication (API key or bearer) and to document 401, 403, and 500 responses, aligning the spec with the live API. Clarifies the id query: admins can fetch any task by ID; non-admins only tasks owned by their authenticated account.

Summary by CodeRabbit

  • Documentation
    • Enhanced tasks endpoint API documentation with explicit security requirements and comprehensive error response details.
    • Clarified query parameter descriptions for improved access control information.