From 77d9595d8afe6684685a322a68adf9cd6210514b Mon Sep 17 00:00:00 2001
From: OpenRouter SDK Bot <sdk-bot@openrouter.ai>
Date: Wed, 29 Jul 2026 14:14:28 +0000
Subject: [PATCH] chore: update OpenAPI spec [sdk-bot]

---
 .speakeasy/in.openapi.yaml | 681 ++++++++++++++++++++++++++++++++-----
 1 file changed, 592 insertions(+), 89 deletions(-)

diff --git a/.speakeasy/in.openapi.yaml b/.speakeasy/in.openapi.yaml
index 3689f6cf..7bdba76f 100644
--- a/.speakeasy/in.openapi.yaml
+++ b/.speakeasy/in.openapi.yaml
@@ -1368,6 +1368,70 @@ components:
         - 'stderr'
         - 'type'
       type: 'object'
+    AnthropicFile:
+      description: 'A stored file in Anthropic''s Files API shape.'
+      example:
+        _shape: 'anthropic'
+        created_at: '2025-01-01T00:00:00Z'
+        downloadable: false
+        filename: 'document.pdf'
+        id: 'or_file_011CNha8iCJcU1wXNR6q4V8w'
+        mime_type: 'application/pdf'
+        size_bytes: 1024000
+        type: 'file'
+      properties:
+        _shape:
+          enum:
+            - 'anthropic'
+          type: 'string'
+        created_at:
+          type: 'string'
+        downloadable:
+          type: 'boolean'
+        filename:
+          type: 'string'
+        id:
+          type: 'string'
+        mime_type:
+          type: 'string'
+        size_bytes:
+          type: 'integer'
+        type:
+          enum:
+            - 'file'
+          type: 'string'
+      required:
+        - '_shape'
+        - 'id'
+        - 'type'
+        - 'filename'
+        - 'mime_type'
+        - 'size_bytes'
+        - 'created_at'
+        - 'downloadable'
+      type: 'object'
+    AnthropicFileDeleted:
+      description: 'Deletion result in Anthropic''s shape.'
+      example:
+        _shape: 'anthropic'
+        id: 'or_file_011CNha8iCJcU1wXNR6q4V8w'
+        type: 'file_deleted'
+      properties:
+        _shape:
+          enum:
+            - 'anthropic'
+          type: 'string'
+        id:
+          type: 'string'
+        type:
+          enum:
+            - 'file_deleted'
+          type: 'string'
+      required:
+        - '_shape'
+        - 'id'
+        - 'type'
+      type: 'object'
     AnthropicFileDocumentSource:
       example:
         file_id: 'or_file_011CNha8iCJcU1wXNR6q4V8w'
@@ -1383,6 +1447,40 @@ components:
         - 'type'
         - 'file_id'
       type: 'object'
+    AnthropicFileList:
+      description: 'A page of files in Anthropic''s shape.'
+      example:
+        _shape: 'anthropic'
+        data: []
+        first_id: null
+        has_more: false
+        last_id: null
+      properties:
+        _shape:
+          enum:
+            - 'anthropic'
+          type: 'string'
+        data:
+          items:
+            $ref: '#/components/schemas/AnthropicFile'
+          type: 'array'
+        first_id:
+          type:
+            - 'string'
+            - 'null'
+        has_more:
+          type: 'boolean'
+        last_id:
+          type:
+            - 'string'
+            - 'null'
+      required:
+        - '_shape'
+        - 'data'
+        - 'has_more'
+        - 'first_id'
+        - 'last_id'
+      type: 'object'
     AnthropicImageBlockParam:
       example:
         source:
@@ -7815,99 +7913,40 @@ components:
         - 'index'
       type: 'object'
     FileDeleteResponse:
-      description: 'Confirmation that a file was deleted.'
+      description: 'Confirmation that a file was deleted, in the negotiated shape.'
+      discriminator:
+        mapping:
+          anthropic: '#/components/schemas/AnthropicFileDeleted'
+          openai: '#/components/schemas/OpenAIFileDeleted'
+          openrouter: '#/components/schemas/OpenRouterFileDeleted'
+        propertyName: '_shape'
       example:
