Full Neurosnap API Tutorial | The Quick & Easy API For Bioinformatics

Written by Keaun Amani

Published 2024-8-4

Introduction

We are excited to announce the official release of the Neurosnap API, a highly anticipated and requested feature that allows seamless interaction with the Neurosnap platform. With this new API, users can automate complex bioinformatic pipelines from any computer without the need to install or run intricate models themselves. This release marks a significant milestone in making advanced bioinformatics more accessible and user-friendly.

Please keep in mind that this tutorial and the Neurosnap API are designed to be used by those with at least a basic understanding of programming and networking concepts.

Accessing The API

To access the Neurosnap API you will need to first generate an API key for your account. If you've ever used a rest API in the past, this part will likely be quite familiar.

Visit your overview page's API tab.
Click on the Generate API Key button.
Save the resulting API key and make sure not to share it. Anybody that has access to your API key can access everything on your Neurosnap account. Treat your API key as confidential (similar to how you would treat a password) and never share your API key or post it online.

API Endpoints

The following is the list of all endpoints currently offered by the Neurosnap platform. Note that almost all API endpoints return data in the JSON format. Exceptions will be clearly specified below.

Job Endpoints

Job endpoints are HTTP endpoints related to neurosnap services and submitted jobs for those services.

`/api/services`

Lists all currently available Neurosnap services.

r = requests.get("https://neurosnap.ai/api/services", headers={"X-API-KEY": YOUR_API_KEY})
r.json()
# [
#   {
#     "beta": false,
#     "title": "NeuroFold",
#     "desc": "The most accurate approach for in silico enzyme optimization. NeuroFold makes it trivial to optimize multiple enzyme properties, simultaneously.",
#     "desc_short": "Optimize enzyme thermostability, pH stability, solubility, and reaction rate with high accuracy.",
#     "paper": "https://doi.org/10.1101/2024.03.12.584504",
#     "video": "",
#     "tags": [
#       "Protein Design",
#       "Protein Stability",
#       "Protein Solubility"
#     ],
#     "features": [
#       "Utilizes our proprietary NeuroFold model to optimize enzymes.",
#       "40-fold increase in Spearman rank correlation when compared to Meta's ESM-1v model.",
#       "Can optimize the thermostability, pH stability, and reaction rate of a target enzyme.",
#       "Output sequences tend to be evolutionarily distinct and diverse.",
#       "Typical sequence identity to wild type is around 49-56%.",
#       "When tested on \u03b2-lactamase, NeuroFold was found to have a 100% experimental success rate.",
#       "Currently only supports monomeric enzymes that do not form complex interactions with nucleotides."
#     ],
#     "citations": [
#       "Keaun Amani, Michael Fish, Matthew D. Smith, Christian Danve M. Castroverde\nbioRxiv 2024.03.12.584504; doi: https://doi.org/10.1101/2024.03.12.584504"
#     ]
#   },
#   ...
# ]

`/api/jobs`

Lists your accounts submitted jobs.

r = requests.get("https://neurosnap.ai/api/jobs", headers={"X-API-KEY": YOUR_API_KEY})
r.json()
# [
#   {
#     "Status": "completed",
#     "Job ID": "66aea7b235c83718af6161d5",
#     "Service": "PDBFixer",
#     "Submitted": 1722722226000,
#     "Runtime": "31s",
#     "Note": "test job binder + membrane",
#     "Shared": false
#   },
#   {
#     "Status": "completed",
#     "Job ID": "66ae52068d3b43e471e39c13",
#     "Service": "AntiFold",
#     "Submitted": 1722700294000,
#     "Runtime": "35s",
#     "Note": "test job using 8DXT",
#     "Shared": false
#   },
#   ...
# ]

`/api/job/submit/SERVICE_NAME`

Submit a Neurosnap job. SERVICE_NAME needs to be replaced with the exact name of the service. For example consider the following DiffDock-L job example. Note that this endpoint receives information in the format of multipart/form-data. Every field needs to be present in order for the endpoint to accept the request. If you're unsure of what fields to provide as input, always reference the service's submission panel page. If the job is successfully submitted this endpoint will return a job ID in JSON format.

r = requests.post(
  "https://neurosnap.ai/api/job/submit/DiffDock-L",
  headers={"X-API-KEY": YOUR_API_KEY},
  files={
    "Input Structure": open("structures/receptor.pdb"), # the python requests package let's us upload file inputs by providing the path to the file
  },
  data={
    "Input Ligand (SMILES)": "NC1CC(C(O)Cl)OC(N)P1",
    "Number Samples": "100", # since this field is a multiple choice field the values must be provided as a string, even if they are numbers.
  },
)
r.json()
# '66affe9ca8c3d6ab6d8e377e'

`/api/job/status/JOB_ID`;

Fetches the status of a specified job. Job statuses can include pending, running, complete, failed, and completed.

r = requests.get(
  "https://neurosnap.ai/api/job/status/66affe9ca8c3d6ab6d8e377e",
  headers={"X-API-KEY": YOUR_API_KEY},
)
r.json()
# 'completed'

`/api/job/files/JOB_ID/[in/out]?share=SHARE_ID`

Fetches all the files from a completed Neurosnap job. This endpoint requires you to specify whether you want to fetch all the input files (files you uploaded to run the job) or fetch all the output files (files produced during the Neurosnap job by the service). For shared / public jobs you can optionally provide the share ID as a query parameter as well. This is not required and job sharing is disabled by default.

