MFannotWeb
···

HTTP API

The /api/v1 surface lets scripts and CLI clients submit, watch, and retrieve jobs. Submitting, watching and retrieving jobs as a signed-in user is available here; anonymous use and the admin pages are not, and stay on the web UI’s own routes.

Overview

Versioned routes live under /api/v1. They are the documented contract for programmatic clients. The unversioned /api/* endpoints (used by the web UI for cookie-authed multipart uploads) are not part of this contract and may change without notice.

All responses are JSON unless noted (event streams are SSE; downloads are binary). Timestamps are ISO 8601 in UTC.

Authentication

Two mechanisms are accepted on every /api/v1 route:

  • Session cookie (sid) — set by POST /api/auth/login from a browser. Cookie callers implicitly hold every scope.
  • Bearer token — Authorization: Bearer mfw_…. Tokens have a fixed scope set assigned at creation and cannot escalate.

Anonymous (no auth) calls only work against the legacy /api/jobs surface used by the web form; /api/v1 always requires authentication.

Scopes

Bearer tokens carry one or more scopes:

ScopeGrants
jobs:readList, fetch, log, events, results, download.
jobs:writeSubmit a new job.
jobs:cancelCancel a queued job.
tokens:manageList, create, revoke API tokens.

Cookie-authed identities return scopes: ["*"] from GET /api/v1. Treat "*" as “all scopes”.

Errors

Failures return a non-2xx status with a JSON body of three fields: detail, the message for people; code, a stable string to branch on instead of parsing the message; and context, the details a code promises (an empty object otherwise). For a 422 from request validation, detail is the list of field errors.

{
  "detail": "only queued jobs can be cancelled (this one is running); to stop a running job, restart the worker",
  "code": "cancellable_only_when_queued",
  "context": {"current_status": "running"}
}
CodeStatusWhen
validation_failed400, 422Bad parameters (gencode, base64, FASTA content, scope name, etc.).
unauthenticated401No valid cookie or bearer token supplied.
forbidden_scope403Token is valid but missing the required scope (context.required_scope).
forbidden403A cookie-authenticated change request from another site.
not_found404Job, token, or file does not exist (or is not yours).
method_not_allowed405The path exists but not for this HTTP method.
cancellable_only_when_queued409Cancel called on a running/done/failed job (context.current_status).
archive_not_ready409Download or manifest requested for a job that is not done.
conflict409Other conflicts with the current state, e.g. the token quota is reached.
archive_missing404Result archive is no longer on disk (deleted from disk).
payload_too_large413Request body over the size cap (context.max_bytes).
idempotency_mismatch422Idempotency-Key reused within 24 hours for a different request (context.job_id).
concurrency_limit_exceeded429Per-user in-flight cap reached (context.in_flight, context.limit).
rate_limit_exceeded429Per-principal rate limit tripped (context.bucket).
too_many_streams429The account already has the most event and log streams open at once (context.limit); close one and retry.
internal_error500The server could not complete the request.
queue_unavailable503The job queue is unreachable; nothing was submitted, retry.

Rate limits

Limits are keyed per principal (per token, per session, or per IP for the legacy surface).

EndpointLimit
POST /api/v1/jobs30 / hour, 5 / minute
POST /api/jobs (the web form’s legacy route, not part of /api/v1)10 / hour, 3 / minute (per IP)
POST /api/v1/jobs/{id}/cancel30 / minute
POST /api/v1/tokens5 / hour
POST /api/auth/signup5 / minute (per IP)
POST /api/auth/login10 / minute (per IP)

There is also a hard cap on concurrent in-flight jobs per user (default 3). Submitting beyond it returns 429 concurrency_limit_exceeded.

Identity & usage

GET /api/v1

Whoami. Returns the version and, if authenticated, the caller’s identity and scopes.

{
  "version": "1",
  "authenticated": true,
  "identity": {
    "id": 42,
    "email": "you@example.org",
    "role": "user",
    "auth_method": "token",
    "scopes": ["jobs:read", "jobs:write"]
  }
}

GET /api/v1/me/usage

How close you are to your concurrency cap and how many jobs you ran recently. Poll this instead of trying a submit and getting a 429.

{
  "concurrent_in_flight": 1,
  "concurrent_limit": 3,
  "jobs_last_24h": 7,
  "jobs_last_7d": 22,
  "ttl_days": 7
}

Pipeline discovery

The three endpoints in this group are unauthenticated and cacheable. Use them so your client never hard-codes lists that drift out of sync with the server.

GET /api/v1/pipelines

List of available pipelines and their required/optional parameters.

[
  {
    "kind": "mfannot",
    "description": "MFannot mitochondrial / plastid genome annotation",
    "required_params": ["gencode"],
    "optional_params": []
  },
  {
    "kind": "rnaweasel",
    "description": "RNA model search (RNAfinder + CMsearchWrapper for ssrA)",
    "required_params": ["gencode", "rna"],
    "optional_params": []
  }
]

GET /api/v1/pipelines/gencodes

Full NCBI gencode table. Maps the integer code to its human-readable name. Submissions with a value outside this set are rejected with 422 validation_failed.

{
  "1": "Standard",
  "2": "Vertebrate Mitochondrial",
  "3": "Yeast Mitochondrial",
  "4": "Mold, Protozoan, and Coelenterate Mitochondrial; Mycoplasma/Spiroplasma",
  "5": "Invertebrate Mitochondrial",
  "6": "Ciliate, Dasycladacean and Hexamita Nuclear",
  "9": "Echinoderm and Flatworm Mitochondrial",
  "10": "Euplotid nuclear",
  "11": "Bacterial, Archaeal and Plant plastid",
  "12": "Alternative Yeast Nuclear",
  "13": "Ascidian Mitochondrial",
  "14": "Alternative Flatworm Mitochondrial",
  "15": "Blepharisma Nuclear",
  "16": "Chlorophycean Mitochondrial",
  "21": "Trematode Mitochondrial",
  "22": "Scenedesmus Obliquus Mitochondrial",
  "23": "Thraustochytrium Mitochondrial"
}

GET /api/v1/pipelines/rnaweasel/models

RNA model names accepted by the rnaweasel rna parameter. The order of names, here or in a submission, makes no difference: the models other than ssrA are searched together, sorted by name, and ssrA, if requested, runs as a separate last step.

{
  "models": ["tRNA", "intronI", "intronII", "rnpB", "rrn5", "rns", "ssrA"]
}

Jobs

POST /api/v1/jobs

Submit a new job. JSON body — multipart uploads stay on the legacy /api/jobs route.

Body fields:

FieldTypeNotes
kindstringmfannot or rnaweasel.
gencodeintMust be present in the gencode table above.
rnastring[]Required for rnaweasel; ignored otherwise. Order does not matter; repeated names count once.
input_filenamestring1–255 chars. Kept as the name of the input file, and so of the outputs derived from it, after sanitising: any directory part is dropped, characters other than letters, digits, ., _ and - become _, leading dots go, and at most the last 100 characters are kept (input.fasta if nothing is left). Jobs return the sanitised name.
fastastringInline FASTA, at most 1,572,864 characters (1.5 MiB). Exactly one of fasta/fasta_b64.
fasta_b64stringBase64-encoded FASTA bytes, at most 2,097,152 characters (2 MiB); useful when escaping is awkward.

A fasta or fasta_b64 field over its character limit above is refused with 422. Those two limits are fixed in the code; they do not follow the server’s MAX_UPLOAD_BYTES setting, which limits the decoded FASTA (1 MiB by default). The FASTA is validated server-side and invalid input is rejected with 400. A record in which more than 5% of the sequence characters are not A C G T U N (whitespace, digits and ! are not counted) is rejected — e.g. a protein FASTA. Fewer such characters, e.g. IUPAC ambiguity codes, are removed from the sequence. At most 10,000 records per submission.

Optional header Idempotency-Key: <1–200 chars> de-dupes retries for 24 hours. Reusing a key with the same request returns the originally-created job; reusing it for a different request (another sequence, kind, gencode, RNA models or filename) is refused with 422 idempotency_mismatch. After 24 hours the key starts a new job.

Required scope: jobs:write. Returns 201 with a JobOutV1.

GET /api/v1/jobs

List the caller’s jobs (most recent 100, newest first). Required scope: jobs:read.

GET /api/v1/jobs/{id}

Fetch a single job. Returns 404 if the job does not exist or is not yours. Required scope: jobs:read.

POST /api/v1/jobs/{id}/cancel

Cancel a job that is still queued. Returns 409 if already running or terminal. Required scope: jobs:cancel.

Job object shape

{
  "id": "f8c1…",
  "kind": "mfannot",
  "status": "queued | running | done | failed | cancelled",
  "params": { "gencode": 4, "rna": [] },
  "input_filename": "mito.fasta",
  "created_at": "2026-05-14T19:02:11Z",
  "started_at": null,
  "finished_at": null,
  "error_msg": null,
  "links": {
    "self":     "/api/v1/jobs/f8c1…",
    "events":   "/api/v1/jobs/f8c1…/events",
    "log":      "/api/v1/jobs/f8c1…/log",
    "download": null,
    "results":  null,
    "cancel":   "/api/v1/jobs/f8c1…/cancel"
  }
}

links.download, links.results, and links.cancel are null when the corresponding action isn’t valid for the current status — clients should follow them rather than constructing URLs by hand.

Event stream

GET /api/v1/jobs/{id}/events

Server-Sent Events. Replays up to 500 lines of run.log and then tails live until the job reaches a terminal state. Required scope: jobs:read.

Event types emitted:

EventPayload
statusInitial snapshot: {"status": "...", "created_at": "..."}
log{"line": "..."} — one per line of pipeline output
stageA new pipeline stage has started: {"label": "..."}. When the label belongs to the job’s expected stage sequence it also carries index (1-based) and total, e.g. {"label": "tRNA", "index": 1, "total": 3}; otherwise only label is present.
substepProgress inside the current stage. The payload is an empty object.
doneTerminal success with download_url
errorTerminal failure (failed / cancelled) with error_msg

Keep-alive comments (: keep-alive) are emitted every ~15 s so intermediate proxies don’t drop the connection.

An account can have at most 5 event and log streams open at once; one more gets a 429 too_many_streams until another closes.

Log access

GET /api/v1/jobs/{id}/log

Fetch the run log as a single response. Query parameters:

  • tail=N — return only the last N lines (1–100 000).
  • format=text|ndjson — default text; ndjson emits one {"line": "..."} per line.

Required scope: jobs:read. Returns 404 if the job hasn’t started or predates log persistence.

GET /api/v1/jobs/{id}/log/stream

Same content as /log but streamed as plain text or NDJSON (no SSE framing). Useful for tail-style consumers that don’t want SSE’s event headers. It counts against the same limit of 5 open streams as /events.

Results

GET /api/v1/jobs/{id}/download

Stream the result archive (results.zip). 409 until status is done; 404 after the TTL purge removes the archive.

GET /api/v1/jobs/{id}/results

JSON manifest of every file in the archive with byte counts and SHA-256 digests.

{
  "files": [
    { "name": "mfannot.out",  "size_bytes": 18432, "sha256": "…" },
    { "name": "mfannot.html", "size_bytes": 41021, "sha256": "…" }
  ]
}

GET /api/v1/jobs/{id}/results/{filename}

Stream a single file out of the archive without downloading the whole zip. The filename must match an entry in the manifest exactly.

Token management

Self-service token CRUD. Browser users hit these via cookie auth; tokens can also call them, but only if they themselves hold tokens:manage. A read-only token cannot mint a write token.

Each user is capped at 10 active tokens, meaning neither revoked nor expired. Creating another while at the cap returns 409 conflict.

GET /api/v1/tokens

List the caller’s tokens that have not been revoked (expired ones are still listed). The plaintext is never returned here — only at creation.

POST /api/v1/tokens

Create a new token.

POST /api/v1/tokens
Content-Type: application/json

{
  "name": "ci-uploads",
  "scopes": ["jobs:read", "jobs:write"],
  "expires_in_days": 90
}

The response includes a one-time plaintext field — store it immediately, it cannot be retrieved again.

{
  "id": "5b2e…",
  "name": "ci-uploads",
  "prefix": "mfw_aBcD",
  "scopes": ["jobs:read", "jobs:write"],
  "created_at": "2026-05-14T19:02:11Z",
  "last_used_at": null,
  "expires_at": "2026-08-12T19:02:11Z",
  "plaintext": "mfw_aBcD…full-token…"
}

DELETE /api/v1/tokens/{id}

Revoke a token. Idempotent: revoking an already-revoked token is a 204 no-op.

Example requests

Submit a job

curl -X POST https://mfannot.example.org/api/v1/jobs \
  -H "Authorization: Bearer $MFW_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nightly-2026-05-14" \
  -d '{
    "kind": "mfannot",
    "gencode": 4,
    "rna": [],
    "input_filename": "sample.fasta",
    "fasta": ">seq1\nACGTACGT…"
  }'

Watch the live log

curl -N https://mfannot.example.org/api/v1/jobs/$ID/events \
  -H "Authorization: Bearer $MFW_TOKEN"

Download results

curl -L -o results.zip \
  https://mfannot.example.org/api/v1/jobs/$ID/download \
  -H "Authorization: Bearer $MFW_TOKEN"

A first-party CLI (mfw) wraps these endpoints with no runtime dependencies beyond Python’s stdlib. See the source in cli/.