Update a note

PATCH

notes

{note_id}

Update a note

curl --request PATCH \
  --url https://api.valendata.com/v1/notes/{note_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "find": "| Tobi | 12,000 | owes |",
  "replace_with": "| Tobi | 12,000 | paid |"
}
'

import requests

url = "https://api.valendata.com/v1/notes/{note_id}"

payload = {
    "find": "| Tobi | 12,000 | owes |",
    "replace_with": "| Tobi | 12,000 | paid |"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({find: '| Tobi | 12,000 | owes |', replace_with: '| Tobi | 12,000 | paid |'})
};

fetch('https://api.valendata.com/v1/notes/{note_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.valendata.com/v1/notes/{note_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'find' => '| Tobi | 12,000 | owes |',
    'replace_with' => '| Tobi | 12,000 | paid |'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.valendata.com/v1/notes/{note_id}"

	payload := strings.NewReader("{\n  \"find\": \"| Tobi | 12,000 | owes |\",\n  \"replace_with\": \"| Tobi | 12,000 | paid |\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.valendata.com/v1/notes/{note_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"find\": \"| Tobi | 12,000 | owes |\",\n  \"replace_with\": \"| Tobi | 12,000 | paid |\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.valendata.com/v1/notes/{note_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"find\": \"| Tobi | 12,000 | owes |\",\n  \"replace_with\": \"| Tobi | 12,000 | paid |\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3b9e6f2a-1c4d-4e8f-9a7b-5d2c0e1f8a6b",
  "title": "Dinner split 27 Sep",
  "body": "| Who | Owes | Status |\n| --- | --- | --- |\n| Ada | 12,000 | paid |\n| Tobi | 12,000 | paid |",
  "topic": "Money",
  "tags": [
    "dinner",
    "split"
  ],
  "pinned": true,
  "source": "api",
  "created_at": "2026-10-10T09:00:00Z",
  "updated_at": "2026-10-10T09:30:00Z",
  "link": "/notes/3b9e6f2a-1c4d-4e8f-9a7b-5d2c0e1f8a6b"
}

{
  "detail": "The request is malformed: the body is not JSON, the cursor or Idempotency-Key is not valid.",
  "code": "invalid_json",
  "type": "invalid_request_error",
  "request_id": "3f9a1c2b7d4e"
}

{
  "detail": "The API key is missing, malformed, revoked, or expired.",
  "code": "unauthorized",
  "type": "authentication_error",
  "request_id": "3f9a1c2b7d4e"
}

{
  "detail": "The key lacks a scope, is limited to other skills or workflows, or you may not do this.",
  "code": "permission_denied",
  "type": "permission_error",
  "request_id": "3f9a1c2b7d4e"
}

{
  "detail": "It does not exist, or it is not yours to see.",
  "code": "not_found",
  "type": "invalid_request_error",
  "request_id": "3f9a1c2b7d4e"
}

{
  "detail": "A conflict with the current state, or a request with this Idempotency-Key is still running.",
  "code": "conflict",
  "type": "conflict_error",
  "request_id": "3f9a1c2b7d4e"
}

{
  "detail": "Invalid request — name: Field required",
  "code": "validation_error",
  "type": "invalid_request_error",
  "request_id": "3f9a1c2b7d4e",
  "param": "name",
  "errors": [
    {
      "type": "missing",
      "loc": [
        "body",
        "name"
      ],
      "msg": "Field required"
    }
  ]
}

{
  "detail": "Too many requests for this key, or too many runs in progress. Wait `Retry-After` seconds.",
  "code": "rate_limited",
  "type": "rate_limit_error",
  "request_id": "3f9a1c2b7d4e"
}

{
  "detail": "Something broke on our side. Retry; runs that fail on our side are refunded.",
  "code": "internal_error",
  "type": "api_error",
  "request_id": "3f9a1c2b7d4e"
}

{
  "detail": "This part of the API is not available on the server right now. Retry later.",
  "code": "service_unavailable",
  "type": "api_error",
  "request_id": "3f9a1c2b7d4e"
}

The body changes one way per request:

body replaces all of it.
append adds text at the end. A list item or table row goes on the next line, anything else after a blank line.
find with replace_with changes one exact place, such as a table row. find must appear exactly once; otherwise nothing changes and you get 422. An empty replace_with removes the text.

title sets a new title. topic sets the topic, and an empty string clears it. tags replaces all the tags, and an empty list clears them. pinned pins or unpins the note. source never changes. The answer is the note as it is now. Read the note first with Get a note when you change one place, so find matches it exactly.

Status	Why
`403`	The key lacks `notes:write`.
`404`	No such note, or it is not yours.
`422`	Nothing to change, more than one way to change the body, `find` without `replace_with` (or the other way round), `find` not in the body or in it more than once, or the body would be longer than 20,000 characters.

MCP tool: update_note.

Authorizations

Authorization

string

header

required

API key with the vd_sk_ prefix, as Authorization: Bearer vd_sk_.... Create keys in Settings → API Keys.

Headers

Idempotency-Key

string

Any unique string (such as your order id). Resending the same request with the same key within 24 hours returns the first answer (with Idempotent-Replayed: true) and does nothing twice; the same key with a different request is a 422 idempotency_key_reused.

Required string length: 1 - 255

Path Parameters

note_id

string

required

Body

application/json

Only what is sent changes. The body changes one way per call: body (all of it), append (added at the end) or find + replace_with (one exact place).

title

string | null

A new title.

Required string length: 1 - 200

body

string | null

A new body: replaces all of it.

Maximum string length: 20000

append

string | null

Text to add at the end of the body: on the next line when it continues a list or a table, after a blank line otherwise.

Required string length: 1 - 20000

find

string | null

Exact text in the body to change, e.g. a whole table row. It must appear exactly once. Send with replace_with.

Required string length: 1 - 20000

replace_with

string | null

What find becomes; empty removes it.

Maximum string length: 20000

topic

string | null

A new topic; empty clears it.

Maximum string length: 64

Response

The note as it is now.

string

required

title

string

required

One line, at most 200 characters.

body

string

required

The note itself, in Markdown (tables and checklists work).

source

enum<string>

required

Who wrote it first: user (you, on the Notes page), igris (the assistant), session (a chat session's agent), brain (a workflow's Brain) or api (the API or an AI assistant you connected).

Available options:

user,

igris,

session,

brain,

api

link

string

required

The path of the note's page in the Valendata app, e.g. /notes/{id}.

topic

string | null

One short topic, e.g. 'Travel'; null when none.

tags

string[]

Short lowercase tags.

pinned

boolean

default:false

Pinned notes come first in the list.

created_at

string<date-time> | null

updated_at

string<date-time> | null

Update a note

curl --request PATCH \
  --url https://api.valendata.com/v1/notes/{note_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "find": "| Tobi | 12,000 | owes |",
  "replace_with": "| Tobi | 12,000 | paid |"
}
'

