fix(v2): serve HEAD, advertise PATCH, and document the reachable 403

Three HTTP-semantics defects on the v2 surface, all found by probing the
published contract rather than the happy path.

**HEAD answered 500 on every v2 endpoint.** Next implements a missing `HEAD`
export by aliasing it onto `GET` and dropping the body when it sends, so a
route's `GET` legitimately runs with `request.method === 'HEAD'`. The builders'
method guard compared that against the contract's declared method and threw, so
`HEAD /api/v2/workflows` and every sibling replied 500 — which is what health
checkers, uptime monitors, link checkers, and some CDNs send, all of them
reading the API as hard-down. RFC 9110 §9.3.2 makes HEAD identical to GET but
for the body, which is exactly what running the GET path produces. Fixed once in
`methodMatchesContract`, shared by all five route builders; every other mismatch
stays a hard error so a handler exported under the wrong verb still fails loudly.

**CORS advertised `GET,POST,OPTIONS,PUT,DELETE`** while the v2 spec has 17
`PATCH` operations, so a browser preflight for any of them was rejected. It also
advertised `PUT`, which two operations use — the shape of a hand-maintained list
outgrown by its surface. The list stays hand-written because middleware cannot
import the contract tree without pulling Zod into the edge bundle, but it is now
pinned by a test that sweeps the real contracts and fails on any method it omits.

**Six operations omitted a 403 their siblings documented** — three knowledge
reads and three file-upload operations. Traced from the code rather than the
spec: `requirePermission` throws `NoWorkspaceAccessError` for no access at all
(concealed as 404) but `InsufficientWorkspacePermissionsError` for access below
`minimumRole` (a real 403), and `PersonalApiKeysDisabledError` reaches every
operation a personal API key can call. So 403 was reachable on all six and the
omission was an accident of hand-assembled error lists, not a policy. They now
use the shared `RESOURCE_ERRORS` / `RESOURCE_CONFLICT_ERRORS` sets, and two
operations spelling those same sets by hand were normalized onto them.

All 128 documented operations now declare 403. The rules for HEAD, for the
403/404 split, and for using the shared error sets are recorded in
`.agents/skills/v2-api-conventions/SKILL.md`.

Author: waleedlatif1

.agents/skills/v2-api-conventions/SKILL.md

@@ -62,7 +62,16 @@ Two of these carry real design weight:
 
 **404 is deliberately overloaded.** A workspace the caller cannot reach answers `404 "Workspace not found"`, never 403 — a 403 would confirm the resource exists. `createV2ResourceConcealmentPolicy` does this by mapping a cross-tenant authorization failure to `v2Error('NOT_FOUND', ...)`. The rollout gate answers the same way for the same reason (`gate.ts`: "an ungated caller cannot distinguish 'not in the rollout cohort' from 'no such endpoint'"), and so does the unknown-path catch-all at `app/api/v2/[[...segments]]/route.ts` — its body is byte-identical to the gate's on purpose.
 
-**500 is never caller-reachable.** Any input a caller can send must be rejected at the contract boundary with a 400. If you can construct a query string or body that produces a 500, that is a bug in the contract, not something to wrap in a `try`/`catch`. `v2ErrorForOrchestration` also replaces the message on an unclassified failure with a generic one, so internal detail never leaks.
+**500 is never caller-reachable.** Any input a caller can send must be rejected at the contract boundary with a 400. If you can construct a query string or body that produces a 500, that is a bug in the contract, not something to wrap in a `try`/`catch`. `v2ErrorForOrchestration` also replaces the message on an unclassified failure with a generic one, so internal detail never leaks. A caller-reachable 500 has shipped twice — a fractional `limit` reaching `LIMIT 2.5`, and a plain `HEAD` tripping the builder's method guard — so treat "a well-formed request produced a 500" as the highest-severity class of defect on this surface.
+
+**Which of 403 and 404 an operation documents follows from its authorization, not from whether it is a read.** `requirePermission` throws two different failures: no workspace access at all is `NoWorkspaceAccessError`, which `createV2ResourceConcealmentPolicy` conceals as 404; access below the operation's `minimumRole` is `InsufficientWorkspacePermissionsError`, which stays a 403. So:
+
+- An operation whose `minimumRole` is `write` or `admin` can always 403 — a member with a lower role hits it. Document 403.
+- An operation whose `minimumRole` is `read` cannot 403 *that* way, because `read` is the floor of the `read < write < admin` ordering and anyone without access is concealed as 404 instead. It can still 403 through `PersonalApiKeysDisabledError` (a personal API key against a workspace whose organization disabled them) or `WorkspaceApiKeyAuthorizationError` (`workspaceApiKey: 'deny'`), and every v2 operation is reachable by a personal API key. **So in practice every workspace-scoped v2 operation documents 403**, and the reads that omitted it were wrong, not principled.
+
+Use the shared sets in `contracts/v2/openapi/shared.ts` — `RESOURCE_ERRORS`, `RESOURCE_CONFLICT_ERRORS`, `RESOURCE_MUTATION_ERRORS` — rather than assembling a per-operation list; all three already include `Forbidden`, and hand-assembled lists are how three knowledge reads and three upload operations quietly lost it.
+
+**HEAD is answered by the `GET` handler, not rejected.** Next aliases a missing `HEAD` export onto `GET` and drops the body when sending, so a route's `GET` legitimately runs with `request.method === 'HEAD'`. The builders' method guard accepts that pairing via `methodMatchesContract`; any other mismatch stays a hard error. Never hand-write a `HEAD` export to "fix" this.
 
 ## Rule 3 — a collection that returns `nextCursor` must accept `limit` + `cursor`, and must apply them
 

