API - Folders Management

Manage folders and organize your forms using the Folders API. All endpoints require authentication via API token.

Base URL: https://api.headlessforms.cloud/api/v1/teams/{TEAM_SLUG}/folders

Note: All endpoints require authentication. Include your API token in the Authorization header as Bearer {API_TOKEN} or as a query parameter ?api_token={API_TOKEN}.
Team Slug: The {TEAM_SLUG} is the unique identifier for your team. You can get all your teams (including their slugs) by calling the Teams API endpoint (GET /api/v1/teams). Alternatively, you can find it in your team's URL in the web interface (e.g., https://app.headlessforms.cloud/teams/my-team-slug).

Get All Folders

Retrieve all folders for a team. The authenticated user must be a member of the team.

Access Control:

Team Owner: Sees all folders in the team
Team Member: Sees folders they have access to, which includes:
- Folders they created (as creator)
- Folders they have explicit access to (via folder permissions)

Endpoint

GET /api/v1/teams/{TEAM_SLUG}/folders

Path Parameters

Name	Type	Description
TEAM_SLUG	string	Required. Team slug.

Headers

Key	Value
Content-Type	application/json
Accept	application/json
Authorization	Bearer

Example Request

bash

curl --location --request GET 'https://api.headlessforms.cloud/api/v1/teams/my-team-slug/folders' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {API_TOKEN}'

Response (200 OK)

json

{
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "parent_uuid": null,
      "name": "Marketing Forms"
    },
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440001",
      "parent_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Support Forms"
    }
  ]
}

Get Folder with Forms

Retrieve a specific folder, all forms it contains, and its child folders. The authenticated user must be a member of the team.

Access Control:

Team Owner: Sees all folders and forms
Team Member:
- Sees the folder if they have access to it (as creator or via explicit permissions)
- Sees only child folders they have access to (as creator or via explicit permissions)
- Sees all forms in the folder (if they have access to the folder)
Returns 403 Access Denied if the user doesn't have access to the requested folder

Endpoint

GET /api/v1/teams/{TEAM_SLUG}/folders/{FOLDER_UUID}

Path Parameters

Name	Type	Description
TEAM_SLUG	string	Required. Team slug.
FOLDER_UUID	string	Required. Folder UUID.

Headers

Key	Value
Content-Type	application/json
Accept	application/json
Authorization	Bearer

Example Request

bash

curl --location --request GET 'https://api.headlessforms.cloud/api/v1/teams/my-team-slug/folders/550e8400-e29b-41d4-a716-446655440000' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {API_TOKEN}'

Response (200 OK)

json

{
  "data": {
    "folder": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "parent_uuid": null,
      "name": "Marketing Forms"
    },
    "forms": [
      {
        "id": "e3f0f882-17d0-41d3-88d7-567b8e66345a",
        "name": "Contact Form",
        "token": "abc123xyz",
        "folder_uuid": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "folders": [
      {
        "uuid": "550e8400-e29b-41d4-a716-446655440001",
        "parent_uuid": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Support Forms"
      }
    ]
  }
}

Create Folder

Create a new folder. The authenticated user must be a member of the team.

Access Control:

Team Owner: Can create folders anywhere in the team (no access restrictions)
Team Member:
- Must have form-create permission to create folders
- Can create folders in root (without parent_uuid) if they have form-create permission
- If creating a folder with parent_uuid specified, must have:
  - form-create permission AND
  - Access to the parent folder

Endpoint

POST /api/v1/teams/{TEAM_SLUG}/folders

Path Parameters

Name	Type	Description
TEAM_SLUG	string	Required. Team slug.

Headers

Key	Value
Content-Type	application/json
Accept	application/json
Authorization	Bearer

Request Body

Field	Type	Required	Description
name	string	Yes	Folder name (max 190 characters)
parent_uuid	string	No	UUID of parent folder (for nested folders)

Example Request

bash

curl --location --request POST 'https://api.headlessforms.cloud/api/v1/teams/my-team-slug/folders' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {API_TOKEN}' \
--data-raw '{
  "name": "Marketing Forms",
  "parent_uuid": null
}'

Response (201 Created)

json

{
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Forms",
    "parent_uuid": null
  },
  "message": "Folder created successfully"
}

