---
title: POST /api/articles/[id]/notes
description: Add one typed note to the Brief — kind, title, optional body and url. createdBy is inferred from the principal. Backs scripto note add.
---

<Note>

The CLI equivalent is `scripto note add <id> --kind <kind> --title <t> [--url …] [--body …|--file …|--stdin]`.

</Note>

Adds one typed note to the [Brief](/concepts/brief). `createdBy` is inferred from the principal — a Bearer/CLI write is an `agent`; a web/session write is a `human`.

## Endpoint

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

## Auth

`Authorization: Bearer scripto_…`

## Request

| Field | Type | Meaning |
|---|---|---|
| `kind` | string | **Required.** One of `source`, `decision`, `idea`, `question`. |
| `title` | string | **Required**, non-empty. The note's short label. |
| `body` | string \| null | Optional Markdown detail. |
| `url` | string \| null | Optional link (mainly for sources). |

```json
{ "kind": "source", "title": "Medium import docs", "url": "https://help.medium.com/…" }
```

## Response (201)

```json
{
  "success": true,
  "data": {
    "note": { "anchor": "1a2b3c4d", "kind": "source", "title": "Medium import docs", "url": "https://…", "createdBy": "agent", "html": null },
    "notes": [ "… the fresh notes map …" ]
  }
}
```

## Errors

| HTTP | `code` | Cause | `nextAction` |
|---|---|---|---|
| 400 | `invalid-argument` | Unknown/missing `kind`. | Pass `--kind` with one of: source, decision, idea, question. |
| 400 | `invalid-argument` | Empty `title`, or wrong `body`/`url` type. | — |
| 404 | `not-found` | No such article, or you don't own it. | — |
| 401 | `unauthenticated` | Missing or invalid key. | — |

## curl

```bash
curl -sS -X POST "https://scripto.codika.io/api/articles/$ID/notes" \
  -H "Authorization: Bearer $SCRIPTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"decision","title":"Lead with the install","body":"Every answer starts with scripto <cmd>."}'
```

## Next

- **[PATCH .../notes/[nid]](/api-reference/update-note)** — edit a note.
- **[The Brief](/concepts/brief)** — note kinds and provenance.