.claude/commands/v2-api-conventions.md

@@ -61,7 +61,16 @@ Two of these carry real design weight:
 
 **404 is deliberately overloaded.** A workspace the caller cannot reach answers `404 "Workspace not found"`, never 403 — a 403 would confirm the resource exists. `createV2ResourceConcealmentPolicy` does this by mapping a cross-tenant authorization failure to `v2Error('NOT_FOUND', ...)`. The rollout gate answers the same way for the same reason (`gate.ts`: "an ungated caller cannot distinguish 'not in the rollout cohort' from 'no such endpoint'"), and so does the unknown-path catch-all at `app/api/v2/[[...segments]]/route.ts` — its body is byte-identical to the gate's on purpose.
 
-**500 is never caller-reachable.** Any input a caller can send must be rejected at the contract boundary with a 400. If you can construct a query string or body that produces a 500, that is a bug in the contract, not something to wrap in a `try`/`catch`. `v2ErrorForOrchestration` also replaces the message on an unclassified failure with a generic one, so internal detail never leaks.
+**500 is never caller-reachable.** Any input a caller can send must be rejected at the contract boundary with a 400. If you can construct a query string or body that produces a 500, that is a bug in the contract, not something to wrap in a `try`/`catch`. `v2ErrorForOrchestration` also replaces the message on an unclassified failure with a generic one, so internal detail never leaks. A caller-reachable 500 has shipped twice — a fractional `limit` reaching `LIMIT 2.5`, and a plain `HEAD` tripping the builder's method guard — so treat "a well-formed request produced a 500" as the highest-severity class of defect on this surface.
+
+**Which of 403 and 404 an operation documents follows from its authorization, not from whether it is a read.** `requirePermission` throws two different failures: no workspace access at all is `NoWorkspaceAccessError`, which `createV2ResourceConcealmentPolicy` conceals as 404; access below the operation's `minimumRole` is `InsufficientWorkspacePermissionsError`, which stays a 403. So:
+
+- An operation whose `minimumRole` is `write` or `admin` can always 403 — a member with a lower role hits it. Document 403.
+- An operation whose `minimumRole` is `read` cannot 403 *that* way, because `read` is the floor of the `read < write < admin` ordering and anyone without access is concealed as 404 instead. It can still 403 through `PersonalApiKeysDisabledError` (a personal API key against a workspace whose organization disabled them) or `WorkspaceApiKeyAuthorizationError` (`workspaceApiKey: 'deny'`), and every v2 operation is reachable by a personal API key. **So in practice every workspace-scoped v2 operation documents 403**, and the reads that omitted it were wrong, not principled.
+
+Use the shared sets in `contracts/v2/openapi/shared.ts` — `RESOURCE_ERRORS`, `RESOURCE_CONFLICT_ERRORS`, `RESOURCE_MUTATION_ERRORS` — rather than assembling a per-operation list; all three already include `Forbidden`, and hand-assembled lists are how three knowledge reads and three upload operations quietly lost it.
+
+**HEAD is answered by the `GET` handler, not rejected.** Next aliases a missing `HEAD` export onto `GET` and drops the body when sending, so a route's `GET` legitimately runs with `request.method === 'HEAD'`. The builders' method guard accepts that pairing via `methodMatchesContract`; any other mismatch stays a hard error. Never hand-write a `HEAD` export to "fix" this.
 
 ## Rule 3 — a collection that returns `nextCursor` must accept `limit` + `cursor`, and must apply them
 

