> ## Documentation Index > Fetch the complete documentation index at: https://docs.cleve.ai/llms.txt > Use this file to discover all available pages before exploring further. # REST API > Programmatic access to your Cleve notes and folders ## 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: ```bash theme={null} Authorization: Bearer ``` ### 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 ```http theme={null} GET /api/v1/notes ``` **Query parameters** | Parameter | Type | Description | | ------------ | ------- | --------------------------- | | `folderId` | string | Filter to a specific folder | | `pinnedOnly` | boolean | Return only pinned notes | **Example** ```bash theme={null} curl -H "Authorization: Bearer " \ "https://app.cleve.ai/api/v1/notes" ``` *** ### Create a Note ```http theme={null} 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** ```bash theme={null} curl -X POST \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"title": "Meeting notes", "content": "## Agenda\n\n- Item 1"}' \ "https://app.cleve.ai/api/v1/notes" ``` **Response** ```json theme={null} { "noteId": "abc123" } ``` *** ### Get a Note ```http theme={null} GET /api/v1/notes/:noteId ``` Returns the full note object including title, content, and metadata. **Example** ```bash theme={null} curl -H "Authorization: Bearer " \ "https://app.cleve.ai/api/v1/notes/abc123" ``` *** ### Update a Note ```http theme={null} 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** ```bash theme={null} curl -X PATCH \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"isPinned": true}' \ "https://app.cleve.ai/api/v1/notes/abc123" ``` *** ### Delete a Note ```http theme={null} DELETE /api/v1/notes/:noteId ``` Permanently deletes the note. This cannot be undone. **Example** ```bash theme={null} curl -X DELETE \ -H "Authorization: Bearer " \ "https://app.cleve.ai/api/v1/notes/abc123" ``` *** ### List Recent Notes ```http theme={null} GET /api/v1/notes/recent ``` Returns the most recently updated notes. **Query parameters** | Parameter | Type | Default | Max | | --------- | ------ | ------- | --- | | `limit` | number | 10 | 50 | *** ### Search Notes ```http theme={null} 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** ```bash theme={null} curl -H "Authorization: Bearer " \ "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): ```bash theme={null} curl -X POST \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"query": "product roadmap"}' \ "https://app.cleve.ai/api/v1/notes/search" ``` *** ### Count Notes ```http theme={null} 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 ```http theme={null} GET /api/v1/folders ``` Returns all folders in your workspace (flat list with parent references for hierarchy). **Example** ```bash theme={null} curl -H "Authorization: Bearer " \ "https://app.cleve.ai/api/v1/folders" ``` *** ### Create a Folder ```http theme={null} POST /api/v1/folders ``` **Body** (JSON) | Field | Type | Required | Description | | ---------- | ------ | -------- | ---------------------------- | | `name` | string | ✅ | Folder name | | `parentId` | string | | Parent folder ID for nesting | **Example** ```bash theme={null} curl -X POST \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"name": "Research"}' \ "https://app.cleve.ai/api/v1/folders" ``` **Response** ```json theme={null} { "folderId": "def456" } ``` *** ### Rename a Folder ```http theme={null} PATCH /api/v1/folders/:folderId ``` **Body** (JSON) | Field | Type | Required | Description | | ------ | ------ | -------- | --------------- | | `name` | string | ✅ | New folder name | *** ### Delete a Folder ```http theme={null} 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: ```json theme={null} { "error": "Note not found" } ``` ## Related Connect AI agents to Cleve via the Model Context Protocol. API access is available on all plans.