From a98ba4da47c3b3b167148efbdda0c5e3cbe898ce Mon Sep 17 00:00:00 2001
From: Sweets Sweetman <sweetmantech@gmail.com>
Date: Fri, 19 Jun 2026 07:39:37 -0500
Subject: [PATCH] docs(tasks): document auth on GET /api/tasks (401/403/500)
 and admin id lookup

GET /api/tasks became auth-gated in api#345 but the OpenAPI spec still
showed it as unauthenticated (security: null) and only documented 200/400.
Add apiKey/bearer security and the 401/403/500 responses to match the live
contract, mirroring PATCH/DELETE. Note that admin callers can retrieve any
task by id, while non-admins are scoped to their own account.

Contract for recoupable/chat#1810.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 api-reference/openapi/releases.json | 36 ++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json
index d6b01c37..42867501 100644
--- a/api-reference/openapi/releases.json
+++ b/api-reference/openapi/releases.json
@@ -17,11 +17,15 @@
     "/api/tasks": {
       "get": {
         "description": "Retrieve scheduled tasks. Each task includes `recent_runs` (last 5 runs), `upcoming` (next scheduled run times) sourced directly from the Trigger.dev API, and `owner_email` when an account email exists for the task owner. Supports filtering by id, account_id, or artist_account_id.",
+        "security": [
+          { "apiKeyAuth": [] },
+          { "bearerAuth": [] }
+        ],
         "parameters": [
           {
             "name": "id",
             "in": "query",
-            "description": "Filter by task ID (UUID). Returns a single task matching the provided ID.",
+            "description": "Filter by task ID (UUID). Returns a single task matching the provided ID. Admin callers may retrieve any task by ID regardless of owner; non-admin callers only receive the task if it belongs to their authenticated account.",
             "required": false,
             "schema": {
               "type": "string",
@@ -69,6 +73,36 @@
                 }
               }
             }
+          },
+          "401": {
+            "description": "Unauthorized - missing or invalid credentials",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden - account_id is outside caller authorization scope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error while retrieving tasks.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
           }
         }
       },