Jump to

Manage Notes

CRUD endpoints for organization-wide notes. Scoped agents see only notes they have been granted access to; human callers (Clerk JWT) and admin API keys see every note in the org.

Create note POST

POST /notes

Create a new note. created_by is stamped server-side from the auth context — any client-supplied value is rejected.

Agent creator (scoped API key): a per-identity access row is auto-inserted, making the note immediately visible to that agent. Other agents cannot see it until granted.
Human creator (JWT or admin key): no access row is inserted. The note stays invisible to all scoped agents until an admin grants them.

Request body

Field	Type	Required	Description
`title`	string \| null	No	Short title (max 255 chars)
`body`	string	Yes	Note body (1–100000 chars, stored byte-for-byte)

Request example

JSON

Response (201)

JSON

Error responses

Status	Description
422	Body too long, or client sent `created_by` (rejected by `extra: forbid`)

Code examples

List notes GET

GET /notes

List notes visible to the caller.

Query parameters

Parameter	Type	Default	Description
`q`	string	—	Full-text search over title + body, max 200 chars
`identity_id`	UUID	—	Filter to notes granted to this identity
`limit`	integer	50	1–200
`offset`	integer	0	Offset for pagination
`order`	string	`recent`	`"recent"` (updated_at desc) or `"created"` (created_at desc)

Response (200)

Returns an array of note objects with inlined access arrays.

Code examples

Get note GET

GET /notes/{note_id}

Fetch a single note by ID.

Path parameters

Parameter	Type	Description
`note_id`	UUID	Note ID

Code examples

Update note PATCH

PATCH /notes/{note_id}

Update a note. Any caller who can see the note can patch it.

Path parameters

Parameter	Type	Description
`note_id`	UUID	Note ID

Request body

Field	Type	Required	Description
`title`	string \| null	No	Omit to leave unchanged, send `null` to clear, or send a string to set
`body`	string	No	Omit to leave unchanged, or send a new body. Sending `null` is not a legal operation (body is required) — returns 422.

created_by, organization_id, status, and timestamps are immutable.

Code examples

Delete note DELETE

DELETE /notes/{note_id}

Delete a note. Returns 204 No Content on success. Any caller who can see the note can delete it.

Code examples

Note object

Field	Type	Description
`id`	UUID	Unique note identifier
`organization_id`	string	Owning organization
`created_by`	string	Opaque creator stamp (user ID or identity ID). Immutable, server-populated.
`title`	string \| null	Optional short title
`body`	string	Note body (required, 1–100000 chars)
`status`	string	`active` or `deleted`
`created_at`	string	ISO 8601
`updated_at`	string	ISO 8601
`access`	object[]	Inlined access rules. Empty for human-created notes until granted; single-element for agent creators; more entries after admin grants.