Skip to main content
Talk to salesStart

Create note

Save one independent note linked to exact lead, company, or Deal IDs. For daily research, create a new dated research_update in a journal, preserving earlier findings. Sources are evidence URLs; provenance is server-owned.

POST/api/notes
Scope notes:writeUpdated October 15, 2026

This page documents the canonical HTTP contract. Switch to the CLI example when you want the operator workflow.

Notes and journals are independent, organization-shared resources. Identity, organization, author, timestamps, and harness provenance are server-owned. Developer keys need the endpoint scope; notes:write does not grant notes:read. These calls complete synchronously and do not consume research credits or start scheduled work.

For longitudinal research, create a journal once, then create a new research_update note per observation with journal_id, explicit related_records, observed_at, and sources. Journal links are independent of entry links. Lead, company, and Deal profiles link to their scoped Notes views. Use the existing Scheduled harness for recurrence; note creation itself does not schedule it.

Writes return {note,replayed} or {journal,replayed}. Retrying a committed write with the same key and input returns the resource's current state and replayed=true. Lists return bounded summaries and next_cursor; get and revision reads contain full content. Lists are ordered by created_at descending with ID as tie-breaker. Revision cursors are scoped to one note. DELETE /api/notes/{note_id} archives a note and preserves its revision history; no hard-delete endpoint is exposed. Failed write candidates are excluded from history.

Clients should preserve unknown BlockNote block data when editing; conversion between Markdown and BlockNote is not performed by the API. File uploads, collaborative editing, and revision restoration are not part of this API.

Body parameters

  • titlerequired

    string

    Non-empty title, at most 300 characters.

  • contentrequired

    object

    {format:"markdown",markdown:"..."} or {format:"blocknote",blocks:[...]}. Exactly one representation. At most 128 KB; complete note at most 192 KB. Bodies are stored as data; rendering clients must validate their editor schema and sanitize imported content.

  • kind · optional

    string

    general (default), meeting, or research_update. Independent of the types of linked records.

  • related_records · optional

    array

    Up to 32 unique {entity_type:"lead"|"company"|"deal",entity_id:string} links. Each record must exist in the authenticated organization. No implicit inheritance from a journal.

  • journal_id · optional

    string | null

    Optional research journal ID in this organization. On update, null detaches the note.

  • observed_at · optional

    string | null

    Optional ISO 8601 timestamp of the research observation; distinct from server creation time. Null clears it on update.

  • sources · optional

    array

    Up to 100 {url,title?,observed_at?} evidence references; HTTP(S) URLs only. The server does not fetch these URLs.

  • pinned · optional

    boolean

    Whether the note is pinned. Default false.

  • idempotency_keyrequired

    string

    Required 8-200 character key, scoped to the authenticated author and operation/resource. Reuse exactly the same payload on retry. Changed input with the same key returns 409.

Errors

StatusMeaning
401Missing or invalid authentication.
403Developer key lacks the required Notes scope.
404Note, journal, or linked record is unavailable in this organization.
409Stale expected_version or idempotency key reused with changed input.
422Invalid fields, content bounds, paired record filter, or cursor.

Docs