Update a single post
curl --request PATCH \
--url https://api.usenotra.com/v1/posts/{postId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"title": "Ship notes for week 11",
"slug": "ship-notes-week-11",
"markdown": "# Ship notes\n\nWe shipped a faster editor.",
"status": "published",
"metadata": {
"coverImage": {
"url": "https://cdn.example.com/covers/ship-notes.png",
"alt": "Screenshot of the new editor"
},
"tags": [
"editor",
"performance"
],
"excerpt": "The editor now opens twice as fast on long posts.",
"authorIds": [
"auth_8f2kq1"
],
"featured": true,
"noindex": false,
"hidden": true,
"displayDate": "2026-10-01"
}
}
'import requests
url = "https://api.usenotra.com/v1/posts/{postId}"
payload = {
"title": "Ship notes for week 11",
"slug": "ship-notes-week-11",
"markdown": "# Ship notes
We shipped a faster editor.",
"status": "published",
"metadata": {
"coverImage": {
"url": "https://cdn.example.com/covers/ship-notes.png",
"alt": "Screenshot of the new editor"
},
"tags": ["editor", "performance"],
"excerpt": "The editor now opens twice as fast on long posts.",
"authorIds": ["auth_8f2kq1"],
"featured": True,
"noindex": False,
"hidden": True,
"displayDate": "2026-10-01"
}
}
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({
title: 'Ship notes for week 11',
slug: 'ship-notes-week-11',
markdown: '# Ship notes\n\nWe shipped a faster editor.',
status: 'published',
metadata: {
coverImage: {
url: 'https://cdn.example.com/covers/ship-notes.png',
alt: 'Screenshot of the new editor'
},
tags: ['editor', 'performance'],
excerpt: 'The editor now opens twice as fast on long posts.',
authorIds: ['auth_8f2kq1'],
featured: true,
noindex: false,
hidden: true,
displayDate: '2026-10-01'
}
})
};
fetch('https://api.usenotra.com/v1/posts/{postId}', 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.usenotra.com/v1/posts/{postId}",
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([
'title' => 'Ship notes for week 11',
'slug' => 'ship-notes-week-11',
'markdown' => '# Ship notes
We shipped a faster editor.',
'status' => 'published',
'metadata' => [
'coverImage' => [
'url' => 'https://cdn.example.com/covers/ship-notes.png',
'alt' => 'Screenshot of the new editor'
],
'tags' => [
'editor',
'performance'
],
'excerpt' => 'The editor now opens twice as fast on long posts.',
'authorIds' => [
'auth_8f2kq1'
],
'featured' => true,
'noindex' => false,
'hidden' => true,
'displayDate' => '2026-10-01'
]
]),
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.usenotra.com/v1/posts/{postId}"
payload := strings.NewReader("{\n \"title\": \"Ship notes for week 11\",\n \"slug\": \"ship-notes-week-11\",\n \"markdown\": \"# Ship notes\\n\\nWe shipped a faster editor.\",\n \"status\": \"published\",\n \"metadata\": {\n \"coverImage\": {\n \"url\": \"https://cdn.example.com/covers/ship-notes.png\",\n \"alt\": \"Screenshot of the new editor\"\n },\n \"tags\": [\n \"editor\",\n \"performance\"\n ],\n \"excerpt\": \"The editor now opens twice as fast on long posts.\",\n \"authorIds\": [\n \"auth_8f2kq1\"\n ],\n \"featured\": true,\n \"noindex\": false,\n \"hidden\": true,\n \"displayDate\": \"2026-10-01\"\n }\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.usenotra.com/v1/posts/{postId}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"title\": \"Ship notes for week 11\",\n \"slug\": \"ship-notes-week-11\",\n \"markdown\": \"# Ship notes\\n\\nWe shipped a faster editor.\",\n \"status\": \"published\",\n \"metadata\": {\n \"coverImage\": {\n \"url\": \"https://cdn.example.com/covers/ship-notes.png\",\n \"alt\": \"Screenshot of the new editor\"\n },\n \"tags\": [\n \"editor\",\n \"performance\"\n ],\n \"excerpt\": \"The editor now opens twice as fast on long posts.\",\n \"authorIds\": [\n \"auth_8f2kq1\"\n ],\n \"featured\": true,\n \"noindex\": false,\n \"hidden\": true,\n \"displayDate\": \"2026-10-01\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usenotra.com/v1/posts/{postId}")
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 \"title\": \"Ship notes for week 11\",\n \"slug\": \"ship-notes-week-11\",\n \"markdown\": \"# Ship notes\\n\\nWe shipped a faster editor.\",\n \"status\": \"published\",\n \"metadata\": {\n \"coverImage\": {\n \"url\": \"https://cdn.example.com/covers/ship-notes.png\",\n \"alt\": \"Screenshot of the new editor\"\n },\n \"tags\": [\n \"editor\",\n \"performance\"\n ],\n \"excerpt\": \"The editor now opens twice as fast on long posts.\",\n \"authorIds\": [\n \"auth_8f2kq1\"\n ],\n \"featured\": true,\n \"noindex\": false,\n \"hidden\": true,\n \"displayDate\": \"2026-10-01\"\n }\n}"
response = http.request(request)
puts response.read_body{
"organization": {
"id": "<string>",
"slug": "<string>",
"name": "<string>",
"logo": "<string>"
},
"post": {
"id": "<string>",
"title": "<string>",
"slug": "<string>",
"content": "<string>",
"htmlUrl": "<string>",
"markdown": "<string>",
"rawHtml": "<string>",
"recommendations": "<string>",
"contentType": "changelog",
"metadata": {
"coverImage": {
"url": "https://cdn.example.com/covers/ship-notes.png",
"alt": "Screenshot of the new editor"
},
"tags": [
"editor",
"performance"
],
"excerpt": "The editor now opens twice as fast on long posts.",
"authors": [
{
"id": "auth_8f2kq1",
"slug": "jane-doe",
"name": "Jane Doe",
"title": "Head of Product",
"avatarUrl": "https://cdn.example.com/avatars/jane.png",
"url": "https://janedoe.dev",
"x": "https://x.com/janedoe",
"linkedin": "<string>",
"github": "<string>",
"youtube": "<string>",
"bluesky": "<string>",
"mastodon": "<string>",
"threads": "<string>",
"instagram": "<string>"
}
],
"featured": false,
"noindex": false,
"hidden": false,
"displayDate": "2026-10-01"
},
"status": "draft",
"createdAt": "<string>",
"updatedAt": "<string>",
"sourceMetadata": "<unknown>"
}
}{
"error": "<string>",
"code": "<string>",
"recovery": "<string>"
}{
"error": "<string>",
"code": "<string>",
"recovery": "<string>"
}{
"error": "<string>",
"code": "<string>",
"recovery": "<string>"
}{
"error": "<string>",
"code": "<string>",
"recovery": "<string>"
}{
"error": "<string>",
"code": "<string>",
"recovery": "<string>"
}{
"error": "<string>",
"limit": 2,
"remaining": 1,
"reset": 123
}{
"error": "<string>",
"code": "<string>",
"recovery": "<string>"
}{
"error": "<string>",
"code": "<string>",
"recovery": "<string>"
}{
"error": "<string>",
"code": "<string>",
"recovery": "<string>"
}Update a single post
Updates any combination of title, slug, markdown, status, and metadata. Sending markdown re-renders the stored HTML, and when title is omitted it is taken from the first heading in the markdown, keeping the existing title when the markdown has no heading. Slugs and metadata are only accepted for blog posts and changelogs. Inside metadata, send only the fields you want to change; tags and authorIds replace the stored list, and authorIds must come from GET /v1/posts/authors. A blog post that publishes to a Notra Sites site can also credit that site's authors as site:<id>, the ref from GET /v1/sites/{siteId}/authors. Title, slug, markdown, or metadata updates also sync a post linked to GitHub: an open pull request gets a new commit, and a repository set to publish directly gets a direct commit when its live branch allows one (unprotected, file unchanged on GitHub). Otherwise, including closed or merged pull requests, GitHub is left as is and no new pull request is opened; the post is still saved. GitHub sync errors occur after saving the post: 429 includes Retry-After, 502 indicates a sync error, and 504 indicates an unknown sync outcome. Check the PR before retrying an unconfirmed sync.
PATCH
/
v1
/
posts
/
{postId}
Update a single post
curl --request PATCH \
--url https://api.usenotra.com/v1/posts/{postId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"title": "Ship notes for week 11",
"slug": "ship-notes-week-11",
"markdown": "# Ship notes\n\nWe shipped a faster editor.",
"status": "published",
"metadata": {
"coverImage": {
"url": "https://cdn.example.com/covers/ship-notes.png",
"alt": "Screenshot of the new editor"
},
"tags": [
"editor",
"performance"
],
"excerpt": "The editor now opens twice as fast on long posts.",
"authorIds": [
"auth_8f2kq1"
],
"featured": true,
"noindex": false,
"hidden": true,
"displayDate": "2026-10-01"
}
}
'import requests
url = "https://api.usenotra.com/v1/posts/{postId}"
payload = {
"title": "Ship notes for week 11",
"slug": "ship-notes-week-11",
"markdown": "# Ship notes
We shipped a faster editor.",
"status": "published",
"metadata": {
"coverImage": {
"url": "https://cdn.example.com/covers/ship-notes.png",
"alt": "Screenshot of the new editor"
},
"tags": ["editor", "performance"],
"excerpt": "The editor now opens twice as fast on long posts.",
"authorIds": ["auth_8f2kq1"],
"featured": True,
"noindex": False,
"hidden": True,
"displayDate": "2026-10-01"
}
}
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({
title: 'Ship notes for week 11',
slug: 'ship-notes-week-11',
markdown: '# Ship notes\n\nWe shipped a faster editor.',
status: 'published',
metadata: {
coverImage: {
url: 'https://cdn.example.com/covers/ship-notes.png',
alt: 'Screenshot of the new editor'
},
tags: ['editor', 'performance'],
excerpt: 'The editor now opens twice as fast on long posts.',
authorIds: ['auth_8f2kq1'],
featured: true,
noindex: false,
hidden: true,
displayDate: '2026-10-01'
}
})
};
fetch('https://api.usenotra.com/v1/posts/{postId}', 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.usenotra.com/v1/posts/{postId}",
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([
'title' => 'Ship notes for week 11',
'slug' => 'ship-notes-week-11',
'markdown' => '# Ship notes
We shipped a faster editor.',
'status' => 'published',
'metadata' => [
'coverImage' => [
'url' => 'https://cdn.example.com/covers/ship-notes.png',
'alt' => 'Screenshot of the new editor'
],
'tags' => [
'editor',
'performance'
],
'excerpt' => 'The editor now opens twice as fast on long posts.',
'authorIds' => [
'auth_8f2kq1'
],
'featured' => true,
'noindex' => false,
'hidden' => true,
'displayDate' => '2026-10-01'
]
]),
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.usenotra.com/v1/posts/{postId}"
payload := strings.NewReader("{\n \"title\": \"Ship notes for week 11\",\n \"slug\": \"ship-notes-week-11\",\n \"markdown\": \"# Ship notes\\n\\nWe shipped a faster editor.\",\n \"status\": \"published\",\n \"metadata\": {\n \"coverImage\": {\n \"url\": \"https://cdn.example.com/covers/ship-notes.png\",\n \"alt\": \"Screenshot of the new editor\"\n },\n \"tags\": [\n \"editor\",\n \"performance\"\n ],\n \"excerpt\": \"The editor now opens twice as fast on long posts.\",\n \"authorIds\": [\n \"auth_8f2kq1\"\n ],\n \"featured\": true,\n \"noindex\": false,\n \"hidden\": true,\n \"displayDate\": \"2026-10-01\"\n }\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.usenotra.com/v1/posts/{postId}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"title\": \"Ship notes for week 11\",\n \"slug\": \"ship-notes-week-11\",\n \"markdown\": \"# Ship notes\\n\\nWe shipped a faster editor.\",\n \"status\": \"published\",\n \"metadata\": {\n \"coverImage\": {\n \"url\": \"https://cdn.example.com/covers/ship-notes.png\",\n \"alt\": \"Screenshot of the new editor\"\n },\n \"tags\": [\n \"editor\",\n \"performance\"\n ],\n \"excerpt\": \"The editor now opens twice as fast on long posts.\",\n \"authorIds\": [\n \"auth_8f2kq1\"\n ],\n \"featured\": true,\n \"noindex\": false,\n \"hidden\": true,\n \"displayDate\": \"2026-10-01\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usenotra.com/v1/posts/{postId}")
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 \"title\": \"Ship notes for week 11\",\n \"slug\": \"ship-notes-week-11\",\n \"markdown\": \"# Ship notes\\n\\nWe shipped a faster editor.\",\n \"status\": \"published\",\n \"metadata\": {\n \"coverImage\": {\n \"url\": \"https://cdn.example.com/covers/ship-notes.png\",\n \"alt\": \"Screenshot of the new editor\"\n },\n \"tags\": [\n \"editor\",\n \"performance\"\n ],\n \"excerpt\": \"The editor now opens twice as fast on long posts.\",\n \"authorIds\": [\n \"auth_8f2kq1\"\n ],\n \"featured\": true,\n \"noindex\": false,\n \"hidden\": true,\n \"displayDate\": \"2026-10-01\"\n }\n}"
response = http.request(request)
puts response.read_body{
"organization": {
"id": "<string>",
"slug": "<string>",
"name": "<string>",
"logo": "<string>"
},
"post": {
"id": "<string>",
"title": "<string>",
"slug": "<string>",
"content": "<string>",
"htmlUrl": "<string>",
"markdown": "<string>",
"rawHtml": "<string>",
"recommendations": "<string>",
"contentType": "changelog",
"metadata": {
"coverImage": {
"url": "https://cdn.example.com/covers/ship-notes.png",
"alt": "Screenshot of the new editor"
},
"tags": [
"editor",
"performance"
],
"excerpt": "The editor now opens twice as fast on long posts.",
"authors": [
{
"id": "auth_8f2kq1",
"slug": "jane-doe",
"name": "Jane Doe",
"title": "Head of Product",
"avatarUrl": "https://cdn.example.com/avatars/jane.png",
"url": "https://janedoe.dev",
"x": "https://x.com/janedoe",
"linkedin": "<string>",
"github": "<string>",
"youtube": "<string>",
"bluesky": "<string>",
"mastodon": "<string>",
"threads": "<string>",
"instagram": "<string>"
}
],
"featured": false,
"noindex": false,
"hidden": false,
"displayDate": "2026-10-01"
},
"status": "draft",
"createdAt": "<string>",
"updatedAt": "<string>",
"sourceMetadata": "<unknown>"
}
}{
"error": "<string>",
"code": "<string>",
"recovery": "<string>"
}{
"error": "<string>",
"code": "<string>",
"recovery": "<string>"
}{
"error": "<string>",
"code": "<string>",
"recovery": "<string>"
}{
"error": "<string>",
"code": "<string>",
"recovery": "<string>"
}{
"error": "<string>",
"code": "<string>",
"recovery": "<string>"
}{
"error": "<string>",
"limit": 2,
"remaining": 1,
"reset": 123
}{
"error": "<string>",
"code": "<string>",
"recovery": "<string>"
}{
"error": "<string>",
"code": "<string>",
"recovery": "<string>"
}{
"error": "<string>",
"code": "<string>",
"recovery": "<string>"
}Authorizations
Send your API key in the Authorization header as Bearer API_KEY. Account API keys work in every workspace you belong to: send X-Notra-Organization-Id with the workspace id or slug to choose one. Workspace endpoints require it when you belong to more than one workspace; GET /v1/me/workspaces works without it. Organization keys only accept their own workspace there.
Path Parameters
Body
application/json
Was this page helpful?