Skip to main content
Talk to salesStart

Create note journal

Create a named research journal linked to lead, company, or Deal records. A journal groups dated notes; creating it does not schedule research.

POST/api/notes/journals
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.

  • 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.

  • 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