Create a folder

Makes a folder, optionally inside another.

POST /v1/file-folders

Permission

The key must be granted files.write

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

Request body

Field	Type	Description
`name` required	string
`parent_id`	string	Nest it inside this folder. The root when omitted.

Request

curl https://api.veruapis.com/v1/file-folders \
  -X POST \
  -H "Authorization: Bearer vak_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Q3", "parent_id": "0192f001-0000-7a41-b8d2-5e9f0c3a7b41" }'

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

Answers 201.

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", "parent_id": "0192f001-0000-7a41-b8d2-5e9f0c3a7b41", "trashed": false, "created_at": "2026-08-02T09:00:00Z", "updated_at": "2026-08-02T09:00:00Z" },
  "meta": { "request_id": "req_01j8z9...", "timestamp": "2026-09-02T10:00:00Z" }
}

Worth knowing

Omit parent_id to create it at the root.

Errors

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

POST `/v1/file-folders`

Your API key Used once, never stored.

name parent_id

Create a folder

Permission

Request body

Request

Response

Related