Skip to content
Try for free
On this page

Files

Create file

Create a workspace file from inline UTF-8 or base64 content. Use an upload session for streamed or larger files. OAuth scope: `api:write`.

POST/api/v2/files

Create a workspace file from inline UTF-8 or base64 content. Use an upload session for streamed or larger files.

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.

Request body

Required

Inline content and placement for a new workspace file.

object

Inline content and placement for a new workspace file.

6 fields
workspaceIdstringRequired

Workspace in which to create the file.

minLength
1
maxLength
128
namestringRequired

File name, including its extension. Path separators and dot segments are rejected.

minLength
1
maxLength
255
contentTypestring

MIME type. When omitted, it is inferred from the file extension.

minLength
1
maxLength
255
folderPathstring

Canonical containing-folder path. Omit for the workspace root.

maxLength
4096
contentstring

Initial file content. Omit or send an empty string for a zero-byte file. The complete JSON request is capped at 10 MiB, including UTF-8 encoding, escaping, base64, and the envelope. The separate decoded-file limit is 50 MiB. Use an upload session for larger payloads.

default
maxLength
70000000
encodingstring

Encoding of the content field.

default
utf-8
enum
["utf-8","base64"]

Additional properties are not allowed.

Request example 1

json
{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "name": "notes.md",
  "content": "# Notes"
}

Responses

201

The created file.

object

A newly created workspace file, with the revision it produced.

1 field
dataobjectRequired

Response data.

12 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
revisionstring

Opaque token for the content this write produced. Send it back as expectedRevision on the next write. Absent for a file with no recorded content version.

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
  }
}

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