+        _shape: 'openrouter'
         id: 'or_file_011CNha8iCJcU1wXNR6q4V8w'
         type: 'file_deleted'
-      properties:
-        id:
-          type: 'string'
-        type:
-          enum:
-            - 'file_deleted'
-          type: 'string'
-      required:
-        - 'id'
-        - 'type'
-      type: 'object'
+      oneOf:
+        - $ref: '#/components/schemas/OpenRouterFileDeleted'
+        - $ref: '#/components/schemas/OpenAIFileDeleted'
+        - $ref: '#/components/schemas/AnthropicFileDeleted'
     FileListResponse:
-      description: 'A page of files belonging to the requesting workspace.'
+      description: 'A page of files, in the negotiated shape.'
+      discriminator:
+        mapping:
+          anthropic: '#/components/schemas/AnthropicFileList'
+          openai: '#/components/schemas/OpenAIFileList'
+          openrouter: '#/components/schemas/OpenRouterFileList'
+        propertyName: '_shape'
       example:
+        _shape: 'openrouter'
         cursor: null
-        data:
-          - created_at: '2025-01-01T00:00:00Z'
-            downloadable: false
-            filename: 'document.pdf'
-            id: 'or_file_011CNha8iCJcU1wXNR6q4V8w'
-            mime_type: 'application/pdf'
-            size_bytes: 1024000
-            type: 'file'
-        first_id: 'or_file_011CNha8iCJcU1wXNR6q4V8w'
+        data: []
+        first_id: null
         has_more: false
-        last_id: 'or_file_011CNha8iCJcU1wXNR6q4V8w'
-      properties:
-        cursor:
-          description: 'Opaque cursor for the next page; null when there are no more results.'
-          type:
-            - 'string'
-            - 'null'
-        data:
-          items:
-            $ref: '#/components/schemas/FileMetadata'
-          type: 'array'
-        first_id:
-          type:
-            - 'string'
-            - 'null'
-        has_more:
-          type: 'boolean'
-        last_id:
-          type:
-            - 'string'
-            - 'null'
-      required:
-        - 'data'
-        - 'has_more'
-        - 'first_id'
-        - 'last_id'
-        - 'cursor'
-      type: 'object'
-    FileMetadata:
-      description: 'Metadata describing a stored file.'
-      example:
-        created_at: '2025-01-01T00:00:00Z'
-        downloadable: false
-        filename: 'document.pdf'
-        id: 'or_file_011CNha8iCJcU1wXNR6q4V8w'
-        mime_type: 'application/pdf'
-        size_bytes: 1024000
-        type: 'file'
-      properties:
-        created_at:
-          type: 'string'
-        downloadable:
-          type: 'boolean'
-        filename:
-          type: 'string'
-        id:
-          type: 'string'
-        mime_type:
-          type: 'string'
-        size_bytes:
-          type: 'integer'
-        type:
-          enum:
-            - 'file'
-          type: 'string'
-      required:
-        - 'id'
-        - 'type'
-        - 'filename'
-        - 'mime_type'
-        - 'size_bytes'
-        - 'created_at'
-        - 'downloadable'
-      type: 'object'
+        last_id: null
+      oneOf:
+        - $ref: '#/components/schemas/OpenRouterFileList'
+        - $ref: '#/components/schemas/OpenAIFileList'
+        - $ref: '#/components/schemas/AnthropicFileList'
     FileParserPlugin:
       example:
         enabled: true
@@ -7946,6 +7985,34 @@ components:
         - 'file_id'
         - 'index'
       type: 'object'
