feat(files): add authored file creation

Author: TheodoreSpeaks

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

@@ -168,13 +168,125 @@
             "$ref": "#/components/responses/InternalError"
           }
         }
+      },
+      "post": {
+        "operationId": "createFile",
+        "summary": "Create File",
+        "description": "Create an authored workspace file, either empty or with initial inline content. Use this endpoint for files whose bytes are already available as UTF-8 text or base64 and are at most 50 MiB after decoding. Use the upload-session endpoints for streamed or larger files. A live file with the same name in the same folder is rejected with `409`.",
+        "tags": ["Files"],
+        "x-codeSamples": [
+          {
+            "id": "curl",
+            "label": "cURL",
+            "lang": "bash",
+            "source": "curl -X POST \\\n  \"https://www.sim.ai/api/v2/files\" \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"workspaceId\": \"YOUR_WORKSPACE_ID\", \"name\": \"notes.md\"}'"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["workspaceId", "name"],
+                "properties": {
+                  "workspaceId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Workspace in which to create the file."
+                  },
+                  "name": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 255,
+                    "description": "File name, including its extension. Path separators and dot segments are rejected."
+                  },
+                  "contentType": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 255,
+                    "description": "MIME type. When omitted, it is inferred from the file extension."
+                  },
+                  "folderId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 128,
+                    "description": "Destination folder. Omit to create the file at the workspace root."
+                  },
+                  "content": {
+                    "type": "string",
+                    "maxLength": 70000000,
+                    "default": "",
+                    "description": "Initial file content. Omit or send an empty string to create a zero-byte file."
+                  },
+                  "encoding": {
+                    "type": "string",
+                    "enum": ["utf-8", "base64"],
+                    "default": "utf-8",
+                    "description": "Encoding of `content`."
+                  }
+                }
+              },
+              "example": {
+                "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                "name": "notes.md"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "The created file.",
+            "headers": {
+              "X-RateLimit-Limit": {
+                "$ref": "#/components/headers/X-RateLimit-Limit"
+              },
+              "X-RateLimit-Remaining": {
+                "$ref": "#/components/headers/X-RateLimit-Remaining"
+              },
+              "X-RateLimit-Reset": {
+                "$ref": "#/components/headers/X-RateLimit-Reset"
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/V2FileResponse"
+                },
+                "example": {
+                  "data": {
+                    "id": "wf_V1StGXR8z5jdHi6BmyT91",
+                    "name": "notes.md",
+                    "size": 0,
+                    "type": "text/markdown",
+                    "key": "workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/1709571234-xyz-notes.md",
+                    "folderId": null,
+                    "folderPath": null,
+                    "uploadedBy": "user_abc123",
+                    "uploadedAt": "2026-01-15T10:30:00Z",
+                    "updatedAt": "2026-01-15T10:30:00Z"
+                  }
+                }
+              }
+            }
+          },
+          "400": { "$ref": "#/components/responses/BadRequest" },
+          "401": { "$ref": "#/components/responses/Unauthorized" },
+          "403": { "$ref": "#/components/responses/Forbidden" },
+          "404": { "$ref": "#/components/responses/NotFound" },
+          "409": { "$ref": "#/components/responses/Conflict" },
+          "413": { "$ref": "#/components/responses/PayloadTooLarge" },
+          "429": { "$ref": "#/components/responses/RateLimited" },
+          "500": { "$ref": "#/components/responses/InternalError" }
+        }
       }
     },
     "/api/v2/files/uploads": {
       "post": {
         "operationId": "createFileUpload",
         "summary": "Create File Upload",
-        "description": "Create an upload session and signed control token. Files up to and including 50 MiB receive a single signed PUT URL; larger files receive multipart transfer instructions. The maximum file size is 5 GB.",
+        "description": "Create an upload session and signed control token. Empty files and files up to and including 50 MiB receive a single signed PUT URL; larger files receive multipart transfer instructions. The maximum file size is 5 GB.",
         "tags": ["Files"],
         "requestBody": {
           "required": true,

apps/sim/app/api/files/uploads/route.test.ts

@@ -143,6 +143,46 @@ describe('/api/files/uploads', () => {
     expect(body.data.session).not.toHaveProperty('transfer')
   })
 
+  it('creates a PUT session for an empty workspace file', async () => {
+    mockCreateUploadSession.mockResolvedValue({
+      ...session({
+        workspaceId: 'workspace-1',
+        purpose: 'workspace_file',
+        storageContext: 'workspace',
+        storageKey: 'workspace/workspace-1/empty.md',
+        fileName: 'empty.md',
+        contentType: 'text/markdown',
+        fileSize: 0,
+      }),
+      transfer: {
+        method: 'put',
+        url: 'https://storage.example.com/upload',
+        headers: { 'Content-Type': 'text/markdown' },
+      },
+    })
+    const request = new NextRequest('http://localhost/api/files/uploads', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        purpose: 'workspace_file',
+        workspaceId: 'workspace-1',
+        name: 'empty.md',
+        contentType: 'text/markdown',
+        size: 0,
+      }),
+    })
+
+    const response = await createUpload(request)
+
+    expect(response.status).toBe(201)
+    expect(mockCreateUploadSession).toHaveBeenCalledWith(
+      expect.objectContaining({ purpose: 'workspace_file', fileSize: 0 })
+    )
+    await expect(response.json()).resolves.toMatchObject({
+      data: { session: { purpose: 'workspace_file', size: 0 } },
+    })
+  })
+
   it('preserves the 5 GiB direct-to-storage limit for mothership attachments', async () => {
     mockCreateUploadSession.mockResolvedValue({
       ...session({

apps/sim/app/api/v2/files/[fileId]/content/route.test.ts

@@ -22,6 +22,7 @@ vi.mock('@/app/api/v2/lib/gate', () => ({
 }))
 
 vi.mock('@/lib/workspace-files/orchestration', () => ({
+  MAX_WORKSPACE_FILE_INLINE_BODY_BYTES: 70 * 1024 * 1024,
   performUpdateWorkspaceFileContent: mockPerformUpdateContent,
 }))
 
@@ -62,12 +63,15 @@ const RECORD = {
   updatedAt: new Date('2024-01-03T00:00:00Z'),
 }
 
-const callPut = (body: unknown) =>
+const callPut = (body: unknown, contentLength?: number) =>
   PUT(
     new NextRequest(`http://localhost:3000/api/v2/files/${FILE_ID}/content`, {
       method: 'PUT',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(body),
+      headers: {
+        'Content-Type': 'application/json',
+        ...(contentLength === undefined ? {} : { 'Content-Length': String(contentLength) }),
+      },
+      body: typeof body === 'string' ? body : JSON.stringify(body),
     }),
     { params: Promise.resolve({ fileId: FILE_ID }) }
   )
@@ -104,6 +108,45 @@ describe('PUT /api/v2/files/[fileId]/content', () => {
     expect(mockPerformUpdateContent).not.toHaveBeenCalled()
   })
 
+  it('400s malformed base64 in the v2 error envelope', async () => {
+    const res = await callPut({ workspaceId: WS, content: 'not-base64!', encoding: 'base64' })
+    const body = await res.json()
+
+    expect(res.status).toBe(400)
+    expect(body.error.code).toBe('BAD_REQUEST')
+    expect(body.error.message).toBe('content must be valid base64')
+    expect(mockPerformUpdateContent).not.toHaveBeenCalled()
+  })
+
+  it('accepts empty base64 as a zero-byte replacement', async () => {
+    const res = await callPut({ workspaceId: WS, content: '', encoding: 'base64' })
+
+    expect(res.status).toBe(200)
+    expect(mockPerformUpdateContent).toHaveBeenCalledWith(
+      expect.objectContaining({ content: '', encoding: 'base64' })
+    )
+  })
+
+  it('allows JSON bodies above the default 50 MiB cap for base64 expansion', async () => {
+    const res = await callPut(
+      { workspaceId: WS, content: 'TQ==', encoding: 'base64' },
+      60 * 1024 * 1024
+    )
+
+    expect(res.status).toBe(200)
+    expect(mockPerformUpdateContent).toHaveBeenCalled()
+  })
+
+  it('returns an oversized JSON body in the canonical v2 413 envelope', async () => {
+    const res = await callPut({ workspaceId: WS, content: '' }, 70 * 1024 * 1024 + 1)
+
+    expect(res.status).toBe(413)
+    await expect(res.json()).resolves.toEqual({
+      error: { code: 'PAYLOAD_TOO_LARGE', message: 'Request body is too large' },
+    })
+    expect(mockPerformUpdateContent).not.toHaveBeenCalled()
+  })
+
   it('surfaces an access-denied failure in the v2 error envelope', async () => {
     mockResolveWorkspaceAccess.mockResolvedValue({
       status: 403,

apps/sim/app/api/v2/files/[fileId]/content/route.ts

@@ -5,7 +5,10 @@ import { v2UpdateFileContentContract } from '@/lib/api/contracts/v2/files'
 import { parseRequest } from '@/lib/api/server'
 import { messageForOrchestrationError } from '@/lib/core/orchestration/types'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
-import { performUpdateWorkspaceFileContent } from '@/lib/workspace-files/orchestration'
+import {
+  MAX_WORKSPACE_FILE_INLINE_BODY_BYTES,
+  performUpdateWorkspaceFileContent,
+} from '@/lib/workspace-files/orchestration'
 import { checkRateLimit, resolveWorkspaceAccess } from '@/app/api/v1/middleware'
 import { toV2File } from '@/app/api/v2/files/utils'
 import { v2ApiGateError } from '@/app/api/v2/lib/gate'
@@ -46,9 +49,15 @@ export const PUT = withRouteHandler(async (request: NextRequest, context: FileRo
     if (gate) return gate
 
     const parsed = await parseRequest(v2UpdateFileContentContract, request, context, {
+      invalidJsonResponse: () => v2Error('BAD_REQUEST', 'Request body must be valid JSON'),
+      maxBodyBytes: MAX_WORKSPACE_FILE_INLINE_BODY_BYTES,
       validationErrorResponse: v2ValidationError,
     })
-    if (!parsed.success) return parsed.response
+    if (!parsed.success) {
+      return parsed.response.status === 413
+        ? v2Error('PAYLOAD_TOO_LARGE', 'Request body is too large')
+        : parsed.response
+    }
 
     const { fileId } = parsed.data.params
     const { workspaceId, content, encoding } = parsed.data.body