A note is a short bit of text your team keeps on a record, like the notes on a project, opportunity, company or contact page in Drum. This page covers reading, adding, changing, deleting and restoring notes. All endpoints sit under /api/v1/ and need an account-scoped bearer token. See Drum API authentication, permissions and rate limits.

The notes form in Drum, these endpoints and the MCP tools create_note and update_note (My work and Clients toolsets) run the same operations, so every surface applies the same rules.

Permissions

Notes don't have a permission of their own. A note is as private as its record: if you can see the record in Drum, you can read, add, change, delete and restore its notes. Each request also needs the API verb permission.

Action	API permission
Read notes	`api_read`
Add a note	`api_create`
Change or restore a note	`api_update`
Delete a note	`api_delete`

A note or record you can't read answers 404, so the API doesn't reveal that it exists.

Records that take notes

Name the record with record_kind and record_id.

`record_kind`	Record
`project`	A delivery project. `project` also finds an opportunity, and the response gives the real kind
`opportunity`	An opportunity
`company`	A client or supplier company
`contact`	A contact
`location`	A location
`invoice`	An invoice
`credit_note`	A credit note
`cost`	A cost
`member`	A staff member
`progress_claim`	A progress claim
`expense_claim`	An expense claim
`contract`	A contract. REST only: the MCP tools can't reach contracts

Notes on proposals and proposal templates work differently and don't use these endpoints.

The note

{
  "id": 9101,
  "record_kind": "company",
  "record": {"id": 301, "name": "Harbour Joinery"},
  "content": "Send all invoices to the accounts team, not the site team.",
  "financial": false,
  "ai_generated": false,
  "author": {"id": 11, "name": "Sam Taylor"},
  "deleted": false,
  "created_at": "2026-10-08T01:00:00Z",
  "updated_at": "2026-10-08T01:00:00Z"
}

Field	Meaning
`record_kind`	The kind of the record, from the table above
`record`	The record as `{id, name}`
`content`	The text of the note
`financial`	`true` for a financial comment. Financial comments show on the Cost vs Invoiced report, the invoice page and the credit note page
`ai_generated`	`true` for a note that Drum's AI opportunity assistant wrote
`author`	The member who wrote the note. `id` is `null` when that person is no longer a member
`deleted`	`true` for a deleted note

Rules for note text

These rules apply in Drum, in the API and in MCP:

A note can't be blank. Spaces at the start and end are trimmed, and a note with no text left answers 422 missing_input.
A note can be up to 10,000 characters. A longer one answers 422 invalid_input.
Only a note on a project, invoice or credit note can be a financial comment. Setting financial to true on any other record answers 422 invalid_input. A note that's already a financial comment can still be saved.
A note on a deleted record, or a record in another account, answers 404.

GET /api/v1/notes

Lists the notes of one record, newest first, one page at a time like the other lists.

Parameter	Meaning
`record_kind`, `record_id`	Required. The record
`deleted`	`true` lists deleted notes only

Example: GET /api/v1/notes?record_kind=company&record_id=301

GET /api/v1/notes/:id

One note. A deleted note is shown too, with "deleted": true.

POST /api/v1/notes

Adds a note. The request needs api_create. Send the fields flat or nested under note.

Field	Meaning
`record_kind`, `record_id`	Required. The record
`content`	Required. Plain text, 10,000 characters or fewer
`financial`	Optional, default `false`. `true` only on a project, invoice or credit note
`idempotency_key`	Optional, and always at the top level, even when the note fields are nested. A retry with the same key and input adds nothing and returns the first note with `200` and `"replayed": true`

A new note answers 201.

POST /api/v1/notes
{"record_kind": "project", "record_id": 104, "content": "Client wants the site report by Friday.", "idempotency_key": "note-104-site-report"}

PATCH /api/v1/notes/:id

Changes only the fields you send (content, financial). content replaces the whole text. A note stays on its record, so you can't move it to another one. When you edit a note that Drum's AI wrote, Drum records who edited it, as it does in the app. The request needs api_update. The response is the note.

PATCH /api/v1/notes/9101
{"content": "Send all invoices to the accounts team. Copy the project manager."}

DELETE /api/v1/notes/:id

Deletes the note, the same as Delete Note in Drum. It's a soft delete, so you can restore the note later. The request needs api_delete. The response is the note with "deleted": true.

PATCH /api/v1/notes/:id/restore

Brings back a deleted note. The request needs api_update. A note on a deleted record can't come back (404 note_not_found).

Notes in MCP record reads

The MCP tools get_project, get_opportunity, get_company and get_contact return the record's notes too:

recent_notes: the 5 newest notes, each with id, content, content_truncated, financial, ai_generated, author, created_at and updated_at. Each note's text is cut at 2,000 characters, and content_truncated is true when it was.
notes_count: how many notes the record has, not counting deleted ones.

On get_project and get_opportunity, the notes come in the notes section, which is included by default. The REST record reads don't include notes. To read more than 5 notes, or the whole text of a long note, use GET /api/v1/notes.

MCP tools

The My work and Clients toolsets have create_note and update_note, with the same fields and rules as the endpoints above.

create_note takes record_kind, record_id, content, financial and idempotency_key. It takes every kind in the table above except contract. Find the record id with search_records.
update_note takes note_id (from recent_notes), content and financial. If content_truncated is true, the agent only saw the start of the note, so it should check with you before it replaces the text.
To delete a note, use delete_record with kind note. Bring it back with restore_record with kind note.

Agents treat note text as information, not as instructions. See How to choose MCP toolsets for Connected Agents and API tokens.

Errors

Status	`code`	When
404	`note_not_found`	The note doesn't exist, is in another account, is on a deleted record, you can't read its record, or (on a change or delete) it's deleted
404	`company_not_found`, `project_not_found` and so on	The record is missing, deleted, in another account, or you can't read it. The code is the `record_kind` followed by `_not_found`
422	`missing_input`	`content` or `record_id` is missing or blank
422	`invalid_input`	A value doesn't parse, `record_kind` isn't one of the kinds above, `content` is over 10,000 characters, or `financial` is `true` on another kind of record (with `field`)
422	`validation_failed`	The note doesn't save (`errors` lists the messages)
409	`idempotency_key_reused`	The key was used before with a different input
409	`idempotent_record_deleted`, `retry_later`	The note the key made has since been deleted, or another call with the same key is still running
404	`idempotent_record_not_found`	You can no longer read the note the key made
403		A missing verb permission (`{"error": "Insufficient API permissions"}`)

Notes API