Skip to content
Try for free
On this page

Files

Revert file version

Make the content of a version current again by writing it as a new `revert` version, so the revert can itself be reverted. Open editors receive the change. Reverting to the current version writes nothing and returns `reverted: false`. A concurrent write, or an `expectedCurrentVersion` that is no longer current, returns `409`; a version above 100 MiB returns `413`. OAuth scope: `api:write`.

POST/api/v2/files/{fileId}/versions/{version}/revert

Make the content of a version current again by writing it as a new revert version, so the revert can itself be reverted. Open editors receive the change. Reverting to the current version writes nothing and returns reverted: false. A concurrent write, or an expectedCurrentVersion that is no longer current, returns 409; a version above 100 MiB returns 413.

OAuth scope: api:write.

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:write

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:write.

Path parameters

fileIdstringRequired

File identifier.

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

Version number.

maximum
2147483647
exclusiveMinimum
0

Request body

Required

Workspace scope and an optional current-version precondition.

object

Workspace scope and an optional current-version precondition.

3 fields
workspaceIdstringRequired

Workspace that owns the file.

minLength
1
maxLength
128
expectedCurrentVersioninteger

Revert only while this is still the current version; otherwise the request fails with 409. Omit to revert whatever is current. Collaborative edits and repeated workflow writes that fold into the current version keep its number, so prefer expectedRevision to guard content.

minimum
1
maximum
2147483647
expectedRevisionstring

Revert only while the file still holds the content this revision names, as returned by Get file metadata or an earlier write; otherwise the request fails with 409. Unlike a version number, it also catches edits that folded into the current version.

minLength
1

Additional properties are not allowed.

Request example 1

json
{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "expectedCurrentVersion": 4
}

Responses

200

The file and its current version after the revert.

object

The file and its current version after the revert.

1 field
dataobjectRequired

Response data.

4 fields
revertedbooleanRequired

False when the requested version was already current, in which case nothing was written.

fileobjectRequired

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.

versionobjectRequired

The current version of the file after the revert: a new revert version; the requested version when it was already current; or the unchanged current version when its content already matched the requested one.

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.

revisionstring

Opaque token for the content the file holds after the revert — the one it just wrote, or the unchanged current content when reverted is false. Send it back as expectedRevision on the next write.

Additional properties are not allowed.

Additional properties are not allowed.

Response example 1

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

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