Skip to content
Try for free
On this page

Files

List file versions

List the versions of a file, newest first by default. Each write that changes the bytes records one; identical rewrites do not. Collaborative edits, and repeated workflow writes by one author, fold into a version under ten minutes old and written in the last five. Renames and moves are not versions. Retention removes older versions by age and plan but keeps the newest ten, so numbers can have gaps. OAuth scope: `api:read`.

GET/api/v2/files/{fileId}/versions

List the versions of a file, newest first by default. Each write that changes the bytes records one; identical rewrites do not. Collaborative edits, and repeated workflow writes by one author, fold into a version under ten minutes old and written in the last five. Renames and moves are not versions. Retention removes older versions by age and plan but keeps the newest ten, so numbers can have gaps.

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.

Path parameters

fileIdstringRequired

File identifier.

minLength
1
maxLength
128
pattern
^[A-Za-z0-9_-]+$

Query parameters

workspaceIdstringRequired

Workspace that owns the file.

minLength
1
maxLength
128
sortBystring

Field used to sort the result.

default
version
enum
["version"]
sortOrderstring

Sort direction.

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

Maximum versions to return per page. Must be a whole number from 1 to 100. Defaults to 50.

default
50
minimum
1
maximum
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 file versions.

object

A cursor-paginated page of file versions.

2 fields
dataarrayRequired

Items in the current page.

Schema details
Array itemobject

One recorded version of the content of a workspace file.

11 fields
fileIdstringRequired

File this version belongs to.

versionintegerRequired

Version number, increasing by one per recorded version. Numbers are never reused, so a gap means an older version was removed by retention or deleted.

minimum
1
maximum
2147483647
isCurrentbooleanRequired

Whether this version holds the current content of the file.

sizeintegerRequired

Size in bytes of the stored content of this version.

minimum
0
maximum
9007199254740991
contentTypestringRequired

MIME type of the stored content of this version.

sourcestringRequired

What wrote this version: upload (the original upload), user (a save in the Sim editor), api (an API, CLI, or MCP write), copilot (Sim, the agent), workflow (a workflow run), collab (collaborative editing), revert (a revert to an earlier version), or unknown (content written before version history existed, or by a writer with no source of its own).

enum
["upload","user","api","copilot","workflow","collab","revert","unknown"]
authorsarrayRequired

Users who wrote this version, in order of first contribution. Empty for actorless writers such as workspace API keys. A collaborative version lists every editor in its window.

Schema details
Array itemobject
2 fields
idstringRequired

User identifier.

emailvalueRequired

Current email address of the user, or null when the account no longer exists.

Schema details

Any of

Option 1string
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])?)*$
Option 2null

Additional properties are not allowed.

restoredFromVersionvalueRequired

For a revert version, the version whose content it restored; otherwise null.

Schema details

Any of

Option 1integer
minimum
1
maximum
2147483647
Option 2null
createdAtstringRequired

ISO 8601 timestamp when this content became current.

format
date-time
updatedAtstringRequired

ISO 8601 timestamp of the last write folded into this version. Equals createdAt unless edits were coalesced into it.

format
date-time
supersededAtvalueRequired

ISO 8601 timestamp when a newer version replaced this one, or null for the current version. Retention ages versions from this time.

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": [
    {
      "fileId": "wf_V1StGXR8z5jdHi6BmyT91",
      "version": 3,
      "isCurrent": true,
      "size": 1024,
      "contentType": "text/csv",
      "source": "api",
      "authors": [
        {
          "id": "usr_4kJ9mN2pQ7rS",
          "email": "jane@example.com"
        }
      ],
      "restoredFromVersion": null,
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-15T10:30:00Z",
      "supersededAt": 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