Projects & Folders

Project Endpoints

Method	Path	Scope	Description
GET	/projects	projects:read	List projects
POST	/projects	projects:write	Create a project
GET	/projects/:id	projects:read	Get a project
PATCH	/projects/:id	projects:write	Update a project
DELETE	/projects/:id	projects:write	Delete a project
POST	/projects/:id/move	projects:write	Move project to a folder

Folder Endpoints

Method	Path	Scope	Description
GET	/folders	projects:read	List folders
POST	/folders	projects:write	Create a folder
GET	/folders/:id	projects:read	Get a folder
PATCH	/folders/:id	projects:write	Update a folder
DELETE	/folders/:id	projects:write	Delete a folder

Folders organize projects or brandings into a hierarchy up to 3 levels deep. Project folders require a Pro or Business plan; branding folders require Business.

List Projects

bash

curl "https://my.clarife.app/api/v1/projects?limit=20&offset=0" \
  -H "Authorization: Bearer clrf_your_key"

Query parameters:

Param	Type	Default	Description
limit	integer	50	Results per page (max 100)
offset	integer	0	Number of results to skip
folder_id	uuid	-	Filter by parent folder

Response:

json

{
  "data": [
    {
      "id": "p1a2b3c4-...",
      "name": "Product Docs",
      "description": null,
      "icon": "book",
      "folder_id": null,
      "sort_order": 0,
      "visibility": "private",
      "created_at": "2026-03-10T08:00:00Z",
      "updated_at": "2026-03-28T12:00:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Create a Project

bash

curl -X POST https://my.clarife.app/api/v1/projects \
  -H "Authorization: Bearer clrf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding Guides",
    "icon": "graduation-cap",
    "folder_id": "f1a2b3c4-..."
  }'

Field	Type	Required	Description
name	string	Yes	Project name (1-200 chars)
description	string	No	Description (max 2000 chars)
icon	string	No	Icon identifier (max 100 chars)
folder_id	uuid	No	Parent folder

Get a Project

bash

curl https://my.clarife.app/api/v1/projects/p1a2b3c4-... \
  -H "Authorization: Bearer clrf_your_key"

Returns the project details including its document count (document_count).

Update a Project

bash

curl -X PATCH https://my.clarife.app/api/v1/projects/p1a2b3c4-... \
  -H "Authorization: Bearer clrf_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "New Name" }'

Delete a Project

bash

curl -X DELETE https://my.clarife.app/api/v1/projects/p1a2b3c4-... \
  -H "Authorization: Bearer clrf_your_key"

⚠️ Warning: Deleting a project does not delete its documents - only the link between them is removed.

Move a Project

Move a project into a different folder (or to the root level by passing null):

bash

curl -X POST https://my.clarife.app/api/v1/projects/p1a2b3c4-.../move \
  -H "Authorization: Bearer clrf_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "folder_id": "f2b3c4d5-..." }'

List Folders

bash

curl "https://my.clarife.app/api/v1/folders?entity_type=project" \
  -H "Authorization: Bearer clrf_your_key"

Create a Folder

bash

curl -X POST https://my.clarife.app/api/v1/folders \
  -H "Authorization: Bearer clrf_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Q2 Documentation", "entity_type": "project" }'

Field	Type	Required	Description
name	string	Yes	Folder name (1-200 chars)
entity_type	string	Yes	project or branding
parent_id	uuid	No	Parent folder (max 3 levels)
color	string	No	Hex color, e.g. #6366F1 (default #6b7280)

Update a Folder

bash

curl -X PATCH https://my.clarife.app/api/v1/folders/f1a2b3c4-... \
  -H "Authorization: Bearer clrf_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Renamed Folder" }'

Delete a Folder

bash

curl -X DELETE https://my.clarife.app/api/v1/folders/f1a2b3c4-... \
  -H "Authorization: Bearer clrf_your_key"

⚠️ Warning: Deleting a folder also deletes its subfolders (cascade). Projects inside are not deleted - they only lose their folder assignment.