---
title: "Update a post by ID"
method: PUT
path: "/v1/posts/{postId}"
tags: ["posts"]
---

# Update a post by ID

`PUT /v1/posts/{postId}`

Update an existing post in your publication. The publication is identified by the API key provided in the Authorization header.

**Behavior:**
- Only provided fields are updated; omitted fields remain unchanged
- When `markdown` is provided, it replaces the full content. Rich blocks (embeds, buttons, callouts) created in the editor will be lost — the markdown to editor conversion is lossy for blocks without a markdown equivalent
- Set `status` to `"published"` to publish a draft, `"draft"` to unpublish, or `"archived"` to archive

## Path parameters

- `postId` string, required

## Request body

- object
  - `markdown` string — Post content in Markdown format. Replaces full content — rich blocks created in the editor will be lost
  - `title` string — Title of the post
  - `subtitle` string — Optional subtitle or brief summary
  - `slug` string — URL-friendly identifier for the post
  - `postPreview` string — Preview text for the post
  - `categories` union — Category tags for the post. Can also be a comma-separated string.
    - string[]
    - string
  - `status` 'draft' | 'published' | 'archived' — Set to 'published' to publish, 'draft' to unpublish, or 'archived' to archive

## Response `200`

Post updated successfully

- object
  - `success` true, required — Whether the update succeeded

## Other responses

- `400` — Invalid request - check field values
- `401` — Invalid or missing API key
- `404` — Post not found in your publication
- `500` — Internal server error

## Changes

- **2026-03-20** `5b9472285686` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/paragraph-xyz/apis/paragraph-api/changes/v1/posts/:postId/put.md)

---

[API](https://skmtc.dev/paragraph-xyz/apis/paragraph-api.md) · [All operations](https://skmtc.dev/paragraph-xyz/apis/paragraph-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/paragraph-xyz/paragraph-api/revisions/f633fb4fbb86/schema)