API overview
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.
For almost everything, the scripto CLI 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.
Base URL
https://scripto.codika.ioAll routes live under /api. There is no URL versioning.
The envelope
Every data route returns a discriminated envelope, paired with an appropriate HTTP status:
{ "success": true, "data": { "…": "…" } }{ "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 |
POST /api/cli/login-complete | scripto auth login-complete | CLI auth |
GET /api/auth/me | scripto whoami | whoami |
GET /api/articles | scripto articles list | list |
POST /api/articles | (part of articles create) | create |
GET /api/articles/[id] | scripto articles get | get |
PATCH /api/articles/[id] | scripto articles update | update |
DELETE /api/articles/[id] | — | delete |
GET /api/articles/[id]/outline | scripto outline | outline |
POST /api/articles/[id]/publish | scripto articles publish | publish |
POST /api/articles/import | scripto articles import | import |
POST /api/articles/[id]/sections | scripto section add | add section |
GET /api/articles/[id]/sections/[sid] | scripto section get | get section |
PATCH /api/articles/[id]/sections/[sid] | scripto section set | update section |
DELETE /api/articles/[id]/sections/[sid] | scripto section rm | delete section |
POST /api/articles/[id]/sections/[sid]/move | scripto section mv | move section |
GET /api/articles/[id]/brief | scripto brief | get brief |
PATCH /api/articles/[id]/brief | scripto brief --premise | set premise |
GET /api/articles/[id]/notes | scripto note list | list notes |
POST /api/articles/[id]/notes | scripto note add | add note |
GET /api/articles/[id]/notes/[nid] | scripto note get | get note |
PATCH /api/articles/[id]/notes/[nid] | scripto note set | update note |
DELETE /api/articles/[id]/notes/[nid] | scripto note rm | delete note |
GET /api/keys | — (web Settings) | list keys |
POST /api/keys | — (web Settings) | create key |
DELETE /api/keys/[id] | — (web Settings) | revoke key |
POST /api/upload | — | upload image |
GET /api/unfurl | — | unfurl |
Next
- Authentication — the Bearer header.
- CLI auth (OTP) — the public provisioning routes.