---
title: POST /api/articles/[id]/sections
description: Insert one Markdown body (which may itself split into several sections) at a chosen place, by anchor. Backs scripto section add.
---

<Note>

The CLI equivalent is `scripto section add <id> --file part.md [--after|--before <anchor>]`.

</Note>

Inserts one Markdown body — which may itself split into several sections if it has multiple headings — at a chosen place. With neither `after` nor `before`, the section is appended.

## Endpoint

```text
POST https://scripto.codika.io/api/articles/{id}/sections
```

## Auth

`Authorization: Bearer scripto_…`

## Request

| Field | Type | Meaning |
|---|---|---|
| `markdown` | string | **Required**, non-empty. The section body. |
| `after` | string (anchor) | Optional. Insert after this section. |
| `before` | string (anchor) | Optional. Insert before this section. |

Pass at most one of `after` / `before`. An anchor is any unique prefix of a section id (see the [outline](/api-reference/get-outline)).

```json
{ "markdown": "## Findings\n\nText…", "after": "a1b2c3d4" }
```

## Response (201)

```json
{
  "success": true,
  "data": {
    "added": [ { "anchor": "9c8d7e6f", "level": 2, "title": "Findings", "words": 14, "source": "markdown" } ],
    "outline": [ "… the full fresh outline …" ]
  }
}
```

`added` is the outline of the new section(s); `outline` is the article's full fresh outline.

## Errors

| HTTP | `code` | Cause | `nextAction` |
|---|---|---|---|
| 400 | `invalid-argument` | Empty `markdown`; both `after` and `before`; or a wrong type. | Pass the body as `markdown`. |
| 400 | `invalid-argument` | The anchor is ambiguous. | Use a longer anchor. |
| 404 | `not-found` | No such article, or no section matches the anchor. | Call GET /outline for current anchors. |
| 401 | `unauthenticated` | Missing or invalid key. | — |

## curl

```bash
curl -sS -X POST "https://scripto.codika.io/api/articles/$ID/sections" \
  -H "Authorization: Bearer $SCRIPTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown":"## Findings\n\nText…","after":"a1b2c3d4"}'
```

## Next

- **[GET .../sections/[sid]](/api-reference/get-section)** — read one section.
- **[POST .../sections/[sid]/move](/api-reference/move-section)** — reorder.