# POST `/api/v1/articles`

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

**Create an article**

Creates an article from Markdown. Content is converted to the editor's document model. Scope: help_center:write (editor or owner token).

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

## Authentication

Authentication:
  - `apiToken` — HTTP BEARER

## Parameters

- `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:

- `title` — string — required
- `sectionTitle` — string — Target section, created if missing.
- `contentMarkdown` — string

## Responses

### 201 — Created article with resolved slug.

- `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.

- `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/94775d99-7940-4977-b2f9-b4eacc945472
Generated from the `Buuk Public API` reference for `buuk`.