+    FileProvider:
+      description: 'Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.'
+      enum:
+        - 'openai'
+        - 'anthropic'
+      example: 'openai'
+      type: 'string'
+    FileResponse:
+      description: 'A stored file. The shape is negotiated per request — see the endpoint description.'
+      discriminator:
+        mapping:
+          anthropic: '#/components/schemas/AnthropicFile'
+          openai: '#/components/schemas/OpenAIFile'
+          openrouter: '#/components/schemas/OpenRouterFile'
+        propertyName: '_shape'
+      example:
+        _shape: 'openrouter'
+        created_at: '2025-01-01T00:00:00Z'
+        downloadable: false
+        filename: 'document.pdf'
+        id: 'or_file_011CNha8iCJcU1wXNR6q4V8w'
+        mime_type: 'application/pdf'
+        size_bytes: 1024000
+        type: 'file'
+      oneOf:
+        - $ref: '#/components/schemas/OpenRouterFile'
+        - $ref: '#/components/schemas/OpenAIFile'
+        - $ref: '#/components/schemas/AnthropicFile'
     FileSearchServerTool:
       description: 'File search tool configuration'
       example:
@@ -16009,6 +16076,127 @@ components:
         - 'type'
         - 'config'
       type: 'object'
+    OpenAIFile:
+      description: 'A stored file in OpenAI''s Files API shape.'
+      example:
+        _shape: 'openai'
+        bytes: 1024000
+        created_at: 1735689600
+        filename: 'document.pdf'
+        id: 'or_file_011CNha8iCJcU1wXNR6q4V8w'
+        object: 'file'
+        purpose: 'user_data'
+        status: 'processed'
+      properties:
+        _shape:
+          enum:
+            - 'openai'
+          type: 'string'
+        bytes:
+          type: 'integer'
+        created_at:
+          type: 'integer'
+        filename:
+          type: 'string'
+        id:
+          type: 'string'
+        object:
+          enum:
+            - 'file'
+          type: 'string'
+        purpose:
+          enum:
+            - 'assistants'
+            - 'batch'
+            - 'fine-tune'
+            - 'vision'
+            - 'user_data'
+            - 'evals'
+            - 'assistants_output'
+            - 'batch_output'
+            - 'fine-tune-results'
+          type: 'string'
+        status:
+          enum:
+            - 'processed'
+          type: 'string'
+      required:
+        - '_shape'
+        - 'id'
+        - 'object'
+        - 'bytes'
+        - 'created_at'
+        - 'filename'
+        - 'purpose'
+        - 'status'
+      type: 'object'
+    OpenAIFileDeleted:
+      description: 'Deletion result in OpenAI''s shape.'
+      example:
+        _shape: 'openai'
+        deleted: true
+        id: 'or_file_011CNha8iCJcU1wXNR6q4V8w'
+        object: 'file'
+      properties:
+        _shape:
+          enum:
+            - 'openai'
+          type: 'string'
+        deleted:
+          const: true
+          type: 'boolean'
+        id:
+          type: 'string'
+        object:
+          enum:
+            - 'file'
+          type: 'string'
+      required:
+        - '_shape'
+        - 'id'
+        - 'object'
+        - 'deleted'
+      type: 'object'
+    OpenAIFileList:
+      description: 'A page of files in OpenAI''s shape.'
+      example:
+        _shape: 'openai'
+        data: []
+        first_id: null
+        has_more: false
+        last_id: null
+        object: 'list'
+      properties:
+        _shape:
+          enum:
+            - 'openai'
+          type: 'string'
+        data:
+          items:
+            $ref: '#/components/schemas/OpenAIFile'
+          type: 'array'
+        first_id:
+          type:
+            - 'string'
+            - 'null'
+        has_more:
+          type: 'boolean'
+        last_id:
+          type:
+            - 'string'
+            - 'null'
+        object:
+          enum:
+            - 'list'
+          type: 'string'
+      required:
+        - '_shape'
+        - 'object'
+        - 'data'
+        - 'has_more'
+        - 'first_id'
+        - 'last_id'
+      type: 'object'
     OpenAIResponseCustomToolCall:
       example:
         call_id: 'call-abc123'
@@ -16658,7 +16846,112 @@ components:
         token:
           type: 'string'
       type: 'object'
