REST API¶

ALMa exposes a single REST API rooted at /api/v1/. The same FastAPI app serves the API and the SPA, so in dev you'll hit http://localhost:8000/api/v1/... and in production whatever hostname your reverse proxy is binding to.

Authentication¶

By default there is no authentication — ALMa is a single-user local tool.

You can require an API key by setting the API_KEY environment variable. When set, every request must include a header:

X-API-Key: <your key>

Set API_KEY if you're exposing ALMa beyond 127.0.0.1 (for example through a reverse proxy or Tailscale). It does not create user accounts — it gates the entire API behind a shared secret.

Base URL¶

Response envelope¶

Most endpoints return JSON directly — a list of objects, a single object, or a status payload.

Long-running operations return an Activity envelope instead:

{
  "job_id": "f3b2…",
  "status": "queued",
  "message": "Refresh started; track progress in Activity."
}

When you see this envelope, the work is happening in the scheduler worker. Track it via GET /api/v1/activity/{job_id} or watch the Activity panel in the UI. See Background jobs.

Errors¶

Errors use standard HTTP status codes with a JSON body:

{ "detail": "Paper not found" }

Long traces and unexpected errors are written to the application log and surfaced in Activity → Logs.

Live API explorer¶

The full OpenAPI spec is rendered below. Expand any operation to see its parameters, request body, and example responses, then Try it out to send a real request against the documented base URL.

Endpoints by domain¶

A curated overview. The Swagger explorer above is authoritative for parameters and response shapes.

Library — saved papers and curation¶

Library imports¶

Paper PDFs¶

Every paper can carry one kept PDF. Fetching, attaching and importing are Activity jobs (the response is the envelope; follow /activity/{job_id}); the PDF's state is the pdf block of GET /papers/{id}/details (stored, file_missing, url, attempts). Sources come from pdf_source plugins — see Building an integration.

Library management¶

Inbox capture¶

Papers you send yourself from another device. The sweep normally runs on a timer; these exist so the loop is observable and forceable. See Inbox.

Triage uses the canonical paper-action route: POST /papers/{id}/action with {"action": "defer", "surface": "inbox"} for the ✕ (leaves the Inbox writing no rating and no feedback event), or add / like / love / dislike for the rest.

Feed¶

Discovery¶

Discovery lenses¶

Authors¶

Feedback learning¶

Insights & Reports¶

Alerts¶

Alert responses carry last_outcome (worst status of the latest evaluation batch) and next_due_at (next sweep-eligible slot; null for manual or disabled digests). Rule configs are validated per type at create/update — a config that would match nothing returns 422. Delivery dedup (alerted_publications) is keyed per (alert, paper, channel).

AI¶

Activity & operations¶

Both stop verbs close the row outright when its worker is already gone (process restart or crash), and both put a 24-hour cooldown on the operation when the run was a background one — so the app's own schedulers don't undo your stop. The response then carries an automation_paused block, and POST /health/operations/{key}/resume lifts the hold. Stopping a run you launched yourself changes no policy. Full rules: Background jobs → Who may restart a job.

Operation rows that participate in a chained workflow (e.g. Library save → metadata hydrate → S2 vector fetch → local SPECTER2 fill) carry two grouping fields:

• chain_id — uuid hex shared by every member of the chain.
• chain_step — one of hydrate, s2_fetch, local_specter2_fill.

The Activity panel groups all rows sharing a chain_id under the member with the lowest chain_step rank (the starter), with the remaining steps rendered as children inside one envelope. | GET | /scheduler/status | Scheduler health + next runs | | POST | /scheduler/trigger/{job_id} | Manually trigger a scheduled job | | GET | /logs | Application log ring buffer |

Settings¶

Other¶

Browser connector (extension)¶

Endpoints the Firefox connector talks to. GET /extension/ping is a pure-read handshake that also returns an instance identity payload — {profile, db_fingerprint} — so the connector can bind an offline-queued capture to a specific database and deliver it only when the same instance answers (it never slips into the wrong DB). Captures are ingested through the single canonical path, POST /extension/save.

OpenAPI artefact¶

The raw OpenAPI 3 document is bundled with these docs at /openapi.json. Generate a fresh copy from a running instance with:

curl -s http://localhost:8000/openapi.json > docs/openapi.json

Or offline, from inside the Python environment:

from alma.api.app import app
import json
print(json.dumps(app.openapi(), indent=2))