CatRange API guide

Predict kcat and KM ranges for enzyme–substrate pairs, using up to 10 interactive pairs or a CSV batch.

API base: https://api.sahassbio.com/catrange/v1

Interactive CatRange reference · All tools · CatRange website

Access · Submission · Progress and results · Limits · Retention · Errors · Citation

Access and authentication

Open Get API key and enter your email address. Your emailed key works with CatRange and CatShift. Existing active emailed keys keep the same value; no separate CatShift key is needed. Your key is delivered to that inbox, never displayed in the request page. If your email is already registered, the same key is sent again; your jobs and usage allowance are preserved. Check your spam folder if it does not arrive. If the operator revokes your key, use the same form to request a replacement. The old key stops working; your account, jobs, and quota usage stay intact. Suspended accounts must be restored by the operator before requesting a key. Wait at least a minute before requesting again; up to three key emails per address per UTC day are permitted. Delivery is subject to service limits.

Keep your key private and store it in a file with permissions 600, outside your project repository. Never embed it in a public notebook, browser JavaScript, or a GitHub issue. Keys do not currently expire automatically. Operator-issued keys may have narrower tool permissions. For replacement of an exposed key, changed quotas, or an older key not linked to your email, contact info@catrange.sahassbio.com.

Send Authorization: Bearer <your-key> on job requests. Documentation, readiness information, and aggregate activity counts are public. A key can only access jobs submitted under its own client identity through this gateway. Existing website job IDs continue working on the website; they are not automatically imported into the gateway. Treat Job IDs and emailed result links as private: the existing website still uses those links to grant access to retained results.

The CatRange interactive reference lets you inspect the fields and try requests. /catrange/v1/ready returns machine-readable availability. See server status for a visual view and the schema page for JSON contracts.

Retry-safe submissions

For either tool, send an Idempotency-Key header containing a unique identifier for this logical submission. Reuse that identifier and the same inputs when retrying the same submission. A new identifier means a new submission, even if the inputs are identical. Multipart boundaries do not affect retry matching. Use 8–128 ASCII letters, digits, dots, underscores, colons, or hyphens. Completed submission responses can be replayed for eight days. After that, the key returns 410; a compact record prevents it from creating another job.

Submit a CSV

CSV files need sequence and smiles columns. Isomeric SMILES is also accepted instead of smiles. Optional sequence_id and substrate_id columns label the results. Protein sequences must contain 9–1,022 amino acids, and SMILES strings 2–512 characters. Invalid rows remain in the output with skip reasons.

Submission uses multipart form data, not a JSON request body:

CLEAN is enabled by default. The screening options are:

• clean: run CLEAN and predict only eligible valid rows (recommended).
• clean_all: run CLEAN, preserve its flags and scores, and also predict valid rows that CLEAN flags. These overridden rows are marked as exploratory.
• skip_clean: do not run CLEAN; predict all valid rows as exploratory estimates.

For example, add "screening_mode": "clean_all" to the data dictionary in the Python submission below, or send -F screening_mode=skip_clean with curl. Input length and format checks still apply in every mode. CLEAN flags do not prove that a protein lacks catalytic activity, and an exploratory kinetic prediction does not establish enzyme activity or turnover of the supplied substrate. Results report screening_mode and screening_warning; CSV rows retain the screening flags and mark exploratory predictions with clean_warning. Advanced modes use separate cache entries. Changing the screening mode is a new submission and requires a new Idempotency-Key; rerunning a job preserves its original screening mode.

from pathlib import Path
import uuid
import httpx

base = "https://api.sahassbio.com/catrange/v1"
key = Path("~/.config/ssbio/research-api-key").expanduser().read_text().strip()
submission_id = str(uuid.uuid4())  # Save this before sending; reuse it on retry.

with httpx.Client(timeout=60, follow_redirects=False) as client:
    with open("inputs.csv", "rb") as file:
        response = client.post(
            f"{base}/jobs",
            headers={"Authorization": f"Bearer {key}",
                     "Idempotency-Key": submission_id},
            data={"mode": "csv", "compute": "cpu"},
            files={"csv_file": ("inputs.csv", file, "text/csv")},
        )
    response.raise_for_status()
    job = response.json()
    print(job["job_id"], job["status"])