-    OpenRouterMetadata:
+    OpenRouterFile:
+      description: 'A stored file in the OpenRouter superset shape: Anthropic-shaped, plus OpenRouter-only fields.'
+      example:
+        _shape: 'openrouter'
+        created_at: '2025-01-01T00:00:00Z'
+        downloadable: false
+        filename: 'document.pdf'
+        id: 'or_file_011CNha8iCJcU1wXNR6q4V8w'
+        mime_type: 'application/pdf'
+        size_bytes: 1024000
+        type: 'file'
+      properties:
+        _shape:
+          enum:
+            - 'openrouter'
+          type: 'string'
+        created_at:
+          type: 'string'
+        downloadable:
+          type: 'boolean'
+        filename:
+          type: 'string'
+        id:
+          type: 'string'
+        mime_type:
+          type: 'string'
+        size_bytes:
+          type: 'integer'
+        type:
+          enum:
+            - 'file'
+          type: 'string'
+      required:
+        - '_shape'
+        - 'id'
+        - 'type'
+        - 'filename'
+        - 'mime_type'
+        - 'size_bytes'
+        - 'created_at'
+        - 'downloadable'
+      type: 'object'
+    OpenRouterFileDeleted:
+      description: 'Deletion result in the OpenRouter shape.'
+      example:
+        _shape: 'openrouter'
+        id: 'or_file_011CNha8iCJcU1wXNR6q4V8w'
+        type: 'file_deleted'
+      properties:
+        _shape:
+          enum:
+            - 'openrouter'
+          type: 'string'
+        id:
+          type: 'string'
+        type:
+          enum:
+            - 'file_deleted'
+          type: 'string'
+      required:
+        - '_shape'
+        - 'id'
+        - 'type'
+      type: 'object'
+    OpenRouterFileList:
+      description: 'A page of files in the OpenRouter shape.'
+      example:
+        _shape: 'openrouter'
+        cursor: null
+        data: []
+        first_id: null
+        has_more: false
+        last_id: null
+      properties:
+        _shape:
+          enum:
+            - 'openrouter'
+          type: 'string'
+        cursor:
+          description: 'Opaque cursor for the next page; null when there are no more results.'
+          type:
+            - 'string'
+            - 'null'
+        data:
+          items:
+            $ref: '#/components/schemas/OpenRouterFile'
+          type: 'array'
+        first_id:
+          type:
+            - 'string'
+            - 'null'
+        has_more:
+          type: 'boolean'
+        last_id:
+          type:
+            - 'string'
+            - 'null'
+      required:
+        - '_shape'
+        - 'data'
+        - 'has_more'
+        - 'first_id'
+        - 'last_id'
+        - 'cursor'
+      type: 'object'
+    OpenRouterMetadata:
       example:
         attempt: 1
         endpoints:
@@ -27704,6 +27997,48 @@ paths:
             example: 'a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7'
             format: 'uuid'
             type: 'string'
+        - description: 'Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.'
+          example: 'openai'
+          in: 'query'
+          name: 'provider'
+          required: false
+          schema:
+            $ref: '#/components/schemas/FileProvider'
+        - description: 'OpenAI-style forward cursor: the id to list after.'
+          in: 'query'
+          name: 'after'
+          required: false
+          schema:
+            description: 'OpenAI-style forward cursor: the id to list after.'
+            example: 'or_file_011CNha8iCJcU1wXNR6q4V8w'
+            type: 'string'
+        - description: 'Anthropic-style forward cursor: the id to list after.'
+          in: 'query'
+          name: 'after_id'
+          required: false
+          schema:
+            description: 'Anthropic-style forward cursor: the id to list after.'
+            example: 'or_file_011CNha8iCJcU1wXNR6q4V8w'
+            type: 'string'
+        - description: 'Anthropic-style reverse cursor. Not supported by OpenRouter storage.'
+          in: 'query'
+          name: 'before_id'
+          required: false
+          schema:
+            description: 'Anthropic-style reverse cursor. Not supported by OpenRouter storage.'
+            example: 'or_file_011CNha8iCJcU1wXNR6q4V8w'
+            type: 'string'
+        - description: 'Sort direction. Only `asc` is supported by OpenRouter storage.'
+          in: 'query'
+          name: 'order'
+          required: false
+          schema:
+            description: 'Sort direction. Only `asc` is supported by OpenRouter storage.'
+            enum:
+              - 'asc'
+              - 'desc'
+            example: 'asc'
+            type: 'string'
       responses:
         '200':
           content:
