REST API

Overview

The Cleve REST API lets you read and write notes and folders programmatically. Base URL: https://app.cleve.ai/api/v1 OpenAPI spec: https://www.cleve.ai/openapi.json (also served at https://app.cleve.ai/api/v1/openapi.json). Every operation has an operationId, typed parameters and response schemas, so you can generate a client or hand it to an LLM as function-calling tools. Every success response wraps its payload in data:

{ "data": { "noteId": "abc123" } }

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

{ "data": { "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

{ "data": { "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	`code`	Meaning
`400`	`bad_request`	Missing or invalid field
`401`	`unauthorized`	Missing or invalid API key
`404`	`not_found`	Note, folder or route not found
`500`	`internal_error`	Internal server error

All errors return JSON with a human-readable error, a stable code to branch on, a hint that says how to fix it, and a docs link:

{
  "error": "Note not found",
  "code": "not_found",
  "hint": "Check the ID or path. List notes with GET /api/v1/notes and folders with GET /api/v1/folders; every route is in https://app.cleve.ai/api/v1/openapi.json.",
  "docs": "https://docs.cleve.ai/developers/api"
}

Unknown paths under /api/v1 return the same JSON 404.

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

Integrations

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