Tamarind Bio workflow recipes

End-to-end examples using plain requests. All use BASE = "https://app.tamarind.bio/api" and HEADERS = {"x-api-key": os.environ["TAMARIND_API_KEY"]}. For exact request/response shapes, fetch the spec at https://app.tamarind.bio/openapi.yaml.

The canonical loop is always: discover → schema → validate → submit → poll → results.

1. Fold a single sequence (AlphaFold)

python

import os, time, requests
BASE = "https://app.tamarind.bio/api"
HEADERS = {"x-api-key": os.environ["TAMARIND_API_KEY"]}

# discover + confirm the tool exists (REST returns the full list; filter client-side)
tools = requests.get(f"{BASE}/tools", headers=HEADERS).json()
assert any(t["name"] == "alphafold" for t in tools)

job = {
    "jobName": "ubiquitin-fold",
    "type": "alphafold",
    "settings": {
        "sequence": "MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTLHLVLRLRGG",
        "numModels": "5",
        "numRecycles": 3,
        "useMSA": True,
    },
}
requests.post(f"{BASE}/submit-job", headers=HEADERS, json=job).raise_for_status()

# poll. GET /jobs?jobName= returns the job ROW directly (no "jobs" wrapper).
while True:
    row = requests.get(f"{BASE}/jobs", headers=HEADERS,
                       params={"jobName": "ubiquitin-fold"}).json()
    if row["JobStatus"] in ("Complete", "Stopped", "Deleted"):
        break
    time.sleep(30)

print("status:", row["JobStatus"], "score:", row.get("Score"))

# results download is two-step: POST /result returns a presigned URL *string*,
# then GET that URL for the zip.
url = requests.post(f"{BASE}/result", headers=HEADERS,
                    json={"jobName": "ubiquitin-fold"}).text.strip('"')
open("ubiquitin-fold.zip", "wb").write(requests.get(url).content)

2. Multimer / complex (colon-separated chains)

For AlphaFold, a multimer is just one sequence with chains joined by :.

python

job = {
    "jobName": "ab-ag-complex",
    "type": "alphafold",
    "settings": {
        # heavy:light:antigen — separate chains with ":"
        "sequence": "EVQLVESGGG...:DIQMTQSPSS...:MKTAYIAKQR...",
    },
}
requests.post(f"{BASE}/submit-job", headers=HEADERS, json=job).raise_for_status()

Other folding tools need more fields — boltz/chai require inputFormat ("sequence"/"list"/"molecules"/"yaml"), e.g. boltz sequence-mode is {"inputFormat": "sequence", "sequence": "...:..."}. Always check required fields with getJobSchema/validateJob first — don't assume sequence alone is enough.

3. Validate before submitting (MCP)

When your agent host has the Tamarind MCP server, dry-run first to catch errors without spending a submission. Validate and submit your own clean settings — build the submit from my_settings, not verdict["normalized"] (normalized is informational: defaults filled in, sometimes platform-managed fields).

getJobSchema(jobType="boltz")               # learn required fields first
my_settings = {"inputFormat": "sequence", "sequence": "...:..."}
verdict = validateJob(jobName="x", type="boltz", settings=my_settings)
# verdict.valid == True  -> good; submit my_settings (NOT verdict.normalized)
# verdict.valid == False -> verdict.error is the first problem to fix
if verdict["valid"]:
    submitJob(jobName="x", type="boltz", settings=my_settings)

4. Upload a structure, then submit a job that uses it

python

# REST: PUT the file to /upload/{filename}
with open("target.pdb", "rb") as fh:
    requests.put(f"{BASE}/upload/target.pdb", headers=HEADERS, data=fh).raise_for_status()
# the object's S3 key is "{your-email}/target.pdb", but you reference it by the
# BARE filename — the platform scopes it to your account. Do NOT email-prefix it.
job = {
    "jobName": "dock-run",
    "type": "diffdock",
    "settings": {
        "proteinFile": "target.pdb",   # bare filename, NOT inline content, NOT email-prefixed
        "ligandFormat": "SMILES",                       # required; gates ligandSmiles vs ligandFile
        "ligandSmiles": "CC(=O)Oc1ccccc1C(=O)O",
    },
}
requests.post(f"{BASE}/submit-job", headers=HEADERS, json=job).raise_for_status()

MCP variant: uploadFile("target.pdb") returns a presigned uploadUrl; then curl -X PUT -T target.pdb "<uploadUrl>".

Reminder: a bare non-filename string in a file-typed field is uploaded as inline content. To point at an existing uploaded file, use its bare filename (target.pdb) — NOT the {email}/{filename} S3-key form, which submit-job 400s as "... has not been uploaded". Confirm the registered name with getFiles/GET /files. For a prior job's output, use JobName/....

For autodock-vina instead of DiffDock, the same upload-then-reference flow applies, but the settings differ: it docks into a fixed pocket, so it needs receptorFile + a bounding box (boxX/Y/Z, width/height/depth) and a lowercase ligandFormat ("smiles"/"sdf"). Run getJobSchema("autodock-vina") for the full shape; see examples.md for a worked payload.

5. Chain jobs: design → fold

A sequence-design tool (ProteinMPNN) emits sequences, so you fold them by passing each as a sequence — NOT via a template/file field. The cleanest way is the MCP submitBatch(fromJob=...), which reads the design job's generated sequences and folds each as one job in a single call:

# Step 1: design sequences for a backbone
submitJob(jobName="design-step", type="proteinmpnn", settings={...})   # poll to Complete

