Domino API

Much of Domino's functionality is available programmatically through our HTTP API and our Python binding.

Note that this is different from our API Endpoints functionality:

  • API Endpoints let you publish your code as a low-latency web service.
  • The Domino REST API lets you control Domino's functionality (e.g., starting and monitoring runs) programmatically.

Visit our new and improved REST API documentation

Read about our python wrapper for the Domino REST API



This legacy article which will no longer be updated has two parts:

  1. An overview of the REST API
  2. Details on the Python bindings

Domino API Documentation


To authenticate your request, simply include your API Key (which you can find on your account page) with the header X-Domino-Api-Key, e.g. curl -H 'X-Domino-Api-Key: API_KEY' -X POST ...

Starting a run<username>/<project_name>/runs
Start a run of a given script or command


Name Type Default Description
command array of strings required the command to run
isDirect boolean required a direct command interpretted as a shell command; Domino doesn't try to infer a program to match your file type
title string   a title for the run
tier string project default name of the hardware tier to use
commitId string latest revision at which to start the run
publishApiEndpoint boolean false if true, the results of a successful run will be deployed to the project's active API Endpoint, if one exists 

Sample request and response

curl -X POST \<username>/<project_name>/runs \
-H 'X-Domino-Api-Key: API_KEY' \
-H "Content-Type: application/json" \ -d '{"command": ["main.r", "foo", "1"], "isDirect": false}'

  "runId": "553af271e4b0364c0f717b24",
  "message": "Run for project <username>/<project_name> started. You can view progress here:<username>/<project_name>#r/553af271e4b0364c0f717b24"

Get Run info<username>/<project_name>/runs/<run_id>
Get info about a run, including its status


Name Type Default Description
runId string required ID of the run 

Sample request and response

curl<username>/<project_name>/runs/55238463e4b00c05a648f815 \
-H 'X-Domino-Api-Key: API_KEY'

  "id": "55238463e4b00c05a648f815",
  "projectId": "55221238e4b02f8c82189faa",
  "number": 19,
  "startingUserId": "551c3875e4b0f4c343c5bc91",
  "queued": 1428391011742,
  "started": 1428391015557,
  "completed": 1428391018043,
  "status": "Succeeded",
  "commitId": "981c1f5915724eb8882b1dffc6e7371c31ba638b",
  "outputCommitId": "ce42f26a45d842e636102474eb227262714a4536",
  "title": null,
  "isArchived": false,
"hardwareTierId": "d-free" }

List files<username>/<project_name>/files/<commitId>/<path>
Get a list of files in a commit


Name Type Default Description
commitId string required Revision of the project to access
path string / A specific directory to list

Sample request and response

curl<username>/<project_name>/files/ce42f26a45d842e636102474eb227262714a4536/results \
-H 'X-Domino-Api-Key: API_KEY'

  "object": "list",
  "url": "/v1/projects/<username>/<project_name>/files/885ecf33dcac86b37c28054e45b198194c222d08/results",
  "data": [
      "path": "results/myChart.png",
      "lastModified": 1427432389000,
      "size": 14292,
      "key": "d0839aebde28729fd96cfd0631cf7af1ac1c490f",
      "url": "<username>/<project_name>/blobs/d0839aebde28729fd96cfd0631cf7af1ac1c490f"
      "path": "results/stdout.txt",
      "lastModified": 1429926528000,
      "size": 843,
      "key": "625f85c90ddc02bd269a709489e796388e473599",
      "url": "<username>/<project_name>/blobs/625f85c90ddc02bd269a709489e796388e473599"

Get a file<username>/<project_name>/blobs/<key>
Get the contents of file from the project


Name Type Default Description
key string required The blob ID (viewable in the result of the list call)

Sample request and response

curl<username>/<project_name>/blobs/625f85c90ddc02bd269a709489e796388e473599 \
-H 'X-Domino-Api-Key: API_KEY'

Python Bindings

The Python binding for the Domino is installable via pip:

pip install git+

You can find Domino's public Python bindings project here.

Once installed, you'll need to get your API key from your Account page. The Python library will read this key from environment variables, so set it as follows in your shell:


If you are using the Python package in code that is already running in Domino, the DOMINO_API_USER_KEY variable will be set automatically to be the key for the user who started the run.

Here is an example of usage:

from domino import Domino

# By and large your commands will run against a single project,
# so you must specify the full project name
domino = Domino("chris/canon")

# List all runs in the project, most-recently queued first
all_runs = domino.runs_list()['data']

latest_100_runs = all_runs[0:100]


# all runs have a commitId (the snapshot of the project when the
# run starts) and, if the run completed, an "outputCommitId"
# (the snapshot of the project after the run completed)
most_recent_run = all_runs[0]

commitId = most_recent_run['outputCommitId']

# list all the files in the output commit ID -- only showing the
# entries under the results directory.  If not provided, will
# list all files in the project.  Or you can say path=“/“ to
# list all files
files = domino.files_list(commitId, path='results/')['data']

for file in files:
print file['path'], '->', file['url']


# Get the content (i.e. blob) for the file you're interested in.
# blobs_get returns a connection rather than the content, because
# the content can get quite large and it’s up to you how you want
# to handle it

# Start a run of file using the latest copy of that file
domino.runs_start(["", "arg1", "arg2"])

# Start a "direct" command
domino.runs_start(["echo 'Hello, World!'"], isDirect=True)

# Start a run of a specific commit
domino.runs_start([""], commitId="aabbccddee")
Was this article helpful?
0 out of 0 found this helpful