.cursor/commands/v2-api-conventions.md

@@ -56,7 +56,16 @@ Two of these carry real design weight:
 
 **404 is deliberately overloaded.** A workspace the caller cannot reach answers `404 "Workspace not found"`, never 403 — a 403 would confirm the resource exists. `createV2ResourceConcealmentPolicy` does this by mapping a cross-tenant authorization failure to `v2Error('NOT_FOUND', ...)`. The rollout gate answers the same way for the same reason (`gate.ts`: "an ungated caller cannot distinguish 'not in the rollout cohort' from 'no such endpoint'"), and so does the unknown-path catch-all at `app/api/v2/[[...segments]]/route.ts` — its body is byte-identical to the gate's on purpose.
 
-**500 is never caller-reachable.** Any input a caller can send must be rejected at the contract boundary with a 400. If you can construct a query string or body that produces a 500, that is a bug in the contract, not something to wrap in a `try`/`catch`. `v2ErrorForOrchestration` also replaces the message on an unclassified failure with a generic one, so internal detail never leaks.
+**500 is never caller-reachable.** Any input a caller can send must be rejected at the contract boundary with a 400. If you can construct a query string or body that produces a 500, that is a bug in the contract, not something to wrap in a `try`/`catch`. `v2ErrorForOrchestration` also replaces the message on an unclassified failure with a generic one, so internal detail never leaks. A caller-reachable 500 has shipped twice — a fractional `limit` reaching `LIMIT 2.5`, and a plain `HEAD` tripping the builder's method guard — so treat "a well-formed request produced a 500" as the highest-severity class of defect on this surface.
+
+**Which of 403 and 404 an operation documents follows from its authorization, not from whether it is a read.** `requirePermission` throws two different failures: no workspace access at all is `NoWorkspaceAccessError`, which `createV2ResourceConcealmentPolicy` conceals as 404; access below the operation's `minimumRole` is `InsufficientWorkspacePermissionsError`, which stays a 403. So:
+
+- An operation whose `minimumRole` is `write` or `admin` can always 403 — a member with a lower role hits it. Document 403.
+- An operation whose `minimumRole` is `read` cannot 403 *that* way, because `read` is the floor of the `read < write < admin` ordering and anyone without access is concealed as 404 instead. It can still 403 through `PersonalApiKeysDisabledError` (a personal API key against a workspace whose organization disabled them) or `WorkspaceApiKeyAuthorizationError` (`workspaceApiKey: 'deny'`), and every v2 operation is reachable by a personal API key. **So in practice every workspace-scoped v2 operation documents 403**, and the reads that omitted it were wrong, not principled.
+
+Use the shared sets in `contracts/v2/openapi/shared.ts` — `RESOURCE_ERRORS`, `RESOURCE_CONFLICT_ERRORS`, `RESOURCE_MUTATION_ERRORS` — rather than assembling a per-operation list; all three already include `Forbidden`, and hand-assembled lists are how three knowledge reads and three upload operations quietly lost it.
+
+**HEAD is answered by the `GET` handler, not rejected.** Next aliases a missing `HEAD` export onto `GET` and drops the body when sending, so a route's `GET` legitimately runs with `request.method === 'HEAD'`. The builders' method guard accepts that pairing via `methodMatchesContract`; any other mismatch stays a hard error. Never hand-write a `HEAD` export to "fix" this.
 
 ## Rule 3 — a collection that returns `nextCursor` must accept `limit` + `cursor`, and must apply them
 

apps/docs/openapi-v2-files-audit.json

@@ -370,6 +370,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
@@ -468,6 +471,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
@@ -555,6 +561,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "404": {
             "$ref": "#/components/responses/NotFound"
           },

apps/docs/openapi-v2-knowledge.json

@@ -295,6 +295,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
@@ -672,6 +675,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
@@ -1252,6 +1258,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "404": {
             "$ref": "#/components/responses/NotFound"
           },

