Tamarind Bio
  • All Tools
  • Database
  • Batch Workflows
  • Pipelines
  • Contact
  • Blog
  • Docs
  • API
  • Pricing
Tamarind API Documentation

Tamarind API Documentation

Tamarind offers an API for job submission for all of our tools at large scales, along with hosting and deploying your custom models.

API Endpoints

Each "job" is one input that is scheduled to run on a GPU given your settings.

The API follows a REST format with the following endpoints:

  • /submit-job (POST) submits a job with a name and input parameters
  • /submit-batch (POST) submits a grouped batch of jobs given their settings
  • /jobs (GET) returns all jobs and their statuses
  • /results (POST) returns a s3 presigned URL to the results folder for a given jobName
  • /files (GET) returns all files in your account
  • /tools (GET) returns all available tools and their configurations

Download OpenAPI Specification


Submitting Jobs

The POST API endpoint /submit-job allows users to create jobs that will be run in parallel with multiple GPUs. Below is a code example to submit one job.

Note: Job names may only contain alphanumeric characters, underscores (_), hyphens (-), and periods (.).

Options for inputting file fields (ex. .pdb, .sdf, etc.):

  • Use the /upload endpoint and upload your file before submitting
  • Use the path of a previous Tamarind job, in the format JobName/path/to/file.ext
  • Submit the contents of your file directly
1import requests 
2api_key = "***************"
3base_url = "https://app.tamarind.bio/api/"
4
5params = {
6  "jobName": "myJobName",
7  "type": "alphafold",
8  "settings": {
9    "sequence": "MALKSLVLLSLLVLVLLLVRVQPSLGKETAAAKFERQHMDSSTSAASSSNYCNQMMKSRNLTKDRCKPVNTFVHESLADVQAVCSQKNVACKNGQTNCYQSYSTMSITDCRETGSSKYPNCAYKTTQANKHIIVACEGNPYVPVHFDASV"
10  }
11}
12
13response = requests.post(base_url + "submit-job", headers={'x-api-key': api_key}, json=params)
14print(response.text)
Select tool:

View tool page


  • Protein amino acid sequence, use : to separate chains for multimers
  • Options: ["1", "2", "3", "4", "5"]
  • Default: 5
  • Number of Models: Number of models to be used, each generating a different prediction
  • Options: ["mmseqs2_uniref_env", "mmseqs2_uniref", "single_sequence"]
  • MSA Mode: Select which database to use for MSA, or choose 'single_sequence' to skip MSA search
  • Default: 3
  • Number of recycles: Number of times to recycle outputs back through structure prediction process for refined results
  • Default: 0
  • Number of models to relax: Number of models to perform amber relaxation for more accurate side chain predictions
  • Options: ["paired", "unpaired", "unpaired_paired"]
  • Pair Mode: "unpaired_paired" = pair sequences from same species + unpaired MSA, "unpaired" = seperate MSA for each chain, "paired" - only use paired sequences.
  • Default: True
  • Use PDB 100 Templates: Query PDB100 for template structures to use for your prediction
  • Custom Template Files: Use custom structural templates in your prediction
  • Random seed: Random seed to be used in structure prediction
  • Options: ["508:2048", "512:1024", "256:512", "128:256", "64:128", "32:64", "16:32"]
  • Max MSA: Max # Clusters : Max # Extra Sequences - decrease max_msa to increase uncertainity
  • Options: ["0.0", "0.5", "1.0"]
  • Recycle Early Stop Tolerance: Run recycles until distance between recycles is within a given tolerance (0 = never stop early)
  • Default: False
  • Score with IPSAE: Use IPSAE scoring function for interprotein interactions
  • Default: False

    • Uploading Files

    The PUT API endpoint /upload/{filename} allows users to upload files to their account to use as inputs for job submissions. Files are uploaded to your account's root folder by default. You can specify a folder to upload to using the optional "folder" parameter. After uploading, you can use the filename as input into jobs, like "input.pdb" or "myFolder/input.pdb". 

    1import requests 