Create Nested Folder

To create a folder inside another folder:

bash

curl --location --request POST 'https://api.headlessforms.cloud/api/v1/teams/my-team-slug/folders' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {API_TOKEN}' \
--data-raw '{
  "name": "Q1 Campaigns",
  "parent_uuid": "550e8400-e29b-41d4-a716-446655440000"
}'

Delete Folder

Delete a folder. Forms in the folder will be moved to root (not deleted). The authenticated user must be a member of the team.

Access Control:

Team Owner: Can delete any folder in the team (no access restrictions)
Team Member:
- Must have form-delete permission to delete folders
- Must have explicit access to the folder being deleted (via folder permissions)

Endpoint

DELETE /api/v1/teams/{TEAM_SLUG}/folders/{FOLDER_UUID}

Path Parameters

Name	Type	Description
TEAM_SLUG	string	Required. Team slug.
FOLDER_UUID	string	Required. Folder UUID.

Headers

Key	Value
Content-Type	application/json
Accept	application/json
Authorization	Bearer

Example Request

bash

curl --location --request DELETE 'https://api.headlessforms.cloud/api/v1/teams/my-team-slug/folders/550e8400-e29b-41d4-a716-446655440000' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {API_TOKEN}'

Response (200 OK)

json

{
  "message": "Folder deleted successfully"
}

Note: When a folder is deleted, all forms inside it are automatically moved to the root (folder_uuid set to null). Child folders are also deleted recursively.

Assign Form to Folder

Assign a form to a folder or remove it from a folder (move to root). The authenticated user must be a member of the team.

Access Control:

Team Owner: Can assign forms to any folder in the team (no access restrictions)
Team Member:
- Must have form-create permission to assign forms
- Can move forms to root (set folder_uuid to null) if they have form-create permission
- If assigning a form to a folder with folder_uuid specified, must have:
  - form-create permission AND
  - Explicit access to the target folder (via folder permissions)

Endpoint

PUT /api/v1/teams/{TEAM_SLUG}/folders/assign-form

Path Parameters

Name	Type	Description
TEAM_SLUG	string	Required. Team slug.

Headers

Key	Value
Content-Type	application/json
Accept	application/json
Authorization	Bearer

Request Body

Field	Type	Required	Description
form_id	string	Yes	Form ID
folder_uuid	string	No	Folder UUID to assign form to. Set to `null` to move form to root.

Example: Assign Form to Folder

bash

curl --location --request PUT 'https://api.headlessforms.cloud/api/v1/teams/my-team-slug/folders/assign-form' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {API_TOKEN}' \
--data-raw '{
  "form_id": "e3f0f882-17d0-41d3-88d7-567b8e66345a",
  "folder_uuid": "550e8400-e29b-41d4-a716-446655440000"
}'

Example: Remove Form from Folder (Move to Root)

bash

curl --location --request PUT 'https://api.headlessforms.cloud/api/v1/teams/my-team-slug/folders/assign-form' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {API_TOKEN}' \
--data-raw '{
  "form_id": "e3f0f882-17d0-41d3-88d7-567b8e66345a",
  "folder_uuid": null
}'

Response (200 OK)

The response contains only essential form fields:

json

{
  "data": {
    "id": "e3f0f882-17d0-41d3-88d7-567b8e66345a",
    "name": "Contact Form",
    "token": "abc123xyz",
    "folder": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Marketing Forms"
    }
  },
  "message": "Form assigned to folder successfully"
}

Or when removing from folder (folder is set to null):

json

{
  "data": {
    "id": "e3f0f882-17d0-41d3-88d7-567b8e66345a",
    "name": "Contact Form",
    "token": "abc123xyz",
    "folder": null
  },
  "message": "Form removed from folder successfully"
}

Note: The response includes only essential form fields (id, name, token, team, folder). The team object contains slug and name, and the folder object contains uuid and name (or null if the form is not in a folder). Other form properties are not included in the response.