@@ -27744,6 +28079,16 @@ paths:
               schema:
                 $ref: '#/components/schemas/UnauthorizedResponse'
           description: 'Unauthorized - Authentication required or invalid credentials'
+        '403':
+          content:
+            application/json:
+              example:
+                error:
+                  code: 403
+                  message: 'Only management keys can perform this operation'
+              schema:
+                $ref: '#/components/schemas/ForbiddenResponse'
+          description: 'Forbidden - Authentication successful but insufficient permissions'
         '429':
           content:
             application/json:
@@ -27764,6 +28109,26 @@ paths:
               schema:
                 $ref: '#/components/schemas/InternalServerResponse'
           description: 'Internal Server Error - Unexpected server error'
+        '502':
+          content:
+            application/json:
+              example:
+                error:
+                  code: 502
+                  message: 'Provider returned error'
+              schema:
+                $ref: '#/components/schemas/BadGatewayResponse'
+          description: 'Bad Gateway - Provider/upstream API failure'
+        '503':
+          content:
+            application/json:
+              example:
+                error:
+                  code: 503
+                  message: 'Service temporarily unavailable'
+              schema:
+                $ref: '#/components/schemas/ServiceUnavailableResponse'
+          description: 'Service Unavailable - Service temporarily unavailable'
       summary: 'List files'
       tags:
         - 'Files'
@@ -27791,6 +28156,13 @@ paths:
             example: 'a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7'
             format: 'uuid'
             type: 'string'
+        - description: 'Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.'
+          example: 'openai'
+          in: 'query'
+          name: 'provider'
+          required: false
+          schema:
+            $ref: '#/components/schemas/FileProvider'
       requestBody:
         content:
           multipart/form-data:
@@ -27818,7 +28190,7 @@ paths:
                 size_bytes: 1024000
                 type: 'file'
               schema:
-                $ref: '#/components/schemas/FileMetadata'
+                $ref: '#/components/schemas/FileResponse'
           description: 'The uploaded file metadata.'
         '400':
           content:
@@ -27880,6 +28252,26 @@ paths:
               schema:
                 $ref: '#/components/schemas/InternalServerResponse'
           description: 'Internal Server Error - Unexpected server error'
+        '502':
+          content:
+            application/json:
+              example:
+                error:
+                  code: 502
+                  message: 'Provider returned error'
+              schema:
+                $ref: '#/components/schemas/BadGatewayResponse'
+          description: 'Bad Gateway - Provider/upstream API failure'
+        '503':
+          content:
+            application/json:
+              example:
+                error:
+                  code: 503
+                  message: 'Service temporarily unavailable'
+              schema:
+                $ref: '#/components/schemas/ServiceUnavailableResponse'
+          description: 'Service Unavailable - Service temporarily unavailable'
       summary: 'Upload a file'
       tags:
         - 'Files'
@@ -27905,6 +28297,13 @@ paths:
             example: 'a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7'
             format: 'uuid'
             type: 'string'
+        - description: 'Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.'
+          example: 'openai'
+          in: 'query'
+          name: 'provider'
+          required: false
+          schema:
+            $ref: '#/components/schemas/FileProvider'
       responses:
         '200':
           content:
@@ -27925,6 +28324,16 @@ paths:
               schema:
                 $ref: '#/components/schemas/UnauthorizedResponse'
           description: 'Unauthorized - Authentication required or invalid credentials'
+        '403':
+          content:
+            application/json:
+              example:
+                error:
+                  code: 403
+                  message: 'Only management keys can perform this operation'
+              schema:
+                $ref: '#/components/schemas/ForbiddenResponse'
+          description: 'Forbidden - Authentication successful but insufficient permissions'
         '404':
           content:
             application/json:
@@ -27955,6 +28364,26 @@ paths:
               schema:
                 $ref: '#/components/schemas/InternalServerResponse'
           description: 'Internal Server Error - Unexpected server error'
