---
title: "Add a note"
description: "A note of up to 20,000 characters at one level, usually ready within a second or two."
url: "https://openemail.uk/docs/api/knowledge/notes"
area: "API"
category: "Mailbox"
---

# Add a note

A note of up to 20,000 characters at one level, usually ready within a second or two.

`POST /knowledge/notes`

## 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**

```
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 }'
```

**Response**

```
{
  "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.

## Reference

- [`POST /knowledge/notes`](https://openemail.uk/docs/api/reference/knowledge#post-knowledge-notes): full reference