Update note - Autotouch AI

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.

Path parameters

note_idrequired
string
Exact note ID returned by create or list.

Name	Type	Description
note_idrequired	string	Exact note ID returned by create or list.

Body parameters

expected_versionrequired
integer
Required current version from GET. A stale version returns 409; reread and reconcile before issuing a fresh write key.
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.
title · optional
string | null
Non-empty title, at most 300 characters.
content · optional
object | null
{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 | null
general (default), meeting, or research_update. Independent of the types of linked records.
related_records · optional
array | null
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 | null
Up to 100 {url,title?,observed_at?} evidence references; HTTP(S) URLs only. The server does not fetch these URLs.
pinned · optional
boolean | null
Whether the note is pinned. Default false.
archived · optional
boolean | null
For PATCH, archive or restore the note. For list, select archived notes (default false selects active notes). Archived notes remain readable by exact ID and retain history.

Name	Type	Description
expected_versionrequired	integer	Required current version from GET. A stale version returns 409; reread and reconcile before issuing a fresh write key.
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.
title	string \| null	Non-empty title, at most 300 characters.
content	object \| null	{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	string \| null	general (default), meeting, or research_update. Independent of the types of linked records.
related_records	array \| null	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	string \| null	Optional research journal ID in this organization. On update, null detaches the note.
observed_at	string \| null	Optional ISO 8601 timestamp of the research observation; distinct from server creation time. Null clears it on update.
sources	array \| null	Up to 100 {url,title?,observed_at?} evidence references; HTTP(S) URLs only. The server does not fetch these URLs.
pinned	boolean \| null	Whether the note is pinned. Default false.
archived	boolean \| null	For PATCH, archive or restore the note. For list, select archived notes (default false selects active notes). Archived notes remain readable by exact ID and retain history.

Errors

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

Example

bash

curl -X PATCH "https://app.autotouch.ai/api/notes/note_example" \
  -H "Authorization: Bearer $AUTOTOUCH_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"expected_version": 1, "pinned": true, "idempotency_key": "pin-note-2026-10-02"}'

Request body

json

{
  "expected_version": 1,
  "pinned": true,
  "idempotency_key": "pin-note-2026-10-02"
}

Response example

json

{
  "note": {
    "id": "note_example",
    "organization_id": "org_example",
    "title": "Platform hiring update",
    "content": {
      "format": "markdown",
      "markdown": "Three new platform roles appeared.",
      "blocks": null
    },
    "kind": "research_update",
    "related_records": [
      {
        "entity_type": "company",
        "entity_id": "company_example"
      }
    ],
    "journal_id": null,
    "observed_at": "2026-10-02T09:00:00Z",
    "sources": [],
    "pinned": true,
    "version": 2,
    "revision_id": "nrev_updated",
    "archived": false,
    "author_id": "user_example",
    "author_kind": "api_key",
    "created_at": "2026-10-02T09:04:00Z",
    "updated_at": "2026-10-02T09:04:00Z",
    "provenance": {}
  },
  "replayed": false
}