+        '502':
+          content:
+            application/json:
+              example:
+                error:
+                  code: 502
+                  message: 'Provider returned error'
+              schema:
+                $ref: '#/components/schemas/BadGatewayResponse'
+          description: 'Bad Gateway - Provider/upstream API failure'
+        '503':
+          content:
+            application/json:
+              example:
+                error:
+                  code: 503
+                  message: 'Service temporarily unavailable'
+              schema:
+                $ref: '#/components/schemas/ServiceUnavailableResponse'
+          description: 'Service Unavailable - Service temporarily unavailable'
       summary: 'Delete a file'
       tags:
         - 'Files'
@@ -27979,6 +28408,13 @@ paths:
             example: 'a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7'
             format: 'uuid'
             type: 'string'
+        - description: 'Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.'
+          example: 'openai'
+          in: 'query'
+          name: 'provider'
+          required: false
+          schema:
+            $ref: '#/components/schemas/FileProvider'
       responses:
         '200':
           content:
@@ -27992,7 +28428,7 @@ paths:
                 size_bytes: 1024000
                 type: 'file'
               schema:
-                $ref: '#/components/schemas/FileMetadata'
+                $ref: '#/components/schemas/FileResponse'
           description: 'The file metadata.'
         '401':
           content:
@@ -28004,6 +28440,16 @@ paths:
               schema:
                 $ref: '#/components/schemas/UnauthorizedResponse'
           description: 'Unauthorized - Authentication required or invalid credentials'
+        '403':
+          content:
+            application/json:
+              example:
+                error:
+                  code: 403
+                  message: 'Only management keys can perform this operation'
+              schema:
+                $ref: '#/components/schemas/ForbiddenResponse'
+          description: 'Forbidden - Authentication successful but insufficient permissions'
         '404':
           content:
             application/json:
@@ -28034,6 +28480,26 @@ paths:
               schema:
                 $ref: '#/components/schemas/InternalServerResponse'
           description: 'Internal Server Error - Unexpected server error'
+        '502':
+          content:
+            application/json:
+              example:
+                error:
+                  code: 502
+                  message: 'Provider returned error'
+              schema:
+                $ref: '#/components/schemas/BadGatewayResponse'
+          description: 'Bad Gateway - Provider/upstream API failure'
+        '503':
+          content:
+            application/json:
+              example:
+                error:
+                  code: 503
+                  message: 'Service temporarily unavailable'
+              schema:
+                $ref: '#/components/schemas/ServiceUnavailableResponse'
+          description: 'Service Unavailable - Service temporarily unavailable'
       summary: 'Get file metadata'
       tags:
         - 'Files'
@@ -28059,6 +28525,13 @@ paths:
             example: 'a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7'
             format: 'uuid'
             type: 'string'
+        - description: 'Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.'
+          example: 'openai'
+          in: 'query'
+          name: 'provider'
+          required: false
+          schema:
+            $ref: '#/components/schemas/FileProvider'
       responses:
         '200':
           content:
@@ -28088,6 +28561,16 @@ paths:
               schema:
                 $ref: '#/components/schemas/UnauthorizedResponse'
           description: 'Unauthorized - Authentication required or invalid credentials'
+        '403':
+          content:
+            application/json:
+              example:
+                error:
+                  code: 403
+                  message: 'Only management keys can perform this operation'
+              schema:
+                $ref: '#/components/schemas/ForbiddenResponse'
+          description: 'Forbidden - Authentication successful but insufficient permissions'
         '404':
           content:
             application/json:
@@ -28118,6 +28601,26 @@ paths:
               schema:
                 $ref: '#/components/schemas/InternalServerResponse'
           description: 'Internal Server Error - Unexpected server error'
+        '502':
+          content:
+            application/json:
+              example:
+                error:
+                  code: 502
+                  message: 'Provider returned error'
+              schema:
+                $ref: '#/components/schemas/BadGatewayResponse'
+          description: 'Bad Gateway - Provider/upstream API failure'
+        '503':
+          content:
+            application/json:
+              example:
+                error:
+                  code: 503
+                  message: 'Service temporarily unavailable'
+              schema:
+                $ref: '#/components/schemas/ServiceUnavailableResponse'
+          description: 'Service Unavailable - Service temporarily unavailable'
       summary: 'Download file content'
       tags:
         - 'Files'