# PATCH `/api/v1/articles/{idOrSlug}`

> Part of the `Buuk Public API` API reference.

**Update an article**

Partially updates an article; an idempotent way to publish content turns Markdown. Scope: help_center:write. Publishes may additionally require editorial approval (403 approval_required).

Base URL: `https://app.getbuuk.com`

## Authentication

Authentication:
  - `apiToken` — HTTP BEARER

## Parameters

- `idOrSlug` — string (path, required) — Article UUID or slug.
- `Idempotency-Key` — string (header, optional) — Optional client-generated unique key (max 255 chars, e.g. a UUID). Retrying with the same key and body within 24 hours replays the original response (with `Idempotent-Replayed: true`) instead of repeating the write.
- `Buuk-Version` — string (header, optional) — API version to use. Omit for the current version (1). Unsupported values return 400 unsupported_api_version.

## Request body

Content type: `application/json`

Request body:

- `slug` — string
- `title` — string
- `status` — string — enum: "draft" | "published" | "archived"
- `visibility` — string — enum: "everywhere" | "unlisted" | "hidden" | "ai_only"
- `contentMarkdown` — string

## Responses

### 200 — Updated article.

- `article` — object
- `id` — string·uuid
- `url` — string
- `kind` — string — enum: "help" | "guide" | "faq"
- `slug` — string
- `title` — string
- `status` — string — enum: "draft" | "published" | "archived"
- `updatedAt` — string·date-time
- `visibility` — string
- `publishedAt` — string·date-time
- `contentMarkdown` — string — Full article body as Markdown.

### 400 — Validation failed — see details.

- `error` — string — required — Stable machine-readable error code, e.g. unauthorized, forbidden, invalid_request, not_found, rate_limited.
- `details` — object — Field-level validation failures, present only for invalid_request.
- `message` — string — Human-readable problem description.

### 401 — Missing or invalid token.

- `error` — string — required — Stable machine-readable error code, e.g. unauthorized, forbidden, invalid_request, not_found, rate_limited.
- `details` — object — Field-level validation failures, present only for invalid_request.
- `message` — string — Human-readable problem description.

### 403 — Token lacks help_center:write, or editorial approval is required before this article can be published (403 approval_required).

- `error` — string — required — Stable machine-readable error code, e.g. unauthorized, forbidden, invalid_request, not_found, rate_limited.
- `details` — object — Field-level validation failures, present only for invalid_request.
- `message` — string — Human-readable problem description.

### 404 — No article matches that id or slug.

- `error` — string — required — Stable machine-readable error code, e.g. unauthorized, forbidden, invalid_request, not_found, rate_limited.
- `details` — object — Field-level validation failures, present only for invalid_request.
- `message` — string — Human-readable problem description.

### 409 — A request with this Idempotency-Key is still in progress (idempotency_key_in_use).

- `error` — string — required — Stable machine-readable error code, e.g. unauthorized, forbidden, invalid_request, not_found, rate_limited.
- `details` — object — Field-level validation failures, present only for invalid_request.
- `message` — string — Human-readable problem description.

### 422 — Idempotency-Key was already used with a different request (idempotency_key_reused).

- `error` — string — required — Stable machine-readable error code, e.g. unauthorized, forbidden, invalid_request, not_found, rate_limited.
- `details` — object — Field-level validation failures, present only for invalid_request.
- `message` — string — Human-readable problem description.

### 429 — Rate limit exceeded. Retry-After header carries the wait in seconds.

- `error` — string — required — Stable machine-readable error code, e.g. unauthorized, forbidden, invalid_request, not_found, rate_limited.
- `details` — object — Field-level validation failures, present only for invalid_request.
- `message` — string — Human-readable problem description.

---

View in browser: /help/buuk/reference/1ab754df-6a63-44fc-a4e7-a3dbe7835bb3
Generated from the `Buuk Public API` reference for `buuk`.