v1_views

Public REST API — version 1 endpoints.

All endpoints live under the /api/v1/ prefix (see api/urls_v1.py).

Authentication

Most endpoints require an API key delivered as a Bearer token:

Authorization: Bearer ak_<your_key>

The two exceptions are /health/ and /methods/, which are intentionally public so that clients can discover available methods and check server status without needing credentials.

Quota

Quota accounting is keyed by API key identity (not source IP), so requests from different hosts still share one quota bucket per key. The effective daily limit for authenticated requests is the higher of:

• the owning user’s IP-level limit, and

• the API key’s optional custom limit.

Module Contents

v1_views.api_health(request)

Health check endpoint — no authentication required.

Returns a simple JSON object confirming the service is up.

v1_views.api_gpu_status(request)

Return a minimal GPU availability snapshot for the frontend.

Internal fields (gpu_name, vram, active_jobs, raw GPU response) are deliberately stripped — the browser only needs to know online/offline.

v1_views.api_list_methods(request)

List all available prediction methods and their requirements.

No authentication required — this endpoint acts as living documentation so clients can discover what methods exist and what CSV columns they need before writing any code. The response is generated directly from the method registry, so it is always up to date when new methods are added.

Response shape

{

“methods”: {

“<method_key>”: {

“displayName”: str, “authors”: str, “publicationTitle”: str, “citationUrl”: str, “repoUrl”: str, “moreInfo”: str, “supports”: list[str], // e.g. [“kcat”, “Km”, “kcat/Km”] “inputFormat”: str, // backend contract: “single” or “multi” “acceptedCsvTypes”: list[str], // UI/API input schemas accepted by the method “acceptedCsvTypesByTarget”: object, “inputBehaviorByTarget”: object, // expanded_pair/native_multi/native_full_reaction “maxSeqLen”: int | null, // null means no limit “requiredColumns”: list[str], // includes “Protein Sequence” “substrateFormat”: str,

}, “predictionTypes”: [“kcat”, “Km”, “kcat/Km”], “longSequenceOptions”: { “truncate”: “…”, “skip”: “…” }, “notes”: { … }

}

v1_views.api_quota(request)

Return the current quota status for the authenticated key owner.

Quota is tracked per-day (resetting at midnight UTC) and keyed by authenticated API key.

v1_views.api_submit_job(request)

Submit a new prediction job.

Accepts two content types:

1. multipart/form-data — upload a CSV file plus form fields:

   file (required) — the CSV file targets (required) — JSON array from

   [“kcat”, “Km”, “kcat/Km”]

   methods (required) — JSON object mapping selected target

   to method key

   handleLongSequences (optional, default “truncate”) — “truncate” or “skip” useExperimental (optional, default “false”) — “true” or “false” includeSimilarityColumns (optional, default “true”) — “true” or “false” canonicalizeSubstrates (optional, default “true”) — “true” or “false” disableGpuPrecompute (optional, default “false”) — internal benchmark toggle

2. application/json — send data directly as a JSON body:

   {

   “targets”: [“kcat”], “methods”: {“kcat”: “DLKcat”}, “handleLongSequences”: “truncate”, “useExperimental”: false, “includeSimilarityColumns”: true, “canonicalizeSubstrates”: true, “disableGpuPrecompute”: false, “data”: [

   {“Protein Sequence”: “MKTL…”, “Substrates”: “CC(=O)O;O”}, …

   ]

   }

Both paths call the same underlying job-submission service, so validation, quota accounting, and task dispatch behave identically.

On success, returns a JSON object with:

• jobId — use this to poll /status/ and download /result/

• status — Pending; poll statusUrl for the current persisted job state

• statusUrl — convenience URL for polling

• resultUrl — convenience URL for downloading results

• quota — your remaining quota after this submission

v1_views.api_job_status(request, public_id)

Return the current status of a prediction job.

Poll this endpoint until status is “Completed” or “Failed”, then fetch your results from the resultUrl.

Possible status values:

Pending — job is queued and waiting for a worker Processing — worker is running predictions Completed — predictions are done; results are ready to download Failed — something went wrong; see the ‘error’ field for details

v1_views.api_download_result(request, public_id)

Download the prediction results for a completed job.

By default, returns a CSV file attachment. Add ?format=json to receive the same data as a JSON object instead — useful when you want to parse results directly without writing an intermediate file.

The response includes all columns from the input CSV plus:

• A prediction column (e.g. “kcat (1/s)” or “KM (mM)”)

• A “Source” column indicating whether the value came from a model or from the experimental database

• An “Extra Info” column with additional details

For Substrates inputs, Km and direct kcat/Km cells contain JSON-encoded arrays. They remain strings in CSV and in the JSON result envelope so both formats represent the same output exactly.

Returns 409 Conflict if the job has not yet completed. Returns 404 if the job does not exist. Returns 500 if the output file is missing (should not normally occur).

v1_views.api_validate(request)

Validate a CSV file (or inline JSON data) without submitting a prediction job. Checks substrate SMILES/InChI strings, protein amino-acid sequences, and sequence-length limits for every available model.

Optionally runs MMseqs2 sequence similarity analysis against each method’s training database when runSimilarity=true. This is a synchronous call that blocks until the analysis is complete — it may take several minutes for large inputs. No quota is consumed by this endpoint.

Accepts the same two content-type formats as /submit/:

1. multipart/form-data

   file (required) — the CSV file runSimilarity (optional, default “false”) — “true” to include similarity

2. application/json

   {

   “data”: […], // required — array of row objects “runSimilarity”: false // optional

   }

Response fields:

rowCount — total number of data rows in the input invalidSubstrates — list of rows with unparseable SMILES/InChI strings invalidProteins — list of rows with invalid amino-acid sequences lengthViolations — per-model violation counts (all registered methods + Server) lengthLimits — per-model max sequence lengths from descriptors

(null means no limit), plus Server

similarity — null when not requested; otherwise a dict keyed by

method name, each containing histogram_max, histogram_mean, average_max_similarity, average_mean_similarity, count_max, count_mean