---
title: "Manage articles with the API"
url: "/help/buuk/guides/manage-articles-with-the-api"
updated: "2026-11-15T11:35:29.988Z"
---
# Manage articles with the API

The public API creates and updates articles without the dashboard. It is the same API the CLI and MCP server use.

## Authenticate

Create a token in Settings → Developers → API tokens. Send it as a bearer token:

```bash
curl https://app.getbuuk.com/api/v1/articles \
  -H "authorization: Bearer buuk_cli_..."
```

Tokens are scoped to one workspace and carry a role. A viewer token can only read published articles; an editor token can write. Every write accepts an `Idempotency-Key` header, so a retried request doesn't create a second article.

## Create

```bash
curl -X POST https://app.getbuuk.com/api/v1/articles \
  -H "authorization: Bearer buuk_cli_..." \
  -H "content-type: application/json" \
  -d '{"title": "Reset a password", "sectionTitle": "Account", "contentMarkdown": "Open Settings, then..."}'
```

New articles start as drafts. The response returns the id and slug.

## Update

```bash
curl -X PATCH https://app.getbuuk.com/api/v1/articles/reset-a-password \
  -H "authorization: Bearer buuk_cli_..." \
  -H "content-type: application/json" \
  -d '{"contentMarkdown": "Open Settings → Security, then..."}'
```

`idOrSlug` accepts either. You can change the title, slug, body, status and visibility. Sending `contentMarkdown` replaces the whole body, so read before you write.

## Publish

Set `status` to `published` on the same PATCH. If the workspace requires editorial approval, an editor token can't publish an unapproved article; the request fails with `approval_required` and the article stays a draft.

## Revisions

Every write keeps a revision. `GET /api/v1/articles/{idOrSlug}/revisions` lists them, so an automated import can be audited or rolled back from the dashboard.

## Markdown

The API converts Markdown to the editor's blocks, including headings, lists, code, tables, callouts, accordions and tabs. Content that a block can't represent comes through as paragraphs, so check a converted page before publishing.