REST API

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

Open Cleve and go to Settings → Developer
Click Manage next to API keys
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

Parameter	Type	Description
`folderId`	string	Filter to a specific folder
`pinnedOnly`	boolean	Return 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)

Field	Type	Description
`title`	string	Note title
`content`	string	Note body (markdown)
`folderId`	string	Folder to place the note in
`isPinned`	boolean	Whether 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)

Field	Type	Description
`title`	string	New title
`content`	string	New body (markdown)
`isPinned`	boolean	Pin or unpin
`isPublic`	boolean	Enable or disable link sharing
`folderId`	string \| null	Move 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

Parameter	Type	Default	Max
`limit`	number	10	50

Search Notes

GET /api/v1/notes/search

Full-text search across your notes — searches both titles and content. Query parameters

Parameter	Type	Required	Description
`query`	string	✅	Search term
`limit`	number		Max results to return
`folderId`	string		Scope to a folder
`isPinned`	boolean		Filter 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

Parameter	Type	Description
`folderId`	string	Scope 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)

Field	Type	Required	Description
`name`	string	✅	Folder name
`parentId`	string		Parent 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)

Field	Type	Required	Description
`name`	string	✅	New folder name

Delete a Folder

DELETE /api/v1/folders/:folderId

Deletes the folder. Notes inside are moved to unfiled (not deleted).

Error Responses

Status	Meaning
`401`	Missing or invalid API key
`404`	Note or folder not found
`400`	Missing required field
`500`	Internal 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.

Getting Started

Core Features

Advanced Features

Plans & Billing

Developers

Reference

Overview

Authentication

Getting an API Key

Notes

List Notes

Create a Note

Get a Note

Update a Note

Delete a Note

List Recent Notes

Search Notes

Count Notes

Folders

List Folders

Create a Folder

Rename a Folder

Delete a Folder

Error Responses

MCP Server

Pricing

​Overview

​Authentication

​Getting an API Key

​Notes

​List Notes

​Create a Note

​Get a Note

​Update a Note

​Delete a Note

​List Recent Notes

​Search Notes

​Count Notes

​Folders

​List Folders

​Create a Folder

​Rename a Folder

​Delete a Folder

​Error Responses

​Related

MCP Server

Pricing

Overview

Authentication

Getting an API Key

Notes

List Notes

Create a Note

Get a Note

Update a Note

Delete a Note

List Recent Notes

Search Notes

Count Notes

Folders

List Folders

Create a Folder

Rename a Folder

Delete a Folder

Error Responses

Related