{"openapi":"3.1.0","info":{"title":"Cleve REST API","version":"1.0.0","summary":"Read and write notes and folders in a Cleve workspace.","description":"Cleve is an AI workspace and knowledge base. It keeps your notes, docs, voice notes and ideas in one place and lets you chat with AI models that have the full context of everything you have saved.\n\nThis API reads and writes the notes and folders in the workspace that the API key belongs to. Create a personal API key in Cleve under Settings → Developer and send it as `Authorization: Bearer <key>`.\n\nEvery success response wraps its payload in `{ \"data\": ... }`. Every error response is JSON with `error` (a human-readable message), `code` (a stable machine-readable code), `hint` (how to fix it) and `docs`.\n\nFor agents, the Cleve MCP server at https://app.cleve.ai/mcp exposes the same workspace as tools with OAuth sign-in.","termsOfService":"https://www.cleve.ai/terms","contact":{"name":"Cleve support","email":"support@cleve.ai","url":"https://docs.cleve.ai/developers/api"}},"servers":[{"url":"https://app.cleve.ai/api/v1","description":"Production"}],"externalDocs":{"description":"Cleve REST API guide","url":"https://docs.cleve.ai/developers/api"},"tags":[{"name":"Notes","description":"Markdown notes in the workspace."},{"name":"Folders","description":"Folders that group notes."}],"security":[{"bearerAuth":[]}],"paths":{"/notes":{"get":{"operationId":"listNotes","summary":"List notes","description":"Lists notes in the workspace, newest first. `content` is a short plain-text preview; call getNote for the full body.","tags":["Notes"],"parameters":[{"name":"folderId","in":"query","required":false,"description":"Only include notes in this folder.","schema":{"type":"string"}},{"name":"pinnedOnly","in":"query","required":false,"description":"When `true`, return only pinned notes.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"The notes.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NoteSummary"}}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createNote","summary":"Create a note","description":"Creates a note from a title and a Markdown body. Returns the new note's ID.","tags":["Notes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteCreate"}}}},"responses":{"201":{"description":"The note was created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["noteId"],"properties":{"noteId":{"type":"string"}}}}}}}},"400":{"description":"The request is invalid. `error` says which field is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/notes/count":{"get":{"operationId":"countNotes","summary":"Count notes","description":"Returns how many notes the workspace holds, and how many are pinned.","tags":["Notes"],"parameters":[{"name":"folderId","in":"query","required":false,"description":"Only include notes in this folder.","schema":{"type":"string"}}],"responses":{"200":{"description":"The counts.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/NoteCount"}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/notes/recent":{"get":{"operationId":"listRecentNotes","summary":"List recently updated notes","description":"Lists the most recently updated notes.","tags":["Notes"],"parameters":[{"name":"limit","in":"query","required":false,"description":"How many notes to return.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}],"responses":{"200":{"description":"The notes.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NoteSummary"}}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/notes/search":{"get":{"operationId":"searchNotes","summary":"Search notes","description":"Full-text search across note titles and bodies. Use searchNotesWithBody when the query has characters that are awkward to URL-encode.","tags":["Notes"],"parameters":[{"name":"query","in":"query","required":true,"description":"Search terms.","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"folderId","in":"query","required":false,"description":"Only include notes in this folder.","schema":{"type":"string"}},{"name":"isPinned","in":"query","required":false,"description":"Filter by pinned state.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Matching notes, best match first.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Note"}}}}}}},"400":{"description":"The request is invalid. `error` says which field is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"searchNotesWithBody","summary":"Search notes (JSON body)","description":"Same as searchNotes, with the search sent as a JSON body instead of query parameters.","tags":["Notes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteSearch"}}}},"responses":{"200":{"description":"Matching notes, best match first.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Note"}}}}}}},"400":{"description":"The request is invalid. `error` says which field is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/notes/{noteId}":{"get":{"operationId":"getNote","summary":"Get a note","description":"Returns one note with its full content and metadata.","tags":["Notes"],"parameters":[{"name":"noteId","in":"path","required":true,"description":"Note ID, as returned by listNotes, searchNotes or createNote (`_id` / `noteId`).","schema":{"type":"string"}}],"responses":{"200":{"description":"The note.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Note"}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The note or folder does not exist, or this key cannot reach it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateNote","summary":"Update a note","description":"Updates a note. Every field is optional. `content` replaces the whole body; `title` alone rewrites only the title.","tags":["Notes"],"parameters":[{"name":"noteId","in":"path","required":true,"description":"Note ID, as returned by listNotes, searchNotes or createNote (`_id` / `noteId`).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteUpdate"}}}},"responses":{"200":{"description":"The note was updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Success"}}}}}},"400":{"description":"The request is invalid. `error` says which field is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteNote","summary":"Delete a note","description":"Permanently deletes a note. This cannot be undone.","tags":["Notes"],"parameters":[{"name":"noteId","in":"path","required":true,"description":"Note ID, as returned by listNotes, searchNotes or createNote (`_id` / `noteId`).","schema":{"type":"string"}}],"responses":{"200":{"description":"The note was deleted.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Success"}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/notes/{noteId}/publish":{"post":{"operationId":"publishNote","summary":"Publish a note","description":"Publishes a note to the public web so anyone with its link can read it.","tags":["Notes"],"parameters":[{"name":"noteId","in":"path","required":true,"description":"Note ID, as returned by listNotes, searchNotes or createNote (`_id` / `noteId`).","schema":{"type":"string"}}],"responses":{"200":{"description":"The note is published.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Success"}}}}}},"400":{"description":"The request is invalid. `error` says which field is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"unpublishNote","summary":"Unpublish a note","description":"Takes a published note off the public web.","tags":["Notes"],"parameters":[{"name":"noteId","in":"path","required":true,"description":"Note ID, as returned by listNotes, searchNotes or createNote (`_id` / `noteId`).","schema":{"type":"string"}}],"responses":{"200":{"description":"The note is no longer published.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Success"}}}}}},"400":{"description":"The request is invalid. `error` says which field is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/folders":{"get":{"operationId":"listFolders","summary":"List folders","description":"Lists every folder in the workspace as a flat list. Nesting is given by `parentId`.","tags":["Folders"],"responses":{"200":{"description":"The folders.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Folder"}}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createFolder","summary":"Create a folder","description":"Creates a folder, optionally inside another folder. Returns the new folder's ID.","tags":["Folders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderCreate"}}}},"responses":{"201":{"description":"The folder was created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["folderId"],"properties":{"folderId":{"type":"string"}}}}}}}},"400":{"description":"The request is invalid. `error` says which field is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/folders/{folderId}":{"patch":{"operationId":"renameFolder","summary":"Rename a folder","description":"Renames a folder.","tags":["Folders"],"parameters":[{"name":"folderId","in":"path","required":true,"description":"Folder ID, as returned by listFolders or createFolder.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderUpdate"}}}},"responses":{"200":{"description":"The folder was renamed.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Success"}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteFolder","summary":"Delete a folder","description":"Deletes a folder. Its notes and subfolders move up one level; they are not deleted.","tags":["Folders"],"parameters":[{"name":"folderId","in":"path","required":true,"description":"Folder ID, as returned by listFolders or createFolder.","schema":{"type":"string"}}],"responses":{"200":{"description":"The folder was deleted.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Success"}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal API key from Cleve → Settings → Developer, sent as `Authorization: Bearer <key>`."}},"schemas":{"Error":{"type":"object","description":"Every error response has this shape.","required":["error","code","hint","docs"],"properties":{"error":{"type":"string","description":"Human-readable message.","examples":["Note not found"]},"code":{"type":"string","description":"Stable machine-readable error code.","enum":["bad_request","unauthorized","forbidden","not_found","method_not_allowed","internal_error"]},"hint":{"type":"string","description":"How to resolve the error."},"docs":{"type":"string","format":"uri","description":"Where to read more."}}},"Success":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","const":true}}},"NoteKind":{"type":"string","enum":["note","memory","welcome","imported"],"description":"`memory` notes hold what Cleve remembers about you; `imported` notes came from an import."},"NoteSummary":{"type":"object","required":["_id","_creationTime","content","isPinned","updatedAt"],"properties":{"_id":{"type":"string","description":"Note ID."},"_creationTime":{"type":"number","description":"Creation time, milliseconds since the Unix epoch."},"userId":{"type":"string","description":"ID of the note's owner."},"title":{"type":"string"},"content":{"type":"string","description":"Plain-text preview of the body."},"kind":{"$ref":"#/components/schemas/NoteKind"},"isPinned":{"type":"boolean"},"isPublic":{"type":"boolean","description":"Whether link sharing is on."},"isPublished":{"type":"boolean","description":"Whether the note is published to the web."},"publishedAt":{"type":"number","description":"Publish time, milliseconds since the Unix epoch."},"folderId":{"type":"string","description":"Folder the note is in, if any."},"updatedAt":{"type":"number","description":"Last update, milliseconds since the Unix epoch."},"orgId":{"type":"string","description":"Workspace ID."}}},"Note":{"description":"A note with its full plain-text content.","allOf":[{"$ref":"#/components/schemas/NoteSummary"},{"type":"object","properties":{"content":{"type":"string","description":"Full plain-text body."},"permission":{"type":"string","enum":["owner","editor","viewer"],"description":"What the caller may do with the note."},"canManageSharing":{"type":"boolean"}}}]},"NoteCount":{"type":"object","required":["total","pinned"],"properties":{"total":{"type":"integer","minimum":0},"pinned":{"type":"integer","minimum":0}}},"NoteCreate":{"type":"object","properties":{"title":{"type":"string","description":"Note title."},"content":{"type":"string","description":"Note body as Markdown."},"folderId":{"type":"string","description":"Folder to create the note in."},"isPinned":{"type":"boolean","description":"Pin the note."}},"examples":[{"title":"Meeting notes","content":"## Agenda\n\n- Item 1"}]},"NoteUpdate":{"type":"object","properties":{"title":{"type":"string","description":"New title."},"content":{"type":"string","description":"New body as Markdown. Replaces the whole body."},"isPinned":{"type":"boolean"},"isPublic":{"type":"boolean","description":"Turn link sharing on or off."},"folderId":{"type":["string","null"],"description":"Move to this folder, or `null` to unfile."}},"examples":[{"isPinned":true}]},"NoteSearch":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":1},"limit":{"type":"integer","minimum":1,"maximum":100},"folderId":{"type":"string"},"isPinned":{"type":"boolean"}},"examples":[{"query":"product roadmap","limit":5}]},"Folder":{"type":"object","required":["_id","_creationTime","name"],"properties":{"_id":{"type":"string","description":"Folder ID."},"_creationTime":{"type":"number","description":"Creation time, milliseconds since the Unix epoch."},"userId":{"type":"string","description":"ID of the folder's owner."},"name":{"type":"string"},"parentId":{"type":"string","description":"Parent folder ID. Absent for top-level folders."},"isPublic":{"type":"boolean"},"isPublished":{"type":"boolean"},"publishedAt":{"type":"number"},"orgId":{"type":"string","description":"Workspace ID."}}},"FolderCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1},"parentId":{"type":"string","description":"Create the folder inside this folder."}},"examples":[{"name":"Research"}]},"FolderUpdate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1}},"examples":[{"name":"Renamed folder"}]}}}}