CatShift API guide

Explore candidate variants with predicted changes in kcat, alongside KM and estimated catalytic efficiency, from a reference protein structure and substrate.

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

Interactive CatShift reference · All tools · CatShift website

Research preview — under development. A qualifying candidate is not guaranteed. For now, please cite CatRange when using these results.

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 CatShift interactive reference lets you inspect the fields and try requests. /catshift/v1/ready and /catshift/v1/capabilities return supported inputs and live 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.

Choose an input mode

All submissions are multipart form data, sent to POST /catshift/v1/jobs. Use your existing Authorization: Bearer <your-key> header and a saved Idempotency-Key, following the shared retry guidance above.

Each reference needs substrate SMILES and a usable structure: an uploaded file, a PDB accession, or a UniProt accession with an available structure. A UniProt accession does not guarantee structure availability. Generating a structure from sequence alone is not supported. Obtain a suitable structure externally first; review the structure guidance and external-service caveats on the CatShift website.

The protein sequence is optional when it can be taken from the chosen structure. If supplied, it must match the reference and selected chain. Specify chain_id for a multichain structure rather than relying on an implicit selection. All residue positions below refer to the reference sequence, starting at 1; they can differ from deposited structure numbering.

The demo supplies its own reference. You may override direction, min_abs_kcat_bin_shift, max_candidates, radius_angstrom and protect_functional_residues. Its curated defaults use direction=either and max_candidates=19; other modes default to up and 38.

First request: a demo

This example submits one real search. Save the submission ID before sending; use the same ID and inputs if you need to retry.

from pathlib import Path
import json
import uuid
import httpx

base = "https://api.sahassbio.com/catshift/v1"
key = Path("~/.config/ssbio/research-api-key").expanduser().read_text().strip()
submission_id = str(uuid.uuid4())
print("Save this submission ID:", submission_id)

response = httpx.post(
    f"{base}/jobs",
    headers={"Authorization": f"Bearer {key}", "Idempotency-Key": submission_id},
    files={
        "mode": (None, "demo"),
        "options_json": (None, json.dumps({"direction": "either", "max_candidates": 19})),
    },
    timeout=60,
    follow_redirects=False,
)
response.raise_for_status()
job = response.json()
print("Job ID:", job["job_id"])

Download catshift.py and save it as catshift.py. This example saves the job record, polls for completion, and downloads the result CSV:

python -m pip install httpx
python catshift.py --demo --output catshift-results.csv \
  --api-key-file ~/.config/ssbio/research-api-key

For an interactive upload, save your public options to options.json:

{
  "structure_source": "upload",
  "chain_id": "A",
  "smiles": "[H]C(=O)[C@H](O)COP(=O)(O)O",
  "sequence_id": "My reference",
  "substrate_id": "D-glyceraldehyde 3-phosphate",
  "direction": "either",
  "min_abs_kcat_bin_shift": 3,
  "max_candidates": 38
}

Use a matching protein structure and your actual substrate:

python catshift.py --options options.json --structure reference.pdb \
  --output catshift-results.csv --api-key-file ~/.config/ssbio/research-api-key

For an accession, set structure_source to pdb or uniprot, add accession to your options, and omit --structure.

Bulk searches

Use mode=csv, a csv_file and optional shared options_json. Each CSV row starts a reference search. Bulk rows use accessions; uploaded structure files are supported only in interactive mode.

Supported columns are sequence, smiles (or Isomeric SMILES), sequence_id, substrate_id, structure_source, accession and chain_id. Row values replace matching shared options. Do not include both SMILES column names.

structure_source,accession,chain_id,smiles,sequence_id,substrate_id
pdb,1TIM,A,[H]C(=O)[C@H](O)COP(=O)(O)O,Reference A,D-glyceraldehyde 3-phosphate

python catshift.py --csv references.csv --output catshift-results.csv \
  --api-key-file ~/.config/ssbio/research-api-key

A five-row bulk search still counts as one submission attempt, but each reference may evaluate up to its candidate budget. Begin with a smaller search and inspect the results before increasing the workload.

Progress, results and activity

Poll approximately every 10 seconds. After status=done, inspect each cases[] entry: a bulk search may finish with some references marked failed. Within a successful case, reference contains the baseline and candidates contains the evaluated variants. Use eligible=true for qualifying candidates; read skip_reason and prediction_status for other outcomes. Candidate ranks, kcat and KM ranges, bin differences, and available efficiency estimates are included in the public results. Keep the CSV so excluded candidates and their reasons remain available for review.

A completed search with no qualifying candidates is a valid outcome. Check the reference prediction and structure/chain/substrate match first. If those are usable, consider a larger candidate budget within the stated limits, another scientifically justified region, the either direction, or a lower bin threshold for a separate exploratory search. A missing reference prediction or failed reference needs input review before a broader search. None of these changes guarantees a hit; no hits do not establish that improvement is impossible.

Activity counts describe service use and predicted candidate availability, not experimentally validated success. Read the endpoint’s collection timestamp and availability fields; do not substitute zeros for unavailable statistics. There is no CatShift /rerun endpoint in this preview. To try different inputs or settings, create a new submission with a new idempotency key.

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.

CatShift currently uses CPU workers; there is no GPU request option. Each bulk job can contain at most five reference pairs, each with a candidate budget of 19–190. Budgets are upper limits, not a guarantee that all candidates receive predictions. Start with one reference or the demo before increasing the workload.

Searches currently run fresh. There is no prediction-cache control or /rerun endpoint for CatShift in this preview. For a new search or changed settings, submit a new request with a new idempotency key. Use the original key only when retrying the same request.

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

CatShift is under development. Candidate ranks and predicted shifts are research hypotheses; they do not establish improved activity, folding, stability or catalytic efficiency. A limited search with no qualifying candidates does not show that improvement is impossible.

Bin differences are ordinal: a three-bin shift does not necessarily mean a 1,000-fold change. Efficiency comparisons use predicted range midpoints, not measured catalytic efficiency, and may be unavailable for some ranges. Review input quality and the reported limitations before choosing experiments.

For now, please cite the CatRange paper when using CatShift results. A separate CatShift citation is not yet available. The shared API is operated by SSBio Lab.