1. Introduction

Running Everest applications via Web UI is easy and convenient, but it has some limitations. For example, if you want to run an application many times with different inputs, it is inconvenient to submit many jobs manually via web form. In other case, if you want to produce some result by using multiple applications, you will have to manually copy data between several jobs. Finally, Web UI is not suitable if you want to run Everest application from your program or some other external application.

For all these cases, from automation of repetitive tasks to application integration, Everest provides a REST API. It is the platform’s application programming interface implemented as a RESTful web service. REST API includes operations for accessing and managing applications, jobs, resources and other entities. This interface serves as a single entry point for all Everest clients, including Web UI which uses REST API under the hood.

Since the API is based on REST principles, it’s very easy to write and test applications. You can use your browser to access URLs, and you can use pretty much any HTTP client in any programming language to interact with the API. Everest also provides a ready-to-use Python client library built on top of REST API.

1.1. Base URL

All URLs referenced in the documentation have the following base:

https://everest.distcomp.org/api

Everest API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

1.2. API Overview

Resources-methods matrix

GET POST PUT DELETE

/auth/access_token

Obtain access token

Delete access token

/api/apps

List applications

Create application

/api/apps/:id

Get app description

Run app (submit job)

Modify application

Delete application

/api/jobs

List jobs

/api/jobs/:id

Get job status

Delete job

/api/jobs/:id/cancel

Cancel job

/api/files/

Upload file

/api/files/:id/:name

Download file

Delete file

2. Authentication

In order to make authorized calls to Everest API, your application must first obtain an access token on behalf of an Everest user.

All requests (except obtaining access token) should include a valid access token in the Authorization request header field using the Bearer authentication scheme:

Authorization: Bearer ACCESS_TOKEN

2.1. Obtain access token

2.1.1. Request

POST /auth/access_token HTTP/1.1
Content-Type: application/json

{
  "username": "alice",
  "password": "secret",
  "label": "my client"
}
Attribute Type Required Description

username

string

Yes

Username

label

string

Yes

Password

password

string

Yes

Token label used to distinguish tokens (need not to be unique). For example, it can be the name of the client application.

2.1.2. Response

200 OK
Content-Type: application/json

{
  "access_token": "abcdef123345"
}
Attribute Type Required

Description

access_token

string

2.1.3. Errors

HTTP Status Code Reason

400 Bad Request

The request doesn’t conform to API specification.

401 Unauthorized

Wrong password or username.

422 Unprocessable Entity

The request is not a valid JSON.

500 Internal Server Error

An exception occured while processing request.

2.2. Delete current access token

2.2.1. Request

DELETE /auth/access_token HTTP/1.1

2.2.2. Response

200 OK

2.2.3. Errors

HTTP Status Code Reason

400 Bad Request

The request doesn’t conform to API specification.

500 Internal Server Error

An exception occured while processing request.

3. Applications

3.1. List applications

3.1.1. Request

GET /apps HTTP/1.1

3.1.2. Response

200 OK
Content-Type: application/json

[
  {
    "id": "53a56f403000007300136697",
    "name": "AutoDock Vina",
    "annotation": "Open-source program for doing molecular docking",
    "keywords": ["AutoDock", "molecular docking", "computer-aided drug design"],
    "owner": "bob",
    "resources": [],
    "resourceOverride": true
  },
  ...
]
Attribute Type Required Description

id

string

Yes

Application Id

name

string

Yes

Application name

annotation

string

Yes

Application annotation

keywords

string[]

No

Application keywords

owner

string

Yes

Application owner

resources

string[]

Yes

Default application resources (can be empty)

resourceOverride

boolean

Yes

Flag indicating whether resource override is enabled

3.1.3. Errors

HTTP Status Code Reason

401 Unauthorized

Cannot authenticate request (access token is not found or expired, or user is not found).

500 Internal Server Error

An exception occured while processing request.

3.2. Get application description

3.2.1. Request

GET /apps/53a56f403000007300136697 HTTP/1.1

3.2.2. Response

200 OK
Content-Type: application/json

