Skip to content
Try for free
On this page

Files

Edit file content

Edit part of a UTF-8 file; use Replace file content to replace it entirely. Search-and-replace requires one exact match unless `replaceAll` is true. Anchored modes match trimmed complete lines; their input descriptions specify boundary handling. Non-UTF-8 files return `400`. Concurrent writes return `409`; re-read before retrying. OAuth scope: `api:write`.

PATCH/api/v2/files/{fileId}/content

Edit part of a UTF-8 file; use Replace file content to replace it entirely. Search-and-replace requires one exact match unless replaceAll is true. Anchored modes match trimmed complete lines; their input descriptions specify boundary handling. Non-UTF-8 files return 400. Concurrent writes return 409; re-read before retrying.

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_-]+$

Request body

Required

Workspace scope and the change to apply.

object

Workspace scope and the change to apply.

3 fields
workspaceIdstringRequired

Workspace that owns the file.

minLength
1
maxLength
128
editvalueRequired

One exact or anchor-based edit: search_replace, replace_between, insert_after, or delete_between.

Schema details

Exactly one of

Option 1object
4 fields
modestringRequired

Replace exact text.

const
search_replace
searchstringRequired

Exact text to replace, matched verbatim. It must appear once unless replaceAll is true.

minLength
1
contentstringRequired

Text to put in its place. An empty string deletes the matched text.

replaceAllboolean

Replace every non-overlapping match. Defaults to false.

Additional properties are not allowed.

Option 2object
5 fields
modestringRequired

Replace content between two complete-line anchors.

const
replace_between
beforeAnchorstringRequired

Boundary line before the replaced content. This line remains.

minLength
1
afterAnchorstringRequired

Boundary line after the replaced content. This line remains.

minLength
1
contentstringRequired

Replacement text. An empty string clears the interior.

occurrenceinteger

Which beforeAnchor match to use, starting at 1. Defaults to 1. afterAnchor is the first match after it.

minimum
1
maximum
9007199254740991

Additional properties are not allowed.

Option 3object
4 fields
modestringRequired

Insert content after a complete-line anchor.

const
insert_after
anchorstringRequired

Complete line after which content is inserted.

minLength
1
contentstringRequired

Text to insert.

minLength
1
occurrenceinteger

Which anchor match to insert after, starting at 1. Defaults to 1.

minimum
1
maximum
9007199254740991

Additional properties are not allowed.

Option 4object
4 fields
modestringRequired

Delete from one complete-line anchor to another.

const
delete_between
startAnchorstringRequired

First line to delete. This start anchor is removed.

minLength
1
endAnchorstringRequired

Ending boundary line. This end anchor remains.

minLength
1
occurrenceinteger

Which startAnchor match to use, starting at 1. Defaults to 1. endAnchor is the first match after it.

minimum
1
maximum
9007199254740991

Additional properties are not allowed.

expectedRevisionstring

Revision from Get file metadata or an earlier write; the request is refused with 409 when the content moved on.

minLength
1

Additional properties are not allowed.

Request example 1

json
{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "edit": {
    "mode": "search_replace",
    "search": "- based in NYC",
    "content": "- based in SF"
  }
}

Request example 2

json
{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "edit": {
    "mode": "insert_after",
    "anchor": "## Preferences",
    "content": "- prefers async updates"
  }
}

Responses

200

The edited file and its new line count.

object

A workspace file after an in-place content edit.

1 field
dataobjectRequired

Response data.

3 fields
fileobjectRequired

The file after the edit.

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.

lineCountintegerRequired

Lines the file holds after the edit.

minimum
0
maximum
9007199254740991
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": {
    "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
    },
    "lineCount": 5
  }
}

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