Error Responses

401 Unauthorized

json

{
  "message": "Unauthenticated."
}

Occurs when API token is missing or invalid.

403 Forbidden

json

{
  "error": "Access Denied"
}

Occurs when:

User doesn't belong to the team
User lacks required permissions (form-create for create/assign, form-delete for delete, form edit permission for assign)
User doesn't have access to the folder

404 Not Found

json

{
  "error": "Not Found"
}

Occurs when:

Validation fails (e.g., folder name too long)
Parent folder doesn't exist or doesn't belong to the team
Folder UUID is invalid

500 Internal Server Error

json

{
  "error": "Some error"
}

Occurs when an unexpected server error happens.

Permissions

Get folders/list:
- Requires user to be a team member
- Team Owner: Sees all folders in the team
- Team Member: Sees folders they have access to, which includes:
  - Folders they created (as creator)
  - Folders they have explicit access to (via folder permissions)
- Folder access is checked via FolderAccessService
Create folder:
- Requires user to be a team member
- Team Owner: Can create folders anywhere in the team (no access restrictions)
- Team Member:
  - Must have form-create permission to create folders
  - Can create folders in root (without parent_uuid) if they have form-create permission
  - If creating a folder with parent_uuid specified, must have:
    - form-create permission AND
    - Access to the parent folder
- When a non-owner user creates a folder, they automatically receive access permissions to that folder and all parent folders
Delete folder:
- Requires user to be a team member
- Team Owner: Can delete any folder in the team (no access restrictions)
- Team Member:
  - Must have form-delete permission to delete folders
  - Must have explicit access to the folder being deleted (via folder permissions)
Get folder:
- Requires user to be a team member
- Team Owner: Sees all folders and forms
- Team Member: Sees the folder if they have access to it (as creator or via explicit permissions). Sees only child folders they have access to (as creator or via explicit permissions). Sees all forms in the folder (if they have access to the folder)
- Returns 403 Access Denied if the user doesn't have access to the requested folder
Assign form:
- Requires user to be a team member
- Team Owner: Can assign forms to any folder in the team (no access restrictions)
- Team Member:
  - Must have form-create permission to assign forms
  - Can move forms to root (set folder_uuid to null) if they have form-create permission
  - If assigning a form to a folder with folder_uuid specified, must have:
    - form-create permission AND
    - Explicit access to the target folder (via folder permissions)
- Also requires form edit permission (check via canEditForm)

API - Folders Management ​

Get All Folders ​

Endpoint ​

Path Parameters ​

Headers ​

Example Request ​

Response (200 OK) ​

Get Folder with Forms ​

Endpoint ​

Path Parameters ​

Headers ​

Example Request ​

Response (200 OK) ​

Create Folder ​

Endpoint ​

Path Parameters ​

Headers ​

Request Body ​

Example Request ​

Response (201 Created) ​

Create Nested Folder ​

Delete Folder ​

Endpoint ​

Path Parameters ​

Headers ​

Example Request ​

Response (200 OK) ​

Assign Form to Folder ​

Endpoint ​

Path Parameters ​

Headers ​

Request Body ​

Example: Assign Form to Folder ​

Example: Remove Form from Folder (Move to Root) ​

Response (200 OK) ​

Error Responses ​

401 Unauthorized ​

403 Forbidden ​

404 Not Found ​

500 Internal Server Error ​

Permissions ​

API - Folders Management

Get All Folders

Endpoint

Path Parameters

Headers

Example Request

Response (200 OK)

Get Folder with Forms

Endpoint

Path Parameters

Headers

Example Request

Response (200 OK)

Create Folder

Endpoint

Path Parameters

Headers

Request Body

Example Request

Response (201 Created)

Create Nested Folder

Delete Folder

Endpoint

Path Parameters

Headers

Example Request

Response (200 OK)

Assign Form to Folder

Endpoint

Path Parameters

Headers

Request Body

Example: Assign Form to Folder

Example: Remove Form from Folder (Move to Root)

Response (200 OK)

Error Responses

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Permissions