Add a note
A note of up to 20,000 characters at one level, usually ready within a second or two.
Runs the real call on your workspace.
POST /knowledge/notes
A note of up to 20,000 characters at one level, usually ready within a second or two.
Example
Needs knowledge:write. title is up to 200 characters and body up to 20,000, in Markdown if you like. Leave scope out for the whole workspace. pinned puts the note into every prompt at its level, up to 2,000 characters of pinned notes from each level. Answers 201 with the note.
curl -X POST "$OE/knowledge/notes" -H "$AUTH" -H "Content-Type: application/json" \ -d '{ "scope": "@acme.com", "title": "Refunds", "body": "Refunds are paid within 14 days of the return reaching our warehouse.", "pinned": true }'{ "object": "knowledge_item", "id": "kb_8c1f4a2b9d7e3f60a5c7b21d", "kind": "note", "scope": "@acme.com", "level": "domain", "title": "Refunds", "url": null, "fileName": null, "mimeType": null, "sizeBytes": null, "pinned": true, "status": "ready", "failure": null, "chunks": 1, "chars": 71, "origin": "api", "createdBy": "usr_5f2a9c71", "createdAt": "2026-10-08T09:12:44.000Z", "updatedAt": "2026-10-08T09:12:44.000Z", "indexedAt": "2026-10-08T09:12:45.000Z"}Changing an item needs reach over every address its level covers: the whole workspace needs every address, a domain needs the whole domain, and an address needs that address. A key or an app limited to particular addresses can change items only at those addresses, or at domains it holds whole.
A level that is not the workspace, one of its domains or one of its addresses is a 422 invalid_knowledge_scope, and one outside what the key reaches a 403 knowledge_scope_not_reached. Sending the same request twice adds two notes.