Rename a file or folder

renameItem

POST /api/v1/shares/{share_id}/rename

Scope: files.writeRate cost: 2

Rename a file or folder where it is

Send If-Match with the ETag you last read for it (GET …/item, a listing, or a write’s answer): a rename without one is refused (428), and one whose item has changed since is refused (412), so nothing renamed is something you did not look at. An item under a legal hold (or a folder holding one) is refused 403 legal-hold, whatever the app is allowed. Answers the item at its NEW canonical path; the old path names nothing afterwards.

Request

curl -X POST "$FOLDR/api/v1/shares/$SHARE_ID/rename" \
  -H "Authorization: Bearer $TOKEN" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/json" \
  -d '{"path":"string","new_name":"string"}'

$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.
If-Match	header	string	Yes	The item’s ETag as you last read it (any form this API gave you for it; a list matches if any member does).

Request body

application/json, required: RenameBody

Field	Type	Description
path	string	Required. The path of the file or folder to rename.
new_name	string	Required. Its new name: one name, no ”/”, no spaces at either end. Something already called that is never replaced (409 conflict).

Example:

{
  "path": "string",
  "new_name": "string"
}

Responses

Status	Meaning	Body
200	The item, at its new canonical path.	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 write-not-allowed	One of: Insufficient scope (insufficient-scope); Legal hold (legal-hold); Not allowed for this app (write-not-allowed).
404	not-found	Not found (not-found).
409	ambiguous-path conflict storage-account-not-connected	One of: Ambiguous path (ambiguous-path); Conflict (conflict); Storage account not connected (storage-account-not-connected).
412	precondition-failed	Precondition failed (precondition-failed).
423	checked-out	Checked out (checked-out).
428	precondition-required	Precondition required (precondition-required).
429	daily-write-limit rate-limited	One of: Daily write limit reached (daily-write-limit); 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).