# Create an article

> POST /articles: Create an article

`POST https://usedocs.app/v1/articles`

Creates a draft. Publish it with POST /articles/{id}/publish.

```bash
curl -X POST "https://usedocs.app/v1/articles" \
  -H "Authorization: Bearer $USEDOCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Export invoices to CSV","contentMarkdown":"Open **Invoices**, then **Export**."}'
```

## Authentication

Bearer token (`content:write`): A workspace API key: ud_live_…

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `bot_id` | query | `string` |  | Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header. |

## Request body

Required, `application/json`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | Yes |  |
| `contentMarkdown` | `string` | Yes | The article in Markdown. |
| `slug` | `string` |  |  |
| `description` | `string` |  | One sentence for search results and the article's lead. |
| `collectionId` | `string | null` |  |  |
| `visibility` | `string` |  | One of: `public`, `authenticated`. |
| `locale` | `string` |  | Language code, e.g. en. Create only. |
| `position` | `integer` |  | Order within its collection in the sidebar (0 first). |

## Responses

| Status | Description |
| --- | --- |
| `201` | The new draft. |
| `400` | The request is missing something or has a bad value. |
| `401` | No API key, or the key is revoked. |
| `402` | The workspace is paused; reads still work. |
| `403` | A read key on a write, or a key for another bot. |
| `404` | Not found. |
| `429` | Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After. |

## Response fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `title` | `string` |  |
| `slug` | `string` |  |
| `status` | `string` | One of: `draft`, `in_review`, `published`, `archived`. |
| `description` | `string | null` |  |
| `collectionId` | `string | null` |  |
| `locale` | `string` |  |
| `visibility` | `string` | One of: `public`, `authenticated`. |
| `url` | `string | null` | The live page, when published. |
| `contentMarkdown` | `string` | With format=markdown (default). |
| `contentHtml` | `string` | With format=html. |
| `publishedAt` | `string | null` |  |
| `createdAt` | `string (date-time)` |  |
| `updatedAt` | `string (date-time)` |  |