Skip to content
Try for free
On this page

Files

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

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.

Authentication

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:read

OAuth flows
json
{
  "authorizationCode": {
    "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
    "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "scopes": {
      "api:read": "Read your workspaces, workflows, files, tables, and logs",
      "api:write": "Read, create, change, run, and delete resources in your workspaces",
      "offline_access": "Stay signed in without asking again"
    }
  }
}

OAuth scope: api:read.

Query parameters

workspaceIdstringRequired

Workspace whose files should be listed.

minLength
1
maxLength
128
folderPathstring

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

maxLength
4096
recursivestring

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

enum
["true","1","yes","on","y","enabled","false","0","no","off","n","disabled"]
scopestring

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
enum
["active","archived"]
searchstring

Case-insensitive substring match against the file name.

minLength
1
maxLength
200
sortBystring

Field used to sort the result. Do not rely on case-insensitive ordering when sorting by name.

default
uploadedAt
enum
["name","size","uploadedAt","updatedAt"]
sortOrderstring

Sort direction.

default
asc
enum
["asc","desc"]
limitinteger

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

default
100
cursorstring

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.

minLength
1

Responses

200

A page of workspace files.

object

A cursor-paginated page of workspace files.

2 fields
dataarrayRequired

Items in the current page.

Schema details
Array itemobject

A workspace file exposed by the public v2 API.

11 fields
idstringRequired

Unique file identifier.

webUrlstringRequired

Canonical absolute URL for opening this resource in the Sim web application.

format
uri
namestringRequired

Original file name.

sizenumberRequired

Size in bytes of the stored file. For a generated document (docx, pptx, pdf, xlsx) this is the generation source, not the rendered document, so it does not predict how many bytes downloading the file returns.

minimum
0
typestringRequired

MIME type of the stored file. For a generated document (docx, pptx, pdf, xlsx) this is the generation source type, not the rendered document type a download serves.

keystringRequired

Storage key for the file.

folderPathstringRequired

Canonical containing-folder path. / is the workspace root.

maxLength
4096
uploadedByEmailstringRequired

Current email address of the uploader.

format
email
pattern
^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$
uploadedAtstringRequired

ISO 8601 timestamp when the file was uploaded.

format
date-time
updatedAtstringRequired

ISO 8601 timestamp of the last content or metadata write.

format
date-time
deletedAtvalueRequired

ISO 8601 timestamp when the file was archived by deleting it, or null while the file is active. Only an archived-scope file list returns files with a non-null value.

format
date-time
Schema details

Any of

Option 1string
Option 2null

Additional properties are not allowed.

nextCursorvalueRequired

Opaque cursor for the next page. Send it back as cursor; null means there are no more pages. Do not construct a cursor yourself.

Schema details

Any of

Option 1string
Option 2null

Additional properties are not allowed.

Response example 1

json
{
  "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
}

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Was this helpful?
Suggest an edit