Content

Update a single post

Changed on

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. Title, slug, markdown, or metadata updates also sync an existing linked GitHub pull request; no new pull request is created. 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}

Request

  • Base URL: https://api.usenotra.com
  • URL: https://api.usenotra.com/v1/posts/{postId}
  • Auth: HTTP bearer

Path parameters

postIdstring required
Example:post_123

Request body

titlestring
slugstring nullable
markdownstring
status'draft' | 'published'

Example request

{
  "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,
    "hidden": true,
    "displayDate": "2026-10-01"
  }
}

Response

Post updated successfully

Example response

{
  "post": {
    "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"
        }
      ],
      "displayDate": "2026-10-01"
    }
  }
}

Changes

  • a3f7b00e98f4Revision changes
    • info

      added the new optional request property /

    • info

      added the required property // to the response with the status

  • 582e7defd842Revision changes
    • info

      added the new optional request property

    • info

      added the required property / to the response with the status