{
  "id": "53a56f403000007300136697",
  "name": "AutoDock Vina",
  "annotation": "Open-source program for doing molecular docking",
  "keywords": ["AutoDock", "molecular docking", "computer-aided drug design"],
  "description": "...",
  "inputs": {
    "receptor": {
      "title": "Receptor",
      "description": "rigid part of the receptor (PDBQT)",
      "type": "string",
      "format": "uri",
      "required": true
    },
    ...
  },
  "outputs": {
    "output": {
      "title": "Output",
      "description": "output models (PDBQT)",
      "type": "string",
      "format": "uri",
      "required": true
    },
    ...
  },
  "owner": "alice",
  "resources": [],
  "resourceOverride": true,
  "permissions": ["run"]
}
Attribute Type Required Description

id

string

Yes

Application Id

name

string

Yes

Application name

annotation

string

Yes

Annotation

keywords

string[]

No

Keywords

description

string

No

Full-text description

inputs

object

Yes

Input parameters

outputs

object

Yes

Output parameters

owner

string

Yes

Application owner

resources

string[]

Yes

Default application resources (can be empty)

resourceOverride

boolean

Yes

Flag indicating whether resource override is enabled

permissions

string[]

Yes

List of allowed app actions for current user ("run", "edit")

3.2.3. Errors

HTTP Status Code Reason

401 Unauthorized

Cannot authenticate request (access token is not found or expired, or user is not found).

403 Forbidden

User is not allowed to access the application.

404 Not Found

Application is not found.

500 Internal Server Error

An exception occured while processing request.

3.3. Run application (submit job)

3.3.1. Request

POST /apps/53a56f403000007300136697 HTTP/1.1
Content-Type: application/json

{
  "name": "Docking XY1",
  "inputs": {
    "receptor": "/api/files/542026f52f000077003bcdfb/protein.pdbqt",
    "ligand": "/api/files/542026f72f000077003bcdfc/ligand.pdbqt",
    "center_x": 11,
    "center_y": 90.5,
    "center_z": 57.5,
    "size_x": 22,
    "size_y": 24,
    "size_z": 28,
    "exhaustiveness": 8
  },
  "resources": [
    "53ad28ca35000042009832de"
  ]
}
Attribute Type Required Description

name

string

Yes

Job name

inputs

object

Yes

Input values

resources

string[]

No

Resources to run the job

3.3.2. Response

200 OK
Location: https://everest.distcomp.org/api/jobs/54202bb12f000032013bcdfd
Content-Type: application/json

{
  "id": "54202bb12f000032013bcdfd",
  "name": "AutoDock Vina",
  "app": "53a56f403000007300136697",
  "user": "alice",
  "created": 1393766008,
  "state": "SCHEDULED",
  "inputs": { ... },
  "allowList": []
}

See Get job status section for description of job attributes.

3.3.3. Errors

HTTP Status Code Reason

400 Bad Request

The request doesn’t conform to API specification and/or application input requirements.

401 Unauthorized

Cannot authenticate request (access token is not found or expired, or user is not found).

403 Forbidden

User is not allowed to run the application.

404 Not Found

Application is not found.

422 Unprocessable Entity

The request is not a valid JSON.

500 Internal Server Error

An exception occured while processing request.

4. Jobs

4.1. List jobs

4.1.1. Request

GET /jobs HTTP/1.1

4.1.2. Response

200 OK
Content-Type: application/json

[
  {
    "id": "54202bb12f000032013bcdfd",
    "name": "AutoDock Vina",
    "app": "53a56f403000007300136697",
    "user": "alice",
    "created": 1393766008,
    "state": "SCHEDULED",
    "inputs": { ... },
    "allowList": []
  }
  ...
]

See Get job status section for description of job attributes.

4.1.3. Errors

HTTP Status Code Reason

401 Unauthorized

Cannot authenticate request (access token is not found or expired, or user is not found).

500 Internal Server Error

An exception occured while processing request.

4.2. Get job status

4.2.1. Request

GET /jobs/54202bb12f000032013bcdfd HTTP/1.1

4.2.2. Response

200 OK
Content-Type: application/json

