Folders

Group forms into folders.

List folders

GET /api/v1/folders

Returns every folder in the active workspace that the caller can see. Not paginated.

Service account scope: forms:read

Example request

curl "https://acme.formcel.com/api/v1/folders" \
  -H "Authorization: Bearer $FORMCEL_API_KEY"

Responses

200 All visible folders.
401 The API key is missing or invalid.

Response body FolderList

data array of FolderSummary required
total integer required
limit integer required
offset integer required

FolderSummary

id string required
label string required
icon string required
color string required
parent_id string: Omitted for top-level folders.
sort_order integer required
role string required: The caller's role on the folder. New values may be added.
created_at string (date-time) required
updated_at string (date-time) required

Create a folder

POST /api/v1/folders

Creates a folder in the active workspace. Requires edit access to the workspace.

Service account scope: forms:write

Request body

label string required
icon string: Defaults to "folder" when empty.
color string
parent_id string: Create the folder inside this folder.

Example request

curl -X POST "https://acme.formcel.com/api/v1/folders" \
  -H "Authorization: Bearer $FORMCEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"Marketing","color":"blue"}'

Responses

201 The created folder.
400 The request body or parameters are invalid.
401 The API key is missing or invalid.
403 The caller lacks access to the resource, or the service account lacks the required scope.

Response body FolderSummary

id string required
label string required
icon string required
color string required
parent_id string: Omitted for top-level folders.
sort_order integer required
role string required: The caller's role on the folder. New values may be added.
created_at string (date-time) required
updated_at string (date-time) required

Update a folder

PATCH /api/v1/folders/{id}

Updates folder properties. Only the fields present in the body change. Send parent_id as null to move the folder to the top level. Requires the owner or editor role.

Service account scope: forms:write

path parameters

id string required: Folder ID.

Request body

label string
icon string
color string
parent_id string or null: Send null to move the folder to the top level.
sort_order integer

Example request

curl -X PATCH "https://acme.formcel.com/api/v1/folders/ID" \
  -H "Authorization: Bearer $FORMCEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"Campaigns","parent_id":null}'

Responses

200 The updated folder.
400 The request body or parameters are invalid.
401 The API key is missing or invalid.
403 The caller lacks access to the resource, or the service account lacks the required scope.
404 The resource does not exist.

Response body FolderSummary

id string required
label string required
icon string required
color string required
parent_id string: Omitted for top-level folders.
sort_order integer required
role string required: The caller's role on the folder. New values may be added.
created_at string (date-time) required
updated_at string (date-time) required

Delete a folder

DELETE /api/v1/folders/{id}

Deletes the folder. Forms inside it are kept and become unfiled. Only the owner can delete a folder.

Service account scope: forms:write

path parameters

id string required: Folder ID.

Example request

curl -X DELETE "https://acme.formcel.com/api/v1/folders/ID" \
  -H "Authorization: Bearer $FORMCEL_API_KEY"

Responses

204 The folder was deleted.
401 The API key is missing or invalid.
403 The caller lacks access to the resource, or the service account lacks the required scope.
404 The resource does not exist.