# Article documents

> The Tiptap JSON body that create_article, update_article and the other X Article actions read and write, and how versions prevent lost edits.

Source: https://docs.xholic.ai/api/articles/

X Articles (Pro plan and up) are edited as a **Tiptap / ProseMirror JSON document**, the same format the Xholic editor uses.

```json
{
  "type": "doc",
  "content": [
    { "type": "heading", "attrs": { "level": 2 }, "content": [{ "type": "text", "text": "Why we rebuilt onboarding" }] },
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "We cut setup from " },
        { "type": "text", "marks": [{ "type": "bold" }], "text": "nine steps to three" },
        { "type": "text", "text": "." }
      ]
    },
    {
      "type": "bulletList",
      "content": [
        { "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "One question per screen" }] }] }
      ]
    }
  ]
}
```

- Every node has a `type`, and may have `attrs`, `marks` (each with a `type`) and `content`.
- The root is always `{ "type": "doc" }`. A document is at most about 1.5 MB of JSON, with up to 2,000 children per node.
- The safest way to edit is to read the article (`articles.get`), change the returned `document`, and send it back whole. Images in the body are uploaded article assets; keep the image nodes the editor produced.

## Versions

Every article has a `version`. `update_article`, `schedule_article` and `publish_article` take the version you last read and return the new one. If someone changed the article in the meantime, the call fails with `CONFLICT` instead of overwriting their edit: read it again and reapply your change.

## Typical flow

1. `create_article` with a title. It returns the new article with its `id` and `version`.
2. `update_article` with `id`, `version`, and `title`, `subtitle` or `document`.
3. `schedule_article` with a time and timezone, or `publish_article` to post it on X now (both need the `publish` scope).

Writing the article itself is your AI's job. Xholic's own article AI (`articles.ai_run`, for outlines, drafts and covers) uses Xholic AI credits and [quotes them first](/api/credits/).