Upload and organize files

This walks through the smallest end-to-end flow: create a library, create a folder inside it, upload a file into that folder, then list it back. Scopes needed: files:write to create and upload, files:read to list.

1. Create a library

A library is the top-level container (called a "workspace" internally — the API only ever calls it a library).

curl -X POST https://us.api.brault.app/v1/libraries \
  -H "Authorization: Bearer $BRAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-1111-4c1a-9c1e-lib-create" \
  -d '{"name": "Client Deliverables"}'

{
  "object": "library",
  "id": "<library_id>",
  "name": "Client Deliverables",
  "description": "",
  "emoji": null,
  "pinned": false,
  "created_at": "2026-09-06T10:00:00.000Z",
  "updated_at": "2026-09-06T10:00:00.000Z",
  "created_by_id": "<user_id>"
}

2. Create a folder

A folder needs exactly one parent: either library_id (a root folder of that library) or folder_id (a child of that folder).

curl -X POST https://us.api.brault.app/v1/folders \
  -H "Authorization: Bearer $BRAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-2222-4c1a-9c1e-folder-create" \
  -d '{"name": "Final Renders", "library_id": "<library_id>"}'

3. Upload a file

Uploads are at most four calls, and file bytes never pass through this API — you PUT them straight to S3 with a presigned URL. Start by declaring the name and size:

curl -X POST https://us.api.brault.app/v1/uploads \
  -H "Authorization: Bearer $BRAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-3333-4c1a-9c1e-upload-start" \
  -d '{"name": "hero.psd", "size": 18874368, "folder_id": "<folder_id>"}'

{
  "object": "upload",
  "id": "<upload_id>",
  "method": "put",
  "file_id": "<file_id>",
  "version_id": null,
  "upload_url": "https://….s3.amazonaws.com/…",
  "part_size": null,
  "part_count": null,
  "expires_at": "2026-09-07T10:00:00.000Z"
}

Files up to 256 MiB get method: "put" — a single PUT with the bytes:

curl -X PUT "<upload_url from the previous response>" \
  --data-binary @hero.psd

Files larger than 256 MiB get method: "multipart" instead: request presigned URLs per part with POST /v1/uploads/:uploadId/parts, PUT each part directly to S3, collect the ETag response header from each PUT, then send them all in the completion call below. See the Uploads reference for the exact multipart shapes.

Either way, finish with:

curl -X POST https://us.api.brault.app/v1/uploads/<upload_id>/complete \
  -H "Authorization: Bearer $BRAULT_API_KEY" \
  -H "Idempotency-Key: 8f14e45f-4444-4c1a-9c1e-upload-complete"

This returns the finished file — the same shape a plain GET /v1/files/:fileId would — with status: "processing" while thumbnails and previews render.

4. List what's in the folder

curl "https://us.api.brault.app/v1/files?folder_id=<folder_id>" \
  -H "Authorization: Bearer $BRAULT_API_KEY"

GET /v1/files also takes q (keyword/natural-language search), extensions, kind, created_after/created_before, uploaded_by, min_size/max_size, sort and order — see the Files reference for the complete parameter list, and Automate boards for filtering by a property value instead of a native field.

Cleaning up

DELETE /v1/files/:fileId and DELETE /v1/folders/:folderId trash by default — recoverable with the matching POST …/restore call — and hard-delete only when you add ?permanent=true. DELETE /v1/libraries/:libraryId takes no such parameter: it has no trash step at all and removes every folder and file the library contains immediately. If you want a safety net before deleting a library, list its contents first.