apps/sim/app/api/v2/skills/route.test.ts

@@ -90,7 +90,7 @@ const skill = {
   updatedAt: new Date('2026-01-02T00:00:00Z'),
 }
 
-function request(method: 'GET' | 'POST', url: string, body?: unknown) {
+function request(method: 'GET' | 'POST' | 'HEAD', url: string, body?: unknown) {
   return new NextRequest(`http://localhost:3000${url}`, {
     method,
     headers: {
@@ -179,6 +179,19 @@ describe('/api/v2/skills', () => {
     expect(mocks.list).not.toHaveBeenCalled()
   })
 
+  /**
+   * Next answers a HEAD by invoking this route's own GET export and dropping the
+   * body when it sends. The builder's method guard used to reject that, so every
+   * v2 read replied 500 to a plain HEAD — what health checkers and uptime
+   * monitors send.
+   */
+  it('serves HEAD through the GET handler instead of throwing', async () => {
+    const response = await GET(request('HEAD', `/api/v2/skills?workspaceId=${WORKSPACE_ID}`))
+
+    expect(response.status).toBe(200)
+    expect(mocks.list).toHaveBeenCalled()
+  })
+
   it('rejects a malformed cursor rather than silently restarting at page one', async () => {
     const response = await GET(
       request('GET', `/api/v2/skills?workspaceId=${WORKSPACE_ID}&cursor=not-a-cursor`)

apps/sim/lib/api/contracts/v2/openapi/files-audit.ts

@@ -26,13 +26,12 @@ import {
   ERROR_RESPONSES,
   type ErrorResponseId,
   RATE_LIMIT_HEADERS,
+  RESOURCE_CONFLICT_ERRORS,
   RESOURCE_ERRORS,
-  STANDARD_ERRORS,
   V2_API_KEY_SECURITY,
   V2_API_KEY_SECURITY_SCHEMES,
   V2_COMMON_HEADERS,
   V2_ERROR_SCHEMA,
-  VALIDATED_ERRORS,
   WORKSPACE_API_KEY_DENIED,
   WORKSPACE_API_KEY_DENIED_AS_NOT_FOUND,
   WORKSPACE_ERRORS,
@@ -213,7 +212,7 @@ const routes = [
       operationId: 'abortFileUpload',
       summary: 'Abort File Upload',
       description: 'Abort an active upload session and release provider-side multipart state.',
-      errors: [...VALIDATED_ERRORS, 'NotFound', 'Conflict'],
+      errors: [...RESOURCE_CONFLICT_ERRORS],
       success: { description: 'The aborted upload session.' },
     }),
     {
@@ -249,7 +248,7 @@ const routes = [
       operationId: 'createFileUploadPartUrls',
       summary: 'Create File Upload Part URLs',
       description: 'Create signed URLs for a bounded set of multipart upload part numbers.',
-      errors: [...STANDARD_ERRORS, 'BadRequest', 'NotFound', 'Conflict'],
+      errors: [...RESOURCE_CONFLICT_ERRORS],
       success: { description: 'Signed URLs for the requested upload parts.' },
     }),
     {
@@ -293,7 +292,7 @@ const routes = [
       summary: 'Complete File Upload',
       description:
         'Finalize uploaded bytes, verify provider state, and begin atomic workspace-file registration.',
-      errors: [...STANDARD_ERRORS, 'BadRequest', 'NotFound', 'Conflict'],
+      errors: [...RESOURCE_CONFLICT_ERRORS],
       success: { description: 'The completed or finalizing upload session.' },
     }),
     {
@@ -460,7 +459,7 @@ const routes = [
       operationId: 'listAuditLogs',
       summary: 'List Audit Logs',
       description: `List an organization audit trail with filters and opaque cursor pagination. Requires an Enterprise subscription and organization admin or owner access. ${WORKSPACE_API_KEY_DENIED}`,
-      errors: [...VALIDATED_ERRORS, 'Forbidden', 'NotFound'],
+      errors: [...RESOURCE_ERRORS],
       success: { description: 'A page of audit-log entries.' },
     }),
     {
@@ -485,7 +484,7 @@ const routes = [
       operationId: 'getAuditLog',
       summary: 'Get Audit Log',
       description: `Return one organization audit-log entry. Requires an Enterprise subscription and organization admin or owner access. ${WORKSPACE_API_KEY_DENIED}`,
-      errors: [...VALIDATED_ERRORS, 'Forbidden', 'NotFound'],
+      errors: [...RESOURCE_ERRORS],
       success: { description: 'The requested audit-log entry.' },
     }),
     {

apps/sim/lib/api/contracts/v2/openapi/knowledge.ts

@@ -31,7 +31,6 @@ import {
   V2_API_KEY_SECURITY_SCHEMES,
   V2_COMMON_HEADERS,
   V2_ERROR_SCHEMA,
-  VALIDATED_ERRORS,
   WORKSPACE_ERRORS,
 } from '@/lib/api/contracts/v2/openapi/shared'
 import {
@@ -116,7 +115,7 @@ const routes = [
       operationId: 'getKnowledgeBase',
       summary: 'Get Knowledge Base',
       description: `Retrieve a knowledge base by identifier. Inaccessible knowledge bases are reported as not found. ${FOLDER_TREE_TOO_LARGE}`,
-      errors: [...VALIDATED_ERRORS, 'NotFound', 'PayloadTooLarge'],
+      errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The requested knowledge base.' },
     }),
     {
@@ -241,7 +240,7 @@ const routes = [
       summary: 'List Documents',
       description:
         'List documents in a knowledge base with filename search, state filtering, sorting, and opaque cursor pagination.',
-      errors: [...VALIDATED_ERRORS, 'NotFound'],
+      errors: [...RESOURCE_ERRORS],
       success: { description: 'A page of knowledge documents.' },
     }),
     {
@@ -478,7 +477,7 @@ const routes = [
       operationId: 'getKnowledgeDocument',
       summary: 'Get Document',
       description: 'Retrieve document detail, processing state, and connector provenance.',
-      errors: [...VALIDATED_ERRORS, 'NotFound'],
+      errors: [...RESOURCE_ERRORS],
       success: { description: 'The requested knowledge document.' },
     }),
     {

apps/sim/lib/api/server/routes/definition.ts

@@ -64,3 +64,25 @@ export function requireBinaryRouteDefinition(
   }
   return { successStatus, successStatuses: [successStatus] }
 }
+
+/**
+ * Whether an incoming request's method is the one its contract declares.
+ *
+ * `HEAD` satisfies a `GET` contract because Next aliases a missing `HEAD`
+ * export straight to the `GET` handler
+ * (`auto-implement-methods.ts`: `methods.HEAD = handlers.GET`) and then drops
+ * the body when sending (`send-response.ts` skips the stream when
+ * `req.method === 'HEAD'`). So the handler legitimately runs with
+ * `request.method === 'HEAD'` against a `GET` contract, and rejecting that made
+ * every v2 read answer 500 to a plain `HEAD` — the request health checkers,
+ * uptime monitors, and link checkers send. RFC 9110 §9.3.2 makes HEAD identical
+ * to GET but for the body, which is exactly what running the GET path and
+ * letting the framework strip the body produces.
+ *
+ * Everything else stays a hard error: a handler exported under the wrong verb is
+ * a wiring mistake that should fail loudly rather than serve the wrong contract.
+ */
+export function methodMatchesContract(requestMethod: string, contractMethod: string): boolean {
+  if (requestMethod === contractMethod) return true
+  return requestMethod === 'HEAD' && contractMethod === 'GET'
+}

apps/sim/lib/api/server/routes/internal-binary-route.ts

@@ -1,7 +1,10 @@
 import type { Principal, SessionPrincipal } from '@sim/auth/principal'
 import type { NextRequest } from 'next/server'
 import { NextResponse } from 'next/server'
-import { requireBinaryRouteDefinition } from '@/lib/api/server/routes/definition'
+import {
+  methodMatchesContract,
+  requireBinaryRouteDefinition,
+} from '@/lib/api/server/routes/definition'
 import {
   type InternalErrorPolicy,
   InternalUnauthenticatedError,
@@ -72,7 +75,7 @@ export function defineInternalBinaryRoute<
 
   const wrapped = withRouteHandler<JsonRouteContext | undefined>(
     async (request, context) => {
-      if (request.method !== options.contract.method) {
+      if (!methodMatchesContract(request.method, options.contract.method)) {
         throw new Error(
           `Route received ${request.method} for ${options.contract.method} contract ${options.contract.path}`
         )