Rename and/or move a folder
workflow:writeSets the folder's name AND parentId in one write. Both fields are a true replace, and that is the trap: parentId is applied exactly as sent, so OMITTING it (or sending null) MOVES THE FOLDER TO THE ROOT. To rename without moving, re-send the folder's current parentId.
name is required and trimmed; blank is a 400.
Cycles are refused: a folder cannot be its own parent and cannot be moved into one of its own descendants. A parentId outside this workspace reads as "parent folder not found".
The response is only an acknowledgement {id, updated: true} — it does NOT return the updated folder. Re-list if you need the new state.
Authorization
bearerAuth An API token: Authorization: Bearer grt_…. Mint one in the app under Settings → Workspace → API tokens; the raw value is shown once. Scopes confine the token — see x-permission on each operation.
In: header
Path Parameters
The folder's UUID.
uuidRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/api/folders/497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "name": "Invoices 2026", "parentId": "1b2c3d4e-5f60-4718-9a2b-3c4d5e6f7081" }'{ "data": { "id": "1b2c3d4e-5f60-4718-9a2b-3c4d5e6f7081", "updated": true }}