feat(api): add file metadata endpoint

TheodoreSpeaks · TheodoreSpeaks · commit 98aa51f56c2f · 2026-08-04T18:27:51.000-07:00
diff --git a/apps/docs/openapi-v2-files-audit.json b/apps/docs/openapi-v2-files-audit.json
@@ -680,6 +680,85 @@
         }
       }
     },
+    "/api/v2/files/{fileId}/metadata": {
+      "get": {
+        "operationId": "getFile",
+        "summary": "Get File Metadata",
+        "description": "Return one workspace file's metadata without downloading its content. Lookups are workspace-scoped: a file that belongs to another workspace returns `404`.",
+        "tags": ["Files"],
+        "x-codeSamples": [
+          {
+            "id": "curl",
+            "label": "cURL",
+            "lang": "bash",
+            "source": "curl -X GET \\\n  \"https://www.sim.ai/api/v2/files/{fileId}/metadata?workspaceId=YOUR_WORKSPACE_ID\" \\\n  -H \"X-API-Key: YOUR_API_KEY\""
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/FileIdPath"
+          },
+          {
+            "$ref": "#/components/parameters/WorkspaceIdQuery"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The file metadata.",
+            "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": "data.csv",
+                    "size": 1024,
+                    "type": "text/csv",
+                    "key": "workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/1709571234-xyz-data.csv",
+                    "folderId": "fold_9Kq2mZ7pR4tLxWc0Ye3Nu",
+                    "folderPath": "Reports/Q1",
+                    "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"
+          },
+          "429": {
+            "$ref": "#/components/responses/RateLimited"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalError"
+          }
+        }
+      }
+    },
     "/api/v2/audit-logs": {
       "get": {
         "operationId": "listAuditLogs",
diff --git a/apps/sim/app/api/v2/files/[fileId]/metadata/route.test.ts b/apps/sim/app/api/v2/files/[fileId]/metadata/route.test.ts
@@ -0,0 +1,127 @@
+/**
+ * @vitest-environment node
+ */
+import { NextRequest } from 'next/server'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockCheckRateLimit, mockResolveWorkspaceAccess, mockGetWorkspaceFile } = vi.hoisted(() => ({
+  mockCheckRateLimit: vi.fn(),
+  mockResolveWorkspaceAccess: vi.fn(),
+  mockGetWorkspaceFile: vi.fn(),
+}))
+
+vi.mock('@/app/api/v1/middleware', () => ({
+  checkRateLimit: mockCheckRateLimit,
+  resolveWorkspaceAccess: mockResolveWorkspaceAccess,
+}))
+
+vi.mock('@/app/api/v2/lib/gate', () => ({
+  v2ApiGateError: vi.fn().mockResolvedValue(null),
+}))
+
+vi.mock('@/lib/uploads/contexts/workspace', () => ({
+  getWorkspaceFile: mockGetWorkspaceFile,
+}))
+
+import { GET } from '@/app/api/v2/files/[fileId]/metadata/route'
+
+const WORKSPACE_ID = 'workspace-1'
+const FILE_ID = 'wf_1'
+
+const RATE_LIMIT_OK = {
+  allowed: true,
+  userId: 'user-1',
+  keyType: 'workspace',
+  limit: 100,
+  remaining: 99,
+  resetAt: new Date('2024-01-01T01:00:00Z'),
+}
+
+const ctx = { params: Promise.resolve({ fileId: FILE_ID }) }
+
+function buildRecord() {
+  return {
+    id: FILE_ID,
+    workspaceId: WORKSPACE_ID,
+    name: 'data.csv',
+    key: 'workspace/ws/1-x-data.csv',
+    path: '/api/files/serve/x',
+    size: 1024,
+    type: 'text/csv',
+    uploadedBy: 'user-1',
+    folderId: null,
+    folderPath: null,
+    uploadedAt: new Date('2024-01-01T00:00:00Z'),
+    updatedAt: new Date('2024-01-02T00:00:00Z'),
+  }
+}
+
+const callGet = (query: string) =>
+  GET(new NextRequest(`http://localhost:3000/api/v2/files/${FILE_ID}/metadata?${query}`), ctx)
+
+describe('GET /api/v2/files/[fileId]/metadata', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockCheckRateLimit.mockResolvedValue(RATE_LIMIT_OK)
+    mockResolveWorkspaceAccess.mockResolvedValue(null)
+    mockGetWorkspaceFile.mockResolvedValue(buildRecord())
+  })
+
+  it('400s when workspaceId is missing', async () => {
+    const response = await callGet('')
+
+    expect(response.status).toBe(400)
+    expect(mockGetWorkspaceFile).not.toHaveBeenCalled()
+  })
+
+  it('surfaces an access-denied failure', async () => {
+    mockResolveWorkspaceAccess.mockResolvedValue({
+      status: 403,
+      code: 'FORBIDDEN',
+      message: 'Access denied',
+    })
+
+    const response = await callGet(`workspaceId=${WORKSPACE_ID}`)
+
+    expect(response.status).toBe(403)
+    expect(mockGetWorkspaceFile).not.toHaveBeenCalled()
+  })
+
+  it('404s when the workspace-scoped file does not exist', async () => {
+    mockGetWorkspaceFile.mockResolvedValue(null)
+
+    const response = await callGet(`workspaceId=${WORKSPACE_ID}`)
+
+    expect(response.status).toBe(404)
+    expect((await response.json()).error.code).toBe('NOT_FOUND')
+  })
+
+  it('returns the public metadata projection without loading content', async () => {
+    const response = await callGet(`workspaceId=${WORKSPACE_ID}`)
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({
+      data: {
+        id: FILE_ID,
+        name: 'data.csv',
+        size: 1024,
+        type: 'text/csv',
+        key: 'workspace/ws/1-x-data.csv',
+        folderId: null,
+        folderPath: null,
+        uploadedBy: 'user-1',
+        uploadedAt: '2024-01-01T00:00:00.000Z',
+        updatedAt: '2024-01-02T00:00:00.000Z',
+      },
+    })
+    expect(mockResolveWorkspaceAccess).toHaveBeenCalledWith(
+      expect.anything(),
+      'user-1',
+      WORKSPACE_ID,
+      'read'
+    )
+    expect(mockGetWorkspaceFile).toHaveBeenCalledWith(WORKSPACE_ID, FILE_ID, {
+      throwOnError: true,
+    })
+  })
+})
diff --git a/apps/sim/app/api/v2/files/[fileId]/metadata/route.ts b/apps/sim/app/api/v2/files/[fileId]/metadata/route.ts
@@ -0,0 +1,61 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import type { NextRequest } from 'next/server'
+import { v2GetFileContract } from '@/lib/api/contracts/v2/files'
+import { parseRequest } from '@/lib/api/server'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { getWorkspaceFile } from '@/lib/uploads/contexts/workspace'
+import { checkRateLimit, resolveWorkspaceAccess } from '@/app/api/v1/middleware'
+import { toV2File } from '@/app/api/v2/files/utils'
+import { v2ApiGateError } from '@/app/api/v2/lib/gate'
+import {
+  v2Data,
+  v2Error,
+  v2RateLimitError,
+  v2ValidationError,
+  v2WorkspaceAccessError,
+} from '@/app/api/v2/lib/response'
+
+const logger = createLogger('V2FileMetadataAPI')
+
+export const dynamic = 'force-dynamic'
+export const revalidate = 0
+
+interface FileMetadataRouteParams {
+  params: Promise<{ fileId: string }>
+}
+
+/** GET /api/v2/files/[fileId]/metadata — Return file metadata without downloading its bytes. */
+export const GET = withRouteHandler(
+  async (request: NextRequest, context: FileMetadataRouteParams) => {
+    try {
+      const rateLimit = await checkRateLimit(request, 'file-detail')
+      if (!rateLimit.allowed) return v2RateLimitError(rateLimit)
+
+      const userId = rateLimit.userId!
+      const gate = await v2ApiGateError(userId)
+      if (gate) return gate
+
+      const parsed = await parseRequest(v2GetFileContract, request, context, {
+        validationErrorResponse: v2ValidationError,
+      })
+      if (!parsed.success) return parsed.response
+
+      const { fileId } = parsed.data.params
+      const { workspaceId } = parsed.data.query
+
+      const access = await resolveWorkspaceAccess(rateLimit, userId, workspaceId, 'read')
+      if (access) return v2WorkspaceAccessError(access)
+
+      const file = await getWorkspaceFile(workspaceId, fileId, { throwOnError: true })
+      if (!file) return v2Error('NOT_FOUND', 'File not found')
+
+      return v2Data(toV2File(file), { rateLimit })
+    } catch (error) {
+      logger.error('Error fetching file metadata', {
+        error: getErrorMessage(error, 'Unknown error'),
+      })
+      return v2Error('INTERNAL_ERROR', 'Internal server error')
+    }
+  }
+)
diff --git a/apps/sim/lib/api/contracts/v2/files.ts b/apps/sim/lib/api/contracts/v2/files.ts
@@ -424,6 +424,17 @@ export const v2DownloadFileContract = defineRouteContract({
   },
 })
 
+export const v2GetFileContract = defineRouteContract({
+  method: 'GET',
+  path: '/api/v2/files/[fileId]/metadata',
+  params: v2FileParamsSchema,
+  query: v2FileWorkspaceQuerySchema,
+  response: {
+    mode: 'json',
+    schema: v2DataResponse(v2FileSchema),
+  },
+})
+
 export const v2RenameFileContract = defineRouteContract({
   method: 'PATCH',
   path: '/api/v2/files/[fileId]',
