Rename or move a folder

Renames a folder, reparents it, or both in that order.

PATCH /v1/file-folders/:id

Permission

The key must be granted files.write

A key without it gets 403 insufficient_scope, with the missing permission named in details.

Path parameters

Field	Type	Description
`id` required	string	The folder to change.

Request body

Rename and move can travel together, and are applied in that order.

Field	Type	Description
`name`	string
`parent_id`	string	Where to move it. An explicit empty string moves it to the root, which is how this API distinguishes "move to the root" from "leave it where it is".

Request

curl https://api.veruapis.com/v1/file-folders/:id \
  -X PATCH \
  -H "Authorization: Bearer vak_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Q3 archive", "parent_id": "" }'

Idempotency-Key is required on every write. Retrying with the same key returns the original response rather than repeating the operation, so a timeout is something you retry rather than something you investigate.

Response

Field	Type	Description
`id`	string
`name`	string
`parent_id`	string	Empty for a folder at the root.
`owner_id`	string
`trashed`	boolean
`created_at`	RFC 3339
`updated_at`	RFC 3339

{
  "data": { "id": "0192f002-0000-7a41-b8d2-5e9f0c3a7b41", "name": "Q3 archive", "parent_id": "", "trashed": false, "updated_at": "2026-09-10T08:00:00Z" },
  "meta": { "request_id": "req_01j8z9...", "timestamp": "2026-09-02T10:00:00Z" }
}

Worth knowing

An explicit empty parent_id moves the folder to the root; leaving the field out leaves it where it is. Rename and move travel together and apply in that order.

Errors

Every failure uses the same shape, with a stable string code you can branch on. See the error reference.

PATCH `/v1/file-folders/:id`

Your API key Used once, never stored.

id

name parent_id