import requests

url = "https://api.valendata.com/v1/notes/{note_id}"

payload = {
    "find": "| Tobi | 12,000 | owes |",
    "replace_with": "| Tobi | 12,000 | paid |"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({find: '| Tobi | 12,000 | owes |', replace_with: '| Tobi | 12,000 | paid |'})
};

fetch('https://api.valendata.com/v1/notes/{note_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.valendata.com/v1/notes/{note_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'find' => '| Tobi | 12,000 | owes |',
    'replace_with' => '| Tobi | 12,000 | paid |'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.valendata.com/v1/notes/{note_id}"

	payload := strings.NewReader("{\n  \"find\": \"| Tobi | 12,000 | owes |\",\n  \"replace_with\": \"| Tobi | 12,000 | paid |\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.valendata.com/v1/notes/{note_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"find\": \"| Tobi | 12,000 | owes |\",\n  \"replace_with\": \"| Tobi | 12,000 | paid |\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.valendata.com/v1/notes/{note_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"find\": \"| Tobi | 12,000 | owes |\",\n  \"replace_with\": \"| Tobi | 12,000 | paid |\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3b9e6f2a-1c4d-4e8f-9a7b-5d2c0e1f8a6b",
  "title": "Dinner split 27 Sep",
  "body": "| Who | Owes | Status |\n| --- | --- | --- |\n| Ada | 12,000 | paid |\n| Tobi | 12,000 | paid |",
  "topic": "Money",
  "tags": [
    "dinner",
    "split"
  ],
  "pinned": true,
  "source": "api",
  "created_at": "2026-10-10T09:00:00Z",
  "updated_at": "2026-10-10T09:30:00Z",
  "link": "/notes/3b9e6f2a-1c4d-4e8f-9a7b-5d2c0e1f8a6b"
}

{
  "detail": "The request is malformed: the body is not JSON, the cursor or Idempotency-Key is not valid.",
  "code": "invalid_json",
  "type": "invalid_request_error",
  "request_id": "3f9a1c2b7d4e"
}

{
  "detail": "The API key is missing, malformed, revoked, or expired.",
  "code": "unauthorized",
  "type": "authentication_error",
  "request_id": "3f9a1c2b7d4e"
}

{
  "detail": "The key lacks a scope, is limited to other skills or workflows, or you may not do this.",
  "code": "permission_denied",
  "type": "permission_error",
  "request_id": "3f9a1c2b7d4e"
}

{
  "detail": "It does not exist, or it is not yours to see.",
  "code": "not_found",
  "type": "invalid_request_error",
  "request_id": "3f9a1c2b7d4e"
}

{
  "detail": "A conflict with the current state, or a request with this Idempotency-Key is still running.",
  "code": "conflict",
  "type": "conflict_error",
  "request_id": "3f9a1c2b7d4e"
}

{
  "detail": "Invalid request — name: Field required",
  "code": "validation_error",
  "type": "invalid_request_error",
  "request_id": "3f9a1c2b7d4e",
  "param": "name",
  "errors": [
    {
      "type": "missing",
      "loc": [
        "body",
        "name"
      ],
      "msg": "Field required"
    }
  ]
}

{
  "detail": "Too many requests for this key, or too many runs in progress. Wait `Retry-After` seconds.",
  "code": "rate_limited",
  "type": "rate_limit_error",
  "request_id": "3f9a1c2b7d4e"
}

{
  "detail": "Something broke on our side. Retry; runs that fail on our side are refunded.",
  "code": "internal_error",
  "type": "api_error",
  "request_id": "3f9a1c2b7d4e"
}

{
  "detail": "This part of the API is not available on the server right now. Retry later.",
  "code": "service_unavailable",
  "type": "api_error",
  "request_id": "3f9a1c2b7d4e"
}

Overview

Skills

Marketplace

Runs

Skill versions

Improvements

Schedules

Workflows

Logins

Connected apps

Follow-ups

Background jobs

Notes

Account and usage

Webhooks

Authorizations

Headers

Path Parameters

Body

Response