Skip to content
Try for free
On this page

Files

Get file metadata

Get file metadata, its public-share configuration, and the version number of its current content. The `share` field is null when the file has never been shared. `currentVersion` identifies the content in List file versions and is the precondition Revert file version accepts. OAuth scope: `api:read`.

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

Get file metadata, its public-share configuration, and the version number of its current content. The share field is null when the file has never been shared. currentVersion identifies the content in List file versions and is the precondition Revert file version accepts.

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, or the VFS path of a live file: files/<folder>/<name>. Pass the id when two files in a folder have names that display alike.

minLength
1
maxLength
4096

Query parameters

workspaceIdstringRequired

Workspace that owns the file.

minLength
1
maxLength
128
scopestring

Which lifecycle set to read from: active (default) resolves live files only and returns 404 for a file a delete soft-deleted; archived also resolves soft-deleted files, so metadata stays readable before the file is restored. Authorization is identical for both.

default
active
enum
["active","archived"]

Responses

200

File metadata and public-share state.

object

File metadata enriched with its current nullable public-share state.

1 field
dataobjectRequired

Response data.

14 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
sharevalueRequired

Current public-share state, or null when the file has never been shared.

Schema details

Any of

Option 1object

Public-safe share configuration for a file.

9 fields
idstringRequired

Unique share identifier.

tokenstringRequired

Server-generated token embedded in the public share URL.

urlstringRequired

Public share URL.

format
uri
isActivebooleanRequired

Whether the public share currently resolves.

resourceTypestringRequired

Kind of resource being shared.

enum
["file","folder"]
resourceIdstringRequired

Identifier of the shared resource.

authTypestringRequired

How access to the share is gated.

enum
["public","password","email","sso"]
hasPasswordbooleanRequired

Whether a password is stored for this share.

allowedEmailsarrayRequired

Allowed addresses or @domain patterns for email and SSO shares.

Schema details
Array itemstring
minLength
1
maxLength
320

Additional properties are not allowed.

Option 2null
revisionstring

Opaque token for the file's current content. Send it back as expectedRevision so a write or revert is refused when the content moved on. Absent for a file with no recorded content version.

currentVersionintegerRequired

Current version number. List file versions returns the history. Pass this as expectedCurrentVersion to require that version to remain current; use expectedRevision to detect edits folded into the same version.

minimum
1
maximum
2147483647

Additional properties are not allowed.

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,
    "share": null,
    "currentVersion": 1,
    "revision": "d2ZfVjFTdEdYUjh6NWpkSGk2Qm15VDkxOjIwMjYtMDEtMTVUMTA6MzA6MDAuMDAwWg"
  }
}

Response example 2

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-16T09:12:00Z",
    "deletedAt": null,
    "share": {
      "id": "shr_8Hf3kL9wQ2mNpXr6Tz1Vb",
      "token": "share-token-example",
      "url": "https://www.sim.ai/f/share-token-example",
      "isActive": true,
      "resourceType": "file",
      "resourceId": "wf_V1StGXR8z5jdHi6BmyT91",
      "authType": "public",
      "hasPassword": false,
      "allowedEmails": []
    },
    "currentVersion": 3,
    "revision": "d2ZfVjFTdEdYUjh6NWpkSGk2Qm15VDkxOjIwMjYtMDEtMTZUMDk6MTI6MDAuMDAwWg"
  }
}

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