Skip to content
SonoraSonora API

Update a note

PATCH
/notes/{noteId}
curl --request PATCH \
  --url https://api.usesonora.com/v1/notes/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "title": "example", "contentMarkdown": "example" }'

Change the title or body of a note written through the API — by any of your workspace’s keys. A note someone wrote in Sonora is theirs to change: 403 note_not_editable. Send If-Match with the ETag you read to refuse the write if the note changed in between; without it, the last write wins.

Requires the notes:write scope. API keys only.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
noteId
required
string

The note’s Sonora id.

Header Parameters

Section titled “Header Parameters”
If-Match
string

The ETag from your last read. If the resource has changed since, nothing is written and the call answers 412 precondition_failed. Without it, the last write wins.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

What to change. A field you leave out is kept.

object
title

Shown as the note’s heading in Sonora.

string
>= 1 characters <= 255 characters
contentMarkdown

Replaces the whole body. To change part of it, read the note, edit its contentMarkdown and send it back.

string
<= 50000 characters
Examplegenerated
{
  "title": "example",
  "contentMarkdown": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

The note, as saved.

Media typeapplication/json

A note your team shares on a customer.

object
id
required
string
customerId
required
string
title
required
string
contentMarkdown
required

The note as Markdown: headings, lists, checklists, links and emphasis kept.

string
contentText
required

The note as plain text, for search or a preview.

string
author
required

Who wrote a note: a person on your team, or an API key — never the person who created the key.

object
type
required

user for a note someone wrote in Sonora; api_key for one written through the API.

string
Allowed values: user api_key
name
required

The person’s name, or the API key’s. Null for a key since deleted.

string | null
email
required

The person’s email. Always null for an API key.

string | null
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
links
required
object
self
required

This resource’s canonical URL on the API host.

string
Example
{
  "author": {
    "type": "user"
  }
}

Headers

Section titled “Headers”
ETag
string

A fingerprint of the note’s title and body. Send it back as If-Match to update only if neither has changed since.

400

Section titled “400”

invalid_json: The request body is not valid JSON.

invalid_request: A parameter or body field is missing, malformed or unknown; details.issues names each.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

401

Section titled “401”

unauthorized: The Authorization header is missing, or the key is invalid, revoked or expired.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

403

Section titled “403”

insufficient_scope: The key or token lacks the scope this endpoint needs, and details.required names it; or an OAuth access token called an endpoint only an API key can.

note_not_editable: The note was written by someone in Sonora. A key may change or delete only notes written through the API.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

404

Section titled “404”

note_not_found: No shared note with that id. Private notes are never found.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

412

Section titled “412”

precondition_failed: The resource changed since the ETag that If-Match names. Read it again, then retry.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

413

Section titled “413”

payload_too_large: The request body is too large; details.maxBytes gives the limit.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

429

Section titled “429”

rate_limited: Too many requests for this key; retry after Retry-After seconds.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

500

Section titled “500”

internal_error: Something went wrong on Sonora’s side. Retry, and quote requestId if it persists.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

Try it

Try it runs the reference's read endpoints, and this one changes data, so it needs an API key with the notes:write scope. Create a key in Sonora under Settings → API and call it from your own code.