Getting Started with the API

Sphinx’s API lets your programmatically interact with the application. This lets you automate your work or integrate Sphinx with other applications you use.

Before you begin

To get access to the API, you first must create an account in Sphinx. If you haven’t already, you can sign up here

Sending your first API request

To send an API request, you need to get up an API Key from your profiles page. Once you have it you can try it out in the command line.

  curl -H "Authorization: Bearer YOUR_API_KEY" https://api.sphinxbio.com/v1/campaigns

Storing your API Key

Your API Key is like your password to Sphinx. It should be stored securely!

Working with paginated responses

The Spinx API returns results subject to the limit parameter (when passed). Results for an endpoint may exceed limit for a single response, in which case you will need to pass the nextToken. Passing the nextToken returns the next set of results. This can be repeated until a nextToken is no longer provided.

An example script for listing Datasets is below. Replace your endpoint as required.

1 API_KEY = '<Your Key Here>'
2 response = requests.get(f"https://api.sphinxbio.com/v1/datasets/{dataset_id}", headers={"Authorization": f"Bearer {API_KEY}"}).json()
3 
4 if response.get('nextToken') is not None:
5     params = {'nextToken': response['nextToken']}
6     _response = requests.get(f"https://api.sphinxbio.com/v1/datasets/{dataset_id}", params=params, headers={"Authorization": "Bearer {access_token}"}).json()
7   response.append(_response)
8 else:
9     response = 0

Working with Signed URLs

Some resources in the API returned a signedUrl which allows for their download. To work with these you can treat them as a file. Here is an example in python.

1 import requests
2 
3 url = requests.get("https://api.sphinxbio.com/v1/plots/plot_12345/download", headers={"Authorization": "Bearer {access_token}"}).json()["signedUrl"]
4 response = requests.get(url)
5 with open("plot.svg", "wb") as f:
6     f.write(response.content)

Working with Tasks

Some resources in the API are returned after a task processes their download. You must wait until the task is complete before a signedUrl is provided.

An example script for requesting a Datatable is below.

1 import requests
2 import pandas as pd
3 import time
4 task_id = requests.get("https://api.sphinxbio.com/v1/datatables/dt_12345/download", headers={"Authorization": "Bearer {access_token}"}).json()["taskId"]
5 task_status = "PROCESSING"
6 while task_status != "SUCCESS":
7     time.sleep(1)
8     task_response = requests.get(f"https://api.sphinxbio.com/v1/tasks/{task_id}", headers={"Authorization": "Bearer {access_token}"}).json()
9     task_status = task_response["status"]
10 df = pd.read_csv(task_response["result"]["signedUrl"])

1	API_KEY = '<Your Key Here>'
2	response = requests.get(f"https://api.sphinxbio.com/v1/datasets/{dataset_id}", headers={"Authorization": f"Bearer {API_KEY}"}).json()
3
4	if response.get('nextToken') is not None:
5	params = {'nextToken': response['nextToken']}
6	_response = requests.get(f"https://api.sphinxbio.com/v1/datasets/{dataset_id}", params=params, headers={"Authorization": "Bearer {access_token}"}).json()
7	response.append(_response)
8	else:
9	response = 0

1	import requests
2
3	url = requests.get("https://api.sphinxbio.com/v1/plots/plot_12345/download", headers={"Authorization": "Bearer {access_token}"}).json()["signedUrl"]
4	response = requests.get(url)
5	with open("plot.svg", "wb") as f:
6	f.write(response.content)

1	import requests
2	import pandas as pd
3	import time
4	task_id = requests.get("https://api.sphinxbio.com/v1/datatables/dt_12345/download", headers={"Authorization": "Bearer {access_token}"}).json()["taskId"]
5	task_status = "PROCESSING"
6	while task_status != "SUCCESS":
7	time.sleep(1)
8	task_response = requests.get(f"https://api.sphinxbio.com/v1/tasks/{task_id}", headers={"Authorization": "Bearer {access_token}"}).json()
9	task_status = task_response["status"]
10	df = pd.read_csv(task_response["result"]["signedUrl"])