r = requests.get(
  "https://neurosnap.ai/api/job/files/66affe9ca8c3d6ab6d8e377e/out", # fetch output files of a job
  headers={"X-API-KEY": YOUR_API_KEY},
)
r.json()
# '66affe9ca8c3d6ab6d8e377e'

`/api/job/file/JOB_ID/[in/out]/FILE_NAME?share=SHARE_ID`;

Fetches a specific file to download from a completed Neurosnap job. This endpoint requires you to specify whether you want to fetch an input file (file you uploaded to run the job) or fetch an output file (file produced during the Neurosnap job by the service). For shared / public jobs you can optionally provide the share ID as a query parameter as well. This is not required and job sharing is disabled by default.

r = requests.get(
  "https://neurosnap.ai/api/job/file/66affe9ca8c3d6ab6d8e377e/out/output.json", # fetch a file called output.json
  headers={"X-API-KEY": YOUR_API_KEY},
)
# save the file to disk
with open("output.json", "wb") as f:
  f.write(r.content)

`/api/job/note/set`;

Set a note for a submitted job. Notes can be thought of as mini descriptions that you can assign to your jobs for convenience and organizational purposes.

r = requests.post(
  "https://neurosnap.ai/api/job/status/66affe9ca8c3d6ab6d8e377e",
  headers={"X-API-KEY": YOUR_API_KEY},
  json={"job_id": "66affe9ca8c3d6ab6d8e377e", "note": "Binder design against target PDCD1."}
)
r.raise_for_status() # no content in response but can raise if status code is not 200

`/api/job/share/set/JOB_ID`;

Enables the sharing feature of a job and makes it public to anybody with the job ID and share ID. Note that sharing is always disabled by default and that enabling it means that anybody with the job ID and share ID will be able to access the job results and inputs (only for jobs with sharing enabled).

r = requests.get(
  "https://neurosnap.ai/api/job/share/set/66affe9ca8c3d6ab6d8e377e",
  headers={"X-API-KEY": YOUR_API_KEY},
)
r.json()
# '66affe9ca8c3d6ab6d8e377e' #the new share ID of the job

`/api/job/share/delete/JOB_ID`;

Disables the sharing feature of a job and makes the job private. Note that sharing is always disabled by default.

r = requests.get(
  "https://neurosnap.ai/api/job/share/delete/66affe9ca8c3d6ab6d8e377e",
  headers={"X-API-KEY": YOUR_API_KEY},
)
r.raise_for_status() # no content in response but can raise if status code is not 200

Team Endpoints

Team endpoints are HTTP endpoints related to viewing and managing Neurosnap Teams.

`/api/teams/info`;

Fetches your team's information if you are part of a Neurosnap Team.

r = requests.get(
  "https://neurosnap.ai/api/teams/info",
  headers={"X-API-KEY": YOUR_API_KEY},
)
r.json()
# {
#   "is_leader": true,
#   "jobsCount": 516,
#   "jobsExcess": 0,
#   "jobsPrepaid": 1000,
#   "members": [
#     {
#       "ID": "66affe9ca8c3d6ab6d8e377e",
#       "Name": "Mario",
#       "Email": "mario@neurosnap.ai",
#       "LastLogin": 1722810058,
#       "EmailVerified": true,
#       "Leader": true
#     },
#     {
#       "ID": "64da8b62ad82b9c2bc36b143",
#       "Name": "Luigi",
#       "Email": "luigi@neurosnap.ai",
#       "LastLogin": 1722616210,
#       "EmailVerified": true,
#       "Leader": false
#     }
#   ],
#   "name": "Mario Brothers Plumbing Inc.",
#   "seatsMax": 2
# }

`/api/teams/jobs`;

Fetches all the jobs submitted by all members of your Neurosnap Team.

r = requests.get(
  "https://neurosnap.ai/api/teams/jobs",
  headers={"X-API-KEY": YOUR_API_KEY},
)
r.json()
# [
#   {
#     "Status": "completed",
#     "Job ID": "66aea7b235c83718af6161d5",
#     "Service": "PDBFixer",
#     "Submitted": 1722722226000,
#     "Runtime": "31s",
#     "Note": "test job binder + membrane",
#     "Shared": false
#   },
#   {
#     "Status": "completed",
#     "Job ID": "66ae52068d3b43e471e39c13",
#     "Service": "AntiFold",
#     "Submitted": 1722700294000,
#     "Runtime": "35s",
#     "Note": "test job using 8DXT",
#     "Shared": false
#   },
#   ...
# ]

Conclusion

Congrats on making it this far! You should now be equipped with everything you need to know in order to successfully and effectively utilize the Neurosnap API. Just keep in mind that we have plans to greatly expand the capabilities of our API and that changes to the existing API structure are certainly possible. Make sure to keep referencing this page for updates.

Accelerate your lab's
research today

Interested in getting a license? Contact Sales.

Introduction

Accessing The API

API Endpoints

Job Endpoints

/api/services

/api/jobs

/api/job/submit/SERVICE_NAME

/api/job/status/JOB_ID;

/api/job/files/JOB_ID/[in/out]?share=SHARE_ID

/api/job/file/JOB_ID/[in/out]/FILE_NAME?share=SHARE_ID;

/api/job/note/set;

/api/job/share/set/JOB_ID;

/api/job/share/delete/JOB_ID;