List Files

List active workspace files with folder filtering, search, sorting, and cursor pagination. Use scope=archived to find files available for restoration. Workspace folder trees exceeding 10,000 folders return 413.

OAuth scope: api:read.

GET/api/v2/files

Authorization

X-API-Key<token>

Your Sim API key, personal or workspace-scoped. Generate one under Settings, then API Keys. Operations that reject workspace keys say so in their own description.

In: header

Query Parameters

workspaceId*string

Workspace whose files should be listed.

Length1 <= length <= 128
folderPath?Folder path input

Restrict files to this folder, including subfolders when recursive is true. Unknown folder paths contribute no matches.

Lengthlength <= 4096
recursive?string

Include subfolders in the folder filter. Defaults to true when searching and false otherwise. Ignored without a folder filter.

Value in"true" | "1" | "yes" | "on" | "y" | "enabled" | "false" | "0" | "no" | "off" | "n" | "disabled"
scope?string

Which lifecycle set to list: active (default) for live files, archived for files a delete soft-deleted. folderPath resolves against active folders only, so pairing it with scope=archived returns an empty page when the containing folder was archived too.

Default"active"
Value in"active" | "archived"
search?string

Case-insensitive substring match against the file name.

Length1 <= length <= 200
sortBy?string

Field used to sort the result. Sorting by name is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.

Default"uploadedAt"
Value in"name" | "size" | "uploadedAt" | "updatedAt"
sortOrder?string

Sort direction.

Default"asc"
Value in"asc" | "desc"
limit?integer

Maximum files per page. Values outside 1–1000 are truncated and clamped into that range rather than rejected. Defaults to 100.

Default100
cursor?string

Opaque cursor from the previous page. Send it back with the same sort and filters; only limit may change. Change anything else and pagination must restart without a cursor.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://www.sim.ai/api/v2/files?workspaceId=string" \  -H "X-API-Key: YOUR_API_KEY"
{
  "data": [
    {
      "id": "wf_V1StGXR8z5jdHi6BmyT91",
      "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/files/wf_V1StGXR8z5jdHi6BmyT91",
      "name": "data.csv",
      "size": 1024,
      "type": "text/csv",
      "key": "workspace/example/data.csv",
      "folderPath": "/Engineering",
      "uploadedByEmail": "jane@example.com",
      "uploadedAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-15T10:30:00Z",
      "deletedAt": null
    }
  ],
  "nextCursor": null
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  }
}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient workspace permissions",
    "details": {
      "code": "INSUFFICIENT_WORKSPACE_ROLE"
    }
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found"
  }
}
{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Request body is too large"
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": {
      "retryAfter": "2026-01-01T00:00:30.000Z"
    }
  }
}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}
{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}
GETGet File UploadGETList Folders