Download catrange.py and save it as catrange.py. This example saves the job response, polls for completion, and downloads the CSV. It reads a key from a private file rather than accepting a key on the command line.

python -m pip install httpx
python catrange.py --input inputs.csv --output predictions.csv \
  --api-key-file ~/.config/ssbio/research-api-key

Interactive pairs

For up to 10 pairs, send mode=interactive and a pairs_json multipart field containing a JSON array, even when you submit only one pair:

import json
pairs_json = json.dumps([
    {"sequence": "YOUR_PROTEIN_SEQUENCE", "smiles": "YOUR_SUBSTRATE_SMILES",
     "sequence_id": "Reference A", "substrate_id": "Substrate A"}
])
# Send with the same Authorization and Idempotency-Key headers as above.
# files={"mode": (None, "interactive"), "pairs_json": (None, pairs_json)}

In PowerShell, use ConvertTo-Json -InputObject @($payload) -Depth 5 -Compress. Piping a single object into ConvertTo-Json can remove the surrounding array. Do not rename pairs_json or send a JSON object instead of a list.

Progress and results

Poll approximately every 10 seconds. A cache hit can finish immediately. Otherwise jobs pass through queueing and execution before done or a failure state. Use the returned links; do not assume backend-specific hostnames.

Activity counters count each successful parameter result once per completed job; downloads do not increment them. Computed and cached results have separate subtotals. Tracking includes the results still retained at activation, so older deleted results are missing from this baseline. These are not lifetime totals. Collection can lag by about a minute; an outage is marked stale or unavailable.

Resources and shared limits

Clients do not need local models, a GPU or cluster credentials. CatRange and CatShift share the same hosted queue with the websites. The current service permits up to five running workers and five unfinished jobs total. Read the live readiness endpoint before submitting; capacity can change.

Default emailed keys permit 120 authenticated requests per minute and 10 new submission attempts per UTC day, shared across both tools. Operators may assign different limits. Retrying with the same idempotency key and the same inputs does not count as a new submission attempt.

RAM rises to 24 GiB for longer valid sequences. These are resource assignments and execution deadlines, not runtime estimates or completion guarantees. GPU requests are currently disabled. cpu is the default; auto can use the available CPU resources. Read /ready for current options and upload limits.

Result retention

Retained result files are normally cleaned up seven days after completion. Availability within that period is best effort and is not guaranteed. Download and keep your own copy promptly; the service is not an archive and cannot guarantee recovery of lost data. Gateway ownership and retry records are separate metadata; they do not extend result retention.

Errors and retries

• 400 / 422: invalid input or request format; check the tool-specific guide.
• 401: missing or invalid API key.
• 403: the key is not permitted to use this tool, or the requested compute option is unavailable.
• 404: the job does not belong to this key, or does not exist.
• 409: an idempotency conflict, submission still in progress, or an uncertain upstream submission outcome. Inspect the response and keep the same key.
• 410: results have expired.
• 410 with idempotency_response_expired: the submission replay record has expired; the original key will not create another job.
• 413: request or upload too large.
• 429: a per-key quota was reached; respect Retry-After.
• 502 / 503 / 504: the upstream service is unavailable or its outcome is uncertain. Do not automatically submit with a new idempotency key.

If a submission times out after the backend may have accepted it, the gateway keeps the attempt reserved to avoid duplicate compute. Ask the operator to reconcile it; a new idempotency key would risk creating another job. Read-only polling can be retried with backoff. Automatic multi-provider failover is not enabled.

Interpretation and citation

CatRange predicts kinetic ranges, not experimentally measured rate constants. Use the reported bounds, units and confidence fields. Adjacent-bin visual guides are not calibrated confidence intervals, and midpoints do not replace the range prediction. CLEAN screening is the default; explicitly chosen exploratory modes retain their screening provenance and cautions in the results.

Please cite the CatRange paper. See CatRange’s README for scientific source and citation details. The shared API is operated by SSBio Lab.