Create a folder
workflow:writeCreates a folder in the caller's workspace. name is required and is trimmed; a name that is empty after trimming is a 400.
parentId is optional — omit it or send null for a root folder. A parentId that does not exist IN THIS WORKSPACE is a 400 ("parent folder not found"); a cross-tenant id reads as not-found rather than forbidden, so folder existence is never disclosed. Nesting depth is not limited.
Names are NOT unique: two sibling folders may share a name.
The response carries the created folder with workflowCount 0.
Does NOT accept Idempotency-Key, so a retried create makes a second folder.
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
Request 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
curl -X POST "https://example.com/api/folders" \ -H "Content-Type: application/json" \ -d '{ "name": "Billing" }'{ "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "parentId": "70850378-7d3c-4f45-91b7-942d4dfbbd43", "workspaceId": "ef0efa32-d1c1-43d4-a5e2-fe7b4f00403c", "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa", "workflowCount": 0, "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" }}