Create a note

POST

notes

Create a note

curl --request POST \
  --url https://api.valendata.com/v1/notes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Dinner split 27 Sep",
  "body": "| Who | Owes | Status |\n| --- | --- | --- |\n| Ada | 12,000 | paid |\n| Tobi | 12,000 | owes |",
  "topic": "Money",
  "tags": [
    "dinner",
    "split"
  ],
  "pinned": true
}
'

import requests

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

payload = {
    "title": "Dinner split 27 Sep",
    "body": "| Who | Owes | Status |
| --- | --- | --- |
| Ada | 12,000 | paid |
| Tobi | 12,000 | owes |",
    "topic": "Money",
    "tags": ["dinner", "split"],
    "pinned": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    title: 'Dinner split 27 Sep',
    body: JSON.stringify('| Who | Owes | Status |\n| --- | --- | --- |\n| Ada | 12,000 | paid |\n| Tobi | 12,000 | owes |'),
    topic: 'Money',
    tags: ['dinner', 'split'],
    pinned: true
  })
};

fetch('https://api.valendata.com/v1/notes', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'Dinner split 27 Sep',
    'body' => '| Who | Owes | Status |
| --- | --- | --- |
| Ada | 12,000 | paid |
| Tobi | 12,000 | owes |',
    'topic' => 'Money',
    'tags' => [
        'dinner',
        'split'
    ],
    'pinned' => true
  ]),
  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"

	payload := strings.NewReader("{\n  \"title\": \"Dinner split 27 Sep\",\n  \"body\": \"| Who | Owes | Status |\\n| --- | --- | --- |\\n| Ada | 12,000 | paid |\\n| Tobi | 12,000 | owes |\",\n  \"topic\": \"Money\",\n  \"tags\": [\n    \"dinner\",\n    \"split\"\n  ],\n  \"pinned\": true\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.valendata.com/v1/notes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"Dinner split 27 Sep\",\n  \"body\": \"| Who | Owes | Status |\\n| --- | --- | --- |\\n| Ada | 12,000 | paid |\\n| Tobi | 12,000 | owes |\",\n  \"topic\": \"Money\",\n  \"tags\": [\n    \"dinner\",\n    \"split\"\n  ],\n  \"pinned\": true\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"Dinner split 27 Sep\",\n  \"body\": \"| Who | Owes | Status |\\n| --- | --- | --- |\\n| Ada | 12,000 | paid |\\n| Tobi | 12,000 | owes |\",\n  \"topic\": \"Money\",\n  \"tags\": [\n    \"dinner\",\n    \"split\"\n  ],\n  \"pinned\": true\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 | owes |",
  "topic": "Money",
  "tags": [
    "dinner",
    "split"
  ],
  "pinned": true,
  "source": "api",
  "created_at": "2026-10-10T09:00:00Z",
  "updated_at": "2026-10-10T09:00: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": "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"
}

Give a title, a Markdown body, or both. Without a title, the body’s first line becomes it. topic, tags, and pinned are optional. Tags are kept lowercase, without a leading #, each once. The note is marked source: api. The answer is the note (201), with its id and link, its page in the app. Creating twice makes two notes, so send an Idempotency-Key to make a retry safe. See Idempotency.

Status	Why
`403`	The key lacks `notes:write`.
`422`	No title and no body, or a field is too long (`param` names it). See Limits.

MCP tool: create_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

Body

application/json

title

string

default:""

One line. Left out, the body's first line becomes the title. A title or a body is needed.

Maximum string length: 200

body

string

default:""

The note, in Markdown.

Maximum string length: 20000

topic

string | null

One short topic, e.g. 'Travel'.

Maximum string length: 64

Response

The note, saved on your Notes page.

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

Create a note

curl --request POST \
  --url https://api.valendata.com/v1/notes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Dinner split 27 Sep",
  "body": "| Who | Owes | Status |\n| --- | --- | --- |\n| Ada | 12,000 | paid |\n| Tobi | 12,000 | owes |",
  "topic": "Money",
  "tags": [
    "dinner",
    "split"
  ],
  "pinned": true
}
'

import requests

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

payload = {
    "title": "Dinner split 27 Sep",
    "body": "| Who | Owes | Status |
| --- | --- | --- |
| Ada | 12,000 | paid |
| Tobi | 12,000 | owes |",
    "topic": "Money",
    "tags": ["dinner", "split"],
    "pinned": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    title: 'Dinner split 27 Sep',
    body: JSON.stringify('| Who | Owes | Status |\n| --- | --- | --- |\n| Ada | 12,000 | paid |\n| Tobi | 12,000 | owes |'),
    topic: 'Money',
    tags: ['dinner', 'split'],
    pinned: true
  })
};

fetch('https://api.valendata.com/v1/notes', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'Dinner split 27 Sep',
    'body' => '| Who | Owes | Status |
| --- | --- | --- |
| Ada | 12,000 | paid |
| Tobi | 12,000 | owes |',
    'topic' => 'Money',
    'tags' => [
        'dinner',
        'split'
    ],
    'pinned' => true
  ]),
  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"

	payload := strings.NewReader("{\n  \"title\": \"Dinner split 27 Sep\",\n  \"body\": \"| Who | Owes | Status |\\n| --- | --- | --- |\\n| Ada | 12,000 | paid |\\n| Tobi | 12,000 | owes |\",\n  \"topic\": \"Money\",\n  \"tags\": [\n    \"dinner\",\n    \"split\"\n  ],\n  \"pinned\": true\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.valendata.com/v1/notes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"Dinner split 27 Sep\",\n  \"body\": \"| Who | Owes | Status |\\n| --- | --- | --- |\\n| Ada | 12,000 | paid |\\n| Tobi | 12,000 | owes |\",\n  \"topic\": \"Money\",\n  \"tags\": [\n    \"dinner\",\n    \"split\"\n  ],\n  \"pinned\": true\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"Dinner split 27 Sep\",\n  \"body\": \"| Who | Owes | Status |\\n| --- | --- | --- |\\n| Ada | 12,000 | paid |\\n| Tobi | 12,000 | owes |\",\n  \"topic\": \"Money\",\n  \"tags\": [\n    \"dinner\",\n    \"split\"\n  ],\n  \"pinned\": true\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 | owes |",
  "topic": "Money",
  "tags": [
    "dinner",
    "split"
  ],
  "pinned": true,
  "source": "api",
  "created_at": "2026-10-10T09:00:00Z",
  "updated_at": "2026-10-10T09:00: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": "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

Body

Response