{
  "id": "54202bb12f000032013bcdfd",
  "name": "AutoDock Vina",
  "app": "53a56f403000007300136697",
  "user": "alice",
  "created": 1393766008,
  "state": "DONE",
  "inputs": {
    "receptor": "/api/files/542026f52f000077003bcdfb/protein.pdbqt",
    "ligand": "/api/files/542026f72f000077003bcdfc/ligand.pdbqt",
    "center_x": 11,
    "center_y": 90.5,
    "center_z": 57.5,
    "size_x": 22,
    "size_y": 24,
    "size_z": 28,
    "exhaustiveness": 8
  },
  "allowList": [],
  "result": {
    "output":"/api/files/542033492f000032003bce01/ligand_out.pdbqt",
    "log":"/api/files/542033492f000032003bce02/log.txt"
  }
}
Attribute Type Required Description

id

string

Yes

Job Id

name

string

Yes

Application name

app

string

Yes

Application Id

user

string

Yes

Job owner

created

integer

Yes

Job submission time (Unix timestamp)

state

string

Yes

Current job state which can take one of the following values:

  • SUBMITTED - the job is accepted and stored for further processing

  • DEFERRED - the job is accepted but will be processed after the planned server restart

  • READY - the job is processed, job tasks are generated and ready for scheduling

  • SCHEDULED - the job tasks are scheduled to resources

  • RUNNING - the job tasks are running on resources

  • DONE - the job is successfully completed and its outputs are available

  • FAILED - the job is failed

  • CANCELLED - the job is cancelled

inputs

object

Yes

Input parameter values specified during job submission

allowList

string[]

Yes

List of users (except the job owner) allowed to see the job data

result

object

No

Output parameter values produced by the job (available only for jobs in DONE state)

info

string

No

Additional information about the job state, e.g., error message for a failed job.

4.2.3. Errors

HTTP Status Code Reason

401 Unauthorized

Cannot authenticate request (access token is not found or expired, or user is not found).

403 Forbidden

User is not allowed to access the job.

404 Not Found

Job is not found.

500 Internal Server Error

An exception occured while processing request.

4.3. Cancel job

4.3.1. Request

POST /jobs/54202bb12f000032013bcdfd/cancel HTTP/1.1

4.3.2. Response

200 OK

4.3.3. Errors

HTTP Status Code Reason

400 Bad Request

Job cannot be cancelled.

401 Unauthorized

Cannot authenticate request (access token is not found or expired, or user is not found).

403 Forbidden

User is not allowed to modify the job.

404 Not Found

Job is not found.

500 Internal Server Error

An exception occured while processing request.

4.4. Delete job

4.4.1. Request

DELETE /jobs/54202bb12f000032013bcdfd HTTP/1.1

4.4.2. Response

200 OK

4.4.3. Errors

HTTP Status Code Reason

401 Unauthorized

Cannot authenticate request (access token is not found or expired, or user is not found).

403 Forbidden

User is not allowed to delete the job.

404 Not Found

Job is not found.

500 Internal Server Error

An exception occured while processing request.

5. Files

5.1. Upload file

5.1.1. Request

POST /files/ HTTP/1.1
Content-Type: ...

FILE CONTENTS...

5.1.2. Response

200 OK
Content-Type: application/json

{
  "id": "542026f52f000077003bcdfb",
  "filename": "protein.pdbqt",
  "length": 216232,
  "uri": "/api/files/542026f52f000077003bcdfb/protein.pdbqt"
}

5.1.3. Errors

HTTP Status Code Reason

401 Unauthorized

Cannot authenticate request (access token is not found or expired, or user is not found).

500 Internal Server Error

An exception occured while processing request.

5.2. Download file

5.2.1. Request

GET /files/542026f52f000077003bcdfb/protein.pdbqt HTTP/1.1

5.2.2. Response

200 OK
Content-Type: ...

FILE CONTENTS...

5.2.3. Errors

HTTP Status Code Reason

401 Unauthorized

Cannot authenticate request (access token is not found or expired, or user is not found).

403 Forbidden

User is not allowed to access the file.

404 Not Found

File is not found.

500 Internal Server Error

An exception occured while processing request.

5.3. Delete file

5.3.1. Request

DELETE /files/542026f52f000077003bcdfb/protein.pdbqt HTTP/1.1

5.3.2. Response

200 OK

5.3.3. Errors

HTTP Status Code Reason

401 Unauthorized

Cannot authenticate request (access token is not found or expired, or user is not found).

403 Forbidden

User is not allowed to delete the file.

404 Not Found

File is not found.

500 Internal Server Error

An exception occured while processing request.