Replace a file's contents

overwriteFile

PUT /api/v1/shares/{share_id}/content

Scope: files.overwriteRate cost: 5

Replace a file’s contents: the request body is the new contents, streamed to the share as it arrives, at any size (Content-Length required)

Send If-Match with the file’s ETag as you last read it (GET …/item, a listing, or a write’s answer): without it 428, with a stale one 412, so nothing is replaced that you did not look at. A body that ends before its Content-Length leaves the file exactly as it was. Needs files.overwrite, allowed for your app on this share. Refused for a file someone else has checked out (423), one under a legal hold (403), the document of a signing still out (409), and, for a person who may only read the approved version of a published file, that file (403). Where the share’s storage keeps no earlier versions an administrator may refuse apps this change (409 not-recoverable-here). Answers the file with its new ETag. Not offered to an app whose administrator requires approval for its changes (403 needs-approval-not-available): new contents cannot be held for approval.

Request

curl -X PUT "$FOLDR/api/v1/shares/$SHARE_ID/content?path=%2FReports%2Fq3.pdf" \
  -H "Authorization: Bearer $TOKEN" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./file

$FOLDR is your site’s address (for example https://files.example.com) and $TOKEN is an access token. See Getting access.

Parameters

Name	In	Type	Required	Description
share_id	path	string	Yes	The share’s id.
path	query	string	Yes	The path of the file to replace.
If-Match	header	string	Yes	The file’s ETag as you last read it (any form this API gave you for it; a list matches if any member does). ”*” is refused.

Request body

The file’s new contents, exactly Content-Length bytes.

application/octet-stream, required: string (binary)

Responses

Status	Meaning	Body
200	The file, with its new ETag.	application/json: Item

200 response

Header	Description
ETag	The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.

Item:

Field	Type	Description
share_id	string (uuid)	Required. The id of the share the item is in.
path	string	Required. The canonical path: as the storage holds it (its case), Unicode NFC, always starting with ”/”. ”/” is the top of the share. Send this form back in later calls.
name	string	Required. The item’s name (the last segment of its path; the share’s name for the top).
kind	string, one of file, folder	Required. file or folder.
size	integer or null	Required. Size in bytes; null for a folder, and null when the item has no fixed byte size (a native Google document, exported on download: see export).
modified	string or null (date-time)	Required. Last modified (RFC 3339, UTC), where the storage reports it.
mime_type	string or null	Required. The item’s own media type, as the storage reports it or guessed from the name; null for a folder. A native Google document has Google’s own type here (application/vnd.google-apps.document for a Doc); export says what it downloads as.
export	Export or null	Required. For a native Google document that can be downloaded, what content delivers: its media type and the extension the download is named with. Null for everything else, including a native Google type that cannot be downloaded (a Form: content answers 409 not-downloadable).
etag	string or null	Required. The item’s entity tag: the storage’s own where it has one, else a weak tag over size and modified time (over modified time alone for a native Google document, whose export is made afresh each time). Null on a search hit, which comes from the index; GET …/item for the live one.
read_only	boolean	Required. True when the person cannot change things in this share.
checked_out	Checkout or null	Required. Who has the item checked out, or null. Null on a search hit.

Example:

{
  "share_id": "0191f2c4-8a1e-7b52-9d3a-5c1e0b7a4d21",
  "path": "string",
  "name": "string",
  "kind": "file",
  "size": 1,
  "modified": "2026-11-04T09:30:00Z",
  "mime_type": "string",
  "export": {
    "mime_type": "string",
    "extension": "string"
  },
  "etag": "string",
  "read_only": false,
  "checked_out": {
    "by": {},
    "since": "2026-11-04T09:30:00Z"
  }
}

Errors

Every error is an application/problem+json document (ProblemDetails); branch on its type or code. See Errors.

Status	Problem types	When
400	invalid-path invalid-request	One of: Invalid path (invalid-path); Invalid request (invalid-request).
401	invalid-token	Invalid token (invalid-token).
403	insufficient-scope legal-hold needs-approval-not-available write-not-allowed	One of: Insufficient scope (insufficient-scope); Legal hold (legal-hold); Not offered in approval mode (needs-approval-not-available); Not allowed for this app (write-not-allowed).
404	not-found	Not found (not-found).
409	ambiguous-path envelope-source not-a-file not-recoverable-here storage-account-not-connected	One of: Ambiguous path (ambiguous-path); Out for signature (envelope-source); Not a file (not-a-file); Not recoverable here (not-recoverable-here); Storage account not connected (storage-account-not-connected).
412	precondition-failed	Precondition failed (precondition-failed).
413	too-large	Too large (too-large).
423	checked-out	Checked out (checked-out).
428	precondition-required	Precondition required (precondition-required).
429	destructive-budget rate-limited	One of: Daily limit of removals reached (destructive-budget); Too many requests (rate-limited).
500	internal-error	Internal error (internal-error).
503	share-unavailable share-unreachable write-failed	One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).