Skip to main content

​
Overview

The Cleve REST API lets you read and write notes and folders programmatically. Base URL: https://app.cleve.ai/api/v1

​
Authentication

All requests require a personal API key passed as a Bearer token: 
Authorization: Bearer <your-api-key>

​
Getting an API Key

  1. Open Cleve and go to Settings → Developer
  2. Click Manage next to API keys
  3. Create a new key in your Clerk user profile
API keys are personal and scoped to your account. Keep them secret — anyone with your key can read and modify your notes.

​
Notes

​
List Notes

GET /api/v1/notes
Query parameters
ParameterTypeDescription
folderIdstringFilter to a specific folder
pinnedOnlybooleanReturn only pinned notes
Example 
curl -H "Authorization: Bearer <your-api-key>" \
  "https://app.cleve.ai/api/v1/notes"

​
Create a Note

POST /api/v1/notes
Body (JSON)
FieldTypeDescription
titlestringNote title
contentstringNote body (markdown)
folderIdstringFolder to place the note in
isPinnedbooleanWhether to pin the note
Example 
curl -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Meeting notes", "content": "## Agenda\n\n- Item 1"}' \
  "https://app.cleve.ai/api/v1/notes"
Response 
{ "noteId": "abc123" }

​
Get a Note

GET /api/v1/notes/:noteId
Returns the full note object including title, content, and metadata. Example 
curl -H "Authorization: Bearer <your-api-key>" \
  "https://app.cleve.ai/api/v1/notes/abc123"

​
Update a Note

PATCH /api/v1/notes/:noteId
Body (JSON, all fields optional)
FieldTypeDescription
titlestringNew title
contentstringNew body (markdown)
isPinnedbooleanPin or unpin
isPublicbooleanEnable or disable link sharing
folderIdstring | nullMove to folder, or null to unfile
Example 
curl -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"isPinned": true}' \
  "https://app.cleve.ai/api/v1/notes/abc123"

​
Delete a Note

DELETE /api/v1/notes/:noteId
Permanently deletes the note. This cannot be undone. Example 
curl -X DELETE \
  -H "Authorization: Bearer <your-api-key>" \
  "https://app.cleve.ai/api/v1/notes/abc123"

​
List Recent Notes

GET /api/v1/notes/recent
Returns the most recently updated notes. Query parameters
ParameterTypeDefaultMax
limitnumber1050

​
Search Notes

GET /api/v1/notes/search
Full-text search across your notes — searches both titles and content. Query parameters
ParameterTypeRequiredDescription
querystring✅Search term
limitnumberMax results to return
folderIdstringScope to a folder
isPinnedbooleanFilter to pinned notes only (true or false)
Example 
curl -H "Authorization: Bearer <your-api-key>" \
  "https://app.cleve.ai/api/v1/notes/search?query=product+roadmap"
You can also POST with a JSON body (useful for queries with special characters): 
curl -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"query": "product roadmap"}' \
  "https://app.cleve.ai/api/v1/notes/search"

​
Count Notes

GET /api/v1/notes/count
Returns total and pinned note counts. Query parameters
ParameterTypeDescription
folderIdstringScope to a folder

​
Folders

​
List Folders

GET /api/v1/folders
Returns all folders in your workspace (flat list with parent references for hierarchy). Example 
curl -H "Authorization: Bearer <your-api-key>" \
  "https://app.cleve.ai/api/v1/folders"

​
Create a Folder

POST /api/v1/folders
Body (JSON)
FieldTypeRequiredDescription
namestring✅Folder name
parentIdstringParent folder ID for nesting
Example 
curl -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Research"}' \
  "https://app.cleve.ai/api/v1/folders"
Response 
{ "folderId": "def456" }

​
Rename a Folder

PATCH /api/v1/folders/:folderId
Body (JSON)
FieldTypeRequiredDescription
namestring✅New folder name

​
Delete a Folder

DELETE /api/v1/folders/:folderId
Deletes the folder. Notes inside are moved to unfiled (not deleted).

​
Error Responses

StatusMeaning
401Missing or invalid API key
404Note or folder not found
400Missing required field
500Internal server error
All errors return JSON: 
{ "error": "Note not found" }

MCP Server

Connect AI agents to Cleve via the Model Context Protocol.

Pricing

API access is available on all plans.