---
title: API overview
description: The Scripto HTTP API — base URL, the response envelope, error codes and statuses, per-user scoping, and the full endpoint index with matching CLI commands.
---

<Note>

For almost everything, the [`scripto` CLI](/cli/overview) is the right interface — it wraps these routes and handles auth, profiles, and the section loop for you. Use the HTTP API directly only when you genuinely can't run the CLI.

</Note>

## Base URL

```text
https://scripto.codika.io
```

All routes live under `/api`. There is no URL versioning.

## The envelope

Every data route returns a discriminated envelope, paired with an appropriate HTTP status:

```json
{ "success": true, "data": { "…": "…" } }
```

```json
{ "success": false, "error": { "code": "not-found", "message": "Article not found.", "nextAction": "Call GET /outline …" } }
```

The CLI decodes web and CLI responses identically against this contract. `nextAction` is an optional machine-readable hint — pass it through verbatim.

## Error codes

| `code` | HTTP | Meaning |
|---|---|---|
| `unauthenticated` | 401 | Missing or invalid key. |
| `invalid-argument` | 400 | Bad/missing field, ambiguous anchor, wrong type. |
| `not-found` | 404 | No such resource **or you don't own it** (no existence leak). |
| `internal` | 500 | Backend error — retry with backoff. |

## Per-user scoping

Every article, section, and note is scoped to the authenticated user. A resource you don't own returns **404, never 403** — Scripto never reveals that an id exists. This is identical across the session, Bearer-key, and OAuth auth paths.

## Endpoint index

| Method & path | CLI equivalent | Page |
|---|---|---|
| `POST /api/cli/login-request` | `scripto auth login-request` | [CLI auth](/api-reference/cli-auth) |
| `POST /api/cli/login-complete` | `scripto auth login-complete` | [CLI auth](/api-reference/cli-auth) |
| `GET /api/auth/me` | `scripto whoami` | [whoami](/api-reference/whoami) |
| `GET /api/articles` | `scripto articles list` | [list](/api-reference/list-articles) |
| `POST /api/articles` | (part of `articles create`) | [create](/api-reference/create-article) |
| `GET /api/articles/[id]` | `scripto articles get` | [get](/api-reference/get-article) |
| `PATCH /api/articles/[id]` | `scripto articles update` | [update](/api-reference/update-article) |
| `DELETE /api/articles/[id]` | — | [delete](/api-reference/delete-article) |
| `GET /api/articles/[id]/outline` | `scripto outline` | [outline](/api-reference/get-outline) |
| `POST /api/articles/[id]/publish` | `scripto articles publish` | [publish](/api-reference/publish-article) |
| `POST /api/articles/import` | `scripto articles import` | [import](/api-reference/import-article) |
| `POST /api/articles/[id]/sections` | `scripto section add` | [add section](/api-reference/add-section) |
| `GET /api/articles/[id]/sections/[sid]` | `scripto section get` | [get section](/api-reference/get-section) |
| `PATCH /api/articles/[id]/sections/[sid]` | `scripto section set` | [update section](/api-reference/update-section) |
| `DELETE /api/articles/[id]/sections/[sid]` | `scripto section rm` | [delete section](/api-reference/delete-section) |
| `POST /api/articles/[id]/sections/[sid]/move` | `scripto section mv` | [move section](/api-reference/move-section) |
| `GET /api/articles/[id]/brief` | `scripto brief` | [get brief](/api-reference/get-brief) |
| `PATCH /api/articles/[id]/brief` | `scripto brief --premise` | [set premise](/api-reference/set-premise) |
| `GET /api/articles/[id]/notes` | `scripto note list` | [list notes](/api-reference/list-notes) |
| `POST /api/articles/[id]/notes` | `scripto note add` | [add note](/api-reference/add-note) |
| `GET /api/articles/[id]/notes/[nid]` | `scripto note get` | [get note](/api-reference/get-note) |
| `PATCH /api/articles/[id]/notes/[nid]` | `scripto note set` | [update note](/api-reference/update-note) |
| `DELETE /api/articles/[id]/notes/[nid]` | `scripto note rm` | [delete note](/api-reference/delete-note) |
| `GET /api/keys` | — (web Settings) | [list keys](/api-reference/list-keys) |
| `POST /api/keys` | — (web Settings) | [create key](/api-reference/create-key) |
| `DELETE /api/keys/[id]` | — (web Settings) | [revoke key](/api-reference/revoke-key) |
| `POST /api/upload` | — | [upload image](/api-reference/upload-image) |
| `GET /api/unfurl` | — | [unfurl](/api-reference/unfurl) |

## Next

- **[Authentication](/api-reference/authentication)** — the Bearer header.
- **[CLI auth (OTP)](/api-reference/cli-auth)** — the public provisioning routes.