# Step 2: fold every designed sequence (MCP reads them from the design job)
submitBatch(batchName="fold-designs", type="alphafold", fromJob="design-step")

Doing it over plain REST instead: read the design job's output sequences (MCP listJobFiles("design-step") → s3Path, or download the FASTA via /result), then submit one fold per sequence with settings={"sequence": "<designed seq>"}.

Don't chain a designed sequence through a file/template field. A file parameter wants a file of the right type, and a template field is for structural homology, not "fold this sequence." Example of the trap: AlphaFold's templateFiles accepts only .cif, must be a list, and is gated behind templateMode: "custom" — so {"templateFiles": "design-step/out/x.pdb"} fails validation three ways and isn't how you fold a design anyway. When a chain really does feed a file (e.g. a PDB into a docking tool), getJobSchema/validateJob first to confirm the param's type and conditions.

For reusable multi-step flows, build a saved pipeline with /submit-pipeline and run it with /run-pipeline.

6. Batch screen many sequences through one tool

Submit, then poll the batch parent on batchStatus (not subjob JobStatus) — the batch aggregates results after subjobs finish computing.

python

seqs = ["MKT...", "AVF...", "GEV..."]
requests.post(f"{BASE}/submit-batch", headers=HEADERS, json={
    "batchName": "binder-screen",
    "type": "alphafold",
    "jobNames":  [f"cand-{i}" for i in range(len(seqs))],
    "settings":  [{"sequence": s} for s in seqs],
    "weightedHoursBudget": 50,        # optional budget cap
}).raise_for_status()

# poll the parent until the aggregated output is ready
# (?jobName= returns the parent ROW directly — no "jobs" wrapper)
while True:
    parent = requests.get(f"{BASE}/jobs", headers=HEADERS,
                          params={"jobName": "binder-screen"}).json()
    bs = parent.get("batchStatus")
    if bs == "Complete":
        break
    if bs in ("Stopped", "AggregationFailed"):
        raise RuntimeError(parent.get("AggregationError", bs))
    time.sleep(15)        # Running / Aggregating -> keep waiting

print(parent["statuses"])  # e.g. {"Complete": 3, "Running": 0, "In Queue": 0, "Stopped": 0}
open("binder-screen.zip", "wb").write(requests.get(parent["resultUrl"]).content)

# Per-subjob rows (e.g. to read each candidate's Score):
subjobs = requests.get(f"{BASE}/jobs", headers=HEADERS,
                       params={"batch": "binder-screen", "includeSubjobs": "true"}).json()

7. Debug a stopped job

python

# REST: pull results/log path; MCP gives logs directly
logs = getJobLogs("binder-screen-cand-2")   # MCP: last N lines of output log
# Inspect the tail for the failure reason (bad input, OOM, timeout, budget).

A Stopped status with no Score usually means a failure — read the log tail. A 403 at submit means a budget cap was hit.

8. List every job (paginate past the 1000 limit)

The list query returns {"jobs": [...], "startKey": ...}; pass startKey back until it's absent.

python

jobs, params = [], {"limit": 1000}
while True:
    resp = requests.get(f"{BASE}/jobs", headers=HEADERS, params=params).json()
    jobs += resp["jobs"]
    if "startKey" not in resp:
        break
    params["startKey"] = resp["startKey"]
print(len(jobs))

9. Submit now, check back later (non-blocking)

Bio jobs run for minutes to hours — you don't have to hold a blocking poll loop open. Jobs are addressable by jobName from any process, so submit, persist the names, and reconnect in a separate session/process to collect results. This is the right pattern for long campaigns or fire-and-forget pipelines.

python

# --- Session 1: submit and save the job names ---
import os, json, requests
BASE = "https://app.tamarind.bio/api"
HEADERS = {"x-api-key": os.environ["TAMARIND_API_KEY"]}

seqs = {"cand-a": "MKT...", "cand-b": "AVF...", "cand-c": "GEV..."}
for name, seq in seqs.items():
    requests.post(f"{BASE}/submit-job", headers=HEADERS,
                  json={"jobName": name, "type": "alphafold",
                        "settings": {"sequence": seq}}).raise_for_status()
json.dump(list(seqs), open("pending_jobs.json", "w"))   # persist to disk/db
print("submitted; check back later")

python

# --- Session 2 (later, fresh process): collect whatever is done ---
import os, json, requests
BASE = "https://app.tamarind.bio/api"
HEADERS = {"x-api-key": os.environ["TAMARIND_API_KEY"]}

names = json.load(open("pending_jobs.json"))
done, pending = [], []
for name in names:
    row = requests.get(f"{BASE}/jobs", headers=HEADERS,
                       params={"jobName": name}).json()   # bare row, by-name
    (done if row["JobStatus"] in ("Complete", "Stopped", "Deleted") else pending).append(name)

print(f"{len(done)} terminal, {len(pending)} still running")
for name in done:
    url = requests.post(f"{BASE}/result", headers=HEADERS,
                        json={"jobName": name}).text.strip('"')
    open(f"{name}.zip", "wb").write(requests.get(url).content)

Re-run session 2 until pending is empty. For a server-driven variant, poll a batch parent's batchStatus (recipe 6) instead of looping job-by-job.

Notes

Polling cadence: 15-30s. Complete and Stopped are terminal.
Scores: completed folding jobs return pLDDT / pTM / ipTM (and interface metrics like ipSAE / pDockQ for complexes) in the Score field.