2api_key = "***************"
3base_url = "https://app.tamarind.bio/api/"
4
5# file is in current directory
6local_filepath = "/path/to/your/file1.txt"
7uploaded_filename = "file1.txt"
8response = requests.put(f"{base_url}/upload/{uploaded_filename}", headers={'x-api-key': api_key}, data=open(local_filepath, 'rb'))
9print(response.status_code)
10# you can now use "file1.txt" as an input for your jobs

    Viewing Jobs

    The GET API endpoint /jobs allows users to see their submitted jobs. Using the snippet below, you can produce a list of jobs, along with their statuses, settings, and created date.

    Optional Params:
    - jobName = "myJobName": return one job given its name
    - batch = "myBatchName": return all jobs in a batch
    - startKey = (key): use a previously returned start key to retrieve more than 1000 jobs
    - limit = (int): limit the number of jobs retrieved, if there are additional jobs a startKey will be returned
    - organization = "true": return all jobs in your organization
    - includeSubjobs = "true": include subjobs from batches in response - only top level jobs are returned by default
    - jobEmail = "user@email.com": return jobs for another member in your organization
    1import requests 
2api_key = "***************"
3base_url = "https://app.tamarind.bio/api/"
4
5response = requests.get(base_url + "jobs", headers={'x-api-key': api_key})
6print(response.json())

    Deleting Jobs

    The POST API endpoint /delete-job allows users to delete a job given its name. If a job name is provided which does not exist, it returns a 400 error. If you delete a batch job, all subjobs will be deleted also. 

    1import requests 
2api_key = "***************"
3base_url = "https://app.tamarind.bio/api/"
4
5params = {
6  "jobName": "myJobName"
7}
8response = requests.post(base_url + "delete-job", headers={'x-api-key': api_key}, json=params)
9print(response.text)

    Retrieving Results

    The POST API endpoint /result returns a S3 presigned URL for a zip file containing results for a given job if the job is complete. If the job is not complete, a 400 error is returned.

    Optional Params:
    - jobEmail: Email of a member of your organization - retrieves a job in another organization member's account
    - fileName: Path to a file in your job's results - retrieves S3 signed url to that file
    1import requests 
2api_key = "***************"
3base_url = "https://app.tamarind.bio/api/"
4
5from urllib.request import urlretrieve
6
7jobName = "myJobName"
8savePath = f"./{jobName}.zip"
9
10params = {
11    "jobName": jobName,
12}
13response = requests.post(base_url + "result", headers={'x-api-key': api_key}, json=params)
14print(response.text)
15
16if response.status_code == 200:
17    results = requests.get(response.text.replace('"', ''))
18    if results.status_code == 200:
19        with open(savePath, 'wb') as file:
20            file.write(results.content)

    Viewing Files

    The GET API endpoint /files allows users to see their uploaded files and folders.

    Optional Params:
    - includeFolders: Set to "true" to include folders in the response
    - folder: Path to folder to view files within that folder
    1import requests 
2api_key = "***************"
3base_url = "https://app.tamarind.bio/api/"
4
5response = requests.get(base_url + "files", headers={'x-api-key': api_key})
6print(response.json())

    Deleting Files

    The GET API endpoint /delete-file allows users to delete files from their account. You can either delete a single file by name or delete all files in a folder. If a filepath or folder is provided which does not exist, it returns a 400 error.

    Parameters (use either filePath OR folder, not both):
    - filePath: Name of the file to delete
    - folder: Path to folder - deletes all files in the specified folder
    1import requests 
2api_key = "***************"
3base_url = "https://app.tamarind.bio/api/"
4
5params = {
6  "filePath": "path/to/myFileName.txt"
7}
8response = requests.get(base_url + "delete-file", headers={'x-api-key': api_key}, params=params)
9print(response.text)

    Available Tools

    The GET API endpoint /tools allows users to see all available tools and their configurations. This returns an array of all tools you have access to along with their display names and configuration details. 

    1import requests
2
3api_key = "***************"
4base_url = "https://app.tamarind.bio/api/"
5
6response = requests.get(base_url + "tools", headers={'x-api-key': api_key})
7tools_data = response.json()
8print("Available tools:", tools_data)
9

    The settings array in the output contains the configuration parameters that can be used with the /submit-job endpoint.

    Please email us at info@tamarind.bio if you encounter any issues with your submissions, such as internal server errors. We'll get back to you within 12 hours!