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

[sweetmantech]

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.

^{Written for commit a98ba4d. Summary will update on new commits.}

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.

[coderabbitai]

📝 Walkthrough

Walkthrough

The OpenAPI spec for GET /api/tasks is updated to declare apiKeyAuth and bearerAuth security requirements, revise the id parameter description to distinguish admin vs non-admin access behavior, and add 401, 403, and 500 error response definitions each referencing the standard Error schema.

Changes

GET /api/tasks OpenAPI updates

Layer / File(s)	Summary
Security, id parameter, and error responses api-reference/openapi/releases.json	Adds apiKeyAuth and bearerAuth to the security section, clarifies the id query parameter description for admin vs non-admin callers, and documents 401, 403, and 500 error responses referencing the Error schema.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐇 Hop hop, the API grows clear,
Auth keys and bearer tokens appear!
Admins fetch tasks far and wide,
Non-admins stay on their own side.
Four-oh-one, four-oh-three too—
Now errors are documented, brand new! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs(tasks): document auth + 401/403/500 on GET /api/tasks' accurately and concisely summarizes the main changes: documenting authentication requirements and additional error responses for the GET /api/tasks endpoint.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/get-tasks-auth-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
recoup-docs	🟢 Ready	View Preview	Jun 19, 2026, 12:40 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@api-reference/openapi/releases.json`:
- Around line 87-96: The 403 response description for the endpoint is overly
specific by only mentioning account_id in the authorization scope violation
message. Update the description property of the 403 response from "Forbidden -
account_id is outside caller authorization scope" to "Forbidden - requested
resource is outside caller authorization scope" to accurately reflect that
authorization scope restrictions apply to multiple parameters including id,
account_id, and artist_account_id, not just account_id alone.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1eb2ef01-4594-4ec6-8556-37e253a110c8

📥 Commits

Reviewing files that changed from the base of the PR and between d32a134 and a98ba4d.

📒 Files selected for processing (1)

• api-reference/openapi/releases.json

[cubic-dev-ai]

1 issue found across 1 file

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api-reference/openapi/releases.json">

<violation number="1" location="api-reference/openapi/releases.json:88">
P3: The 403 description only mentions `account_id` scope violations, but the `id` parameter description in this same change states that non-admin callers are restricted to tasks belonging to their authenticated account. A 403 can therefore be triggered by scope checks on `id` or `artist_account_id` as well. Consider broadening to something like: "Forbidden - requested resource is outside caller authorization scope".</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: The 403 description only mentions account_id scope violations, but the id parameter description in this same change states that non-admin callers are restricted to tasks belonging to their authenticated account. A 403 can therefore be triggered by scope checks on id or artist_account_id as well. Consider broadening to something like: "Forbidden - requested resource is outside caller authorization scope".

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/releases.json, line 88:

<comment>The 403 description only mentions `account_id` scope violations, but the `id` parameter description in this same change states that non-admin callers are restricted to tasks belonging to their authenticated account. A 403 can therefore be triggered by scope checks on `id` or `artist_account_id` as well. Consider broadening to something like: "Forbidden - requested resource is outside caller authorization scope".</comment>

<file context>
@@ -69,6 +73,36 @@
+            }
+          },
+          "403": {
+            "description": "Forbidden - account_id is outside caller authorization scope",
+            "content": {
+              "application/json": {
</file context>

Suggested change

	"description": "Forbidden - account_id is outside caller authorization scope",
	"description": "Forbidden - requested resource is outside caller authorization scope",

[sweetmantech]

Validated against the api handler — declining the broadening, it would reduce accuracy.

403 on GET /api/tasks is emitted only by the account_id query-param override path (validateAccountIdOverride denial in validateGetTasksQuery). Scope filtering on id or artist_account_id does not 403 — selectScheduledActions just adds an .eq() filter, so a non-admin requesting a task they don't own gets an empty list with 200, not a 403. The id-param wording ("non-admins only receive the task if it belongs to their account") describes that silent filtering, not an authorization error.

So "account_id is outside caller authorization scope" is the precise trigger; broadening to "requested resource" would wrongly imply id/artist_account_id mismatches return 403. Keeping as-is.

[cubic-dev-ai]

Got it — thanks for the correction. I’ll keep the scope narrow to the account_id override path.

[sweetmantech]

Reconciled against the live api preview

Verified the documented 401 is exactly what the endpoint returns on api-otintkleh-recoup.vercel.app (built from the sibling api PR's HEAD):

• no credentials → 401 "Exactly one of x-api-key or Authorization must be provided"
• invalid key → 401 "Unauthorized"
• both mechanisms → 401 (exactly-one)

The added security (apiKey/bearer) + 401 response match reality. 403/500 are documented for parity with PATCH/DELETE and the handler's real error paths (org-override denial / catch-all). Diff is additive; JSON parses.

Merge order: this docs PR → api#689 → tasks#151. cc recoupable/chat#1810