Design Hub developer guide - REST API

    Design Hub includes a token based API access layer. Authenticated users of the system can generate API keys to be used to authorize HTTP requests made by other applications, outside of active login sessions. Additionally, when using OpenIDConnect authentication, Bearer tokens issued by the identity provider can be used as well.

    Authorize requests with API key

    Use of most API endpoints requires a successful token based authentication. The user needs ACCESS_REST_API permission to be able to manipulate and view API tokens. The token can be obtained by opening the corner menu on the user interface and creating a new token. Here, previous tokens can be invalidated as well.

    access keys dialog

    Once a token has been obtained, specifying them on HTTP requests can be done in the X-API-KEY header:

    user:~/app$ curl -H "X-API-KEY: XFBg+9IVHhTRviLF1WOHgD0U2QS5Ww8oHqqG+405" "http://server:port/api/user"
    {
      "user_id": 1,
      "displayName": "Tester"
    }

    Authorize requests with Bearer tokens

    Use of most API endpoints requires a successful authentication. Using OpenIDConnect based authentication, users with valid access tokens can authorize requests using Bearer authentication. The token can be obtained from the identity provider.

    Once a token is available, specifying them on HTTP requests can be done on the Authorization header:

    user:~/app$ export TOKEN=eyJhbG...FaEyTA
    user:~/app$ curl -H "Authorization: Bearer $TOKEN" "http://server:port/api/domainname/user"
    {
      "user_id": 1,
      "displayName": "Tester"
    }

    Error codes

    Different HTTP errors are returned for incorrect authentication. The following spreadsheets describes which status code corresponds to which check.

    Status code Description
    400 Bad request X-API-KEY or Authorization header not specified on the request
    401 Unauthorized X-API-KEY value or Bearer token is invalid
    404 Not found HTTP path or method specified in the request doesn't exist

    Methods

    Get user details

    HTTP Request: GET /api/user

    Purpose: Provides basic information about the user authorized by the access token.

    Request headers: X-API-KEY required

    Response content-type: application/json

    Response body:

    {
      "user_id": number,
      "displayName": string
    }
    Property name Value Description
    user_id number internal identifier of the user
    displayName string user-specified display name

    Get projects

    HTTP Request: GET /api/projects

    Purpose: Provides list of projects accessible to the authorized user.

    Request headers: X-API-KEY required

    Response content-type: application/json

    Response body:

    [
      {
        "project_id": number,
        "label": string,
        "last_used": string
      }, ...
    }
    Property name Value Description
    project list list An unordered list of projects
    project list[*].project_id number Unique, internal identifier of the project.
    project list[*].label string Human friendly name of the project.
    project list[*].last_used string Serialized date object representing when this project was last used, in ISO date format, UTC timezone. May be used for sorting.

    Get hypotheses

    HTTP Request: GET /api/hypotheses

    Purpose: Provides list of hypotheses accessible to the authorized user.

    Request headers: X-API-KEY required

    Response content-type: application/json

    Query parameters:

    Parameter name type Description
    myprojects boolean (optional) Filter by projects to which the user is assigned
    project_id list of numbers Filter by a comma separated list of project identifiers to which the hypotheses belong

    Response body:

    [
      {
        "content_id": string,
        "title": string,
        "tags": string,
        "create_date": string,
        "modify_date": string,
        "project_id": number
      }, ...
    }
    Property name Value Description
    hypothesis list list An unordered list of hypotheses.
    hypothesis list[*].content_id string Unique, internal identifier of the hypothesis.
    hypothesis list[*].title string Human friendly name of the hypothesis.
    hypothesis list[*].tags List of string A list of tags assigned to the hypothesis.
    hypothesis list[*].create_date string The date when the hypothesis was created, in ISO date format, UTC timezone.
    hypothesis list[*].modify_date string The date when the hypothesis was last changed, in ISO date format, UTC timezone.
    hypothesis list[*].project_id number The unique identifier of the project.

    Get design sets

    HTTP Request: GET /api/designsets

    Purpose: Provides list of design sets accessible to the authorized user.

    Request headers: X-API-KEY required

    Response content-type: application/json

    Query parameters:

    Parameter name type Description
    project_id list of numbers Filter by a comma separated list of project identifiers to which the design sets belong

    Response body:

    [
      {
        "content_id": string,
        "parent_id": string,
        "title": string,
        "tags": string,
        "create_date": string,
        "modify_date": string,
        "parent_title": string,
        "parent_content_id": string
      }, ...
    }
    Property name Value Description
    design set list list An unordered list of design sets.
    design set list[*].content_id string Unique, internal identifier of the design set.
    design set list[*].title string Human friendly name of the design set.
    design set list[*].tags List of string A list of tags assigned to the design set.
    design set list[*].create_date string The date when the design set was created, in ISO date format, UTC timezone.
    design set list[*].modify_date string The date when the design set was last changed, in ISO date format, UTC timezone.
    design set list[*].parent_title string The design set's parent title.
    design set list[*].parent_content_id string The design set's parent unique, internal identifier.

    List compounds and IDs

    HTTP Request: GET /api/compounds/public

    Purpose: Provides all IDs and compounds publicly available in the system. May be used to make Design Hub generated IDs usable in other systems.

    Request headers : X-API-KEY required

    Response content-type: application/json

    Query parameters:

    Parameter name type Description
    offset number (optional) number of compounds to skip in the beginning of the list, default 0
    limit number (optional) maximum size of list, default based on Design Hub config parameter limitPublicCompoundsListSize

    Response body:

    {
      "compounds": [
        {
          "currentId": string,
          "previousIds": [ string, ... ],
          "source": string,
          "url": string
        },
        ...
      ],
      "total": number,
      "limit": number,
      "offset": number
    }
    Property name Value Description
    compounds list A list of compound records ordered by record creation date
    compounds[*].currentId string Latest known ID of the compound, e.g. "CXN-123456"
    compounds[*].previousIds list of strings List of previously known IDs of the compound, e.g.: ["VXN-1234567"]
    compounds[*].source string MRV formatted source of the compound
    compounds[*].url string A root relative URL to the compound's dedicated webpage, e.g.: "/compounds/find/CXN-123456"
    total number Number of all public compounds that can be obtained using this endpoint
    offset number Index of the first compound in this result set
    limit number Number of compounds requested

    Attach data to compound

    HTTP Request: POST /api/compounds/:id/attach

    Purpose: allows attaching generated files, and comments to a compound

    Request headers : X-API-KEY required

    Response content-type: application/json

    URL parameters:

    Parameter name type Description
    id string the content ID of the selected compound

    Request parameters:

    Parameter name type Description
    link string A single URL (https://) to be attached to the compound as a comment
    comment string A free text comment to be added to the compound
    files array of objects A list of generated files to attach to the compound
    files[*].fileName string name of the file
    files[*].content string plain text contents of the file for text or xml files
    files[*].contentBase64 string base64 encoded contents of the file for binary files
    files[*].mimeType string mime type hint for the file - for certain mime types thumbnail images may be generated

    Response body:

    {
      "contentUrl": string
    }

    Export compounds data

    HTTP Request: GET /api/compounds/export

    Purpose: allows the export of compounds data using filters

    Request headers : X-API-KEY required

    Response content-type: application/json

    Query parameters:

    Parameter name type Description
    offset number number of compounds to skip in the beginning of the list, default 0
    limit number maximum size of list, default based on Design Hub config parameter limitPublicCompoundsListSize
    registration_ids string a comma separated list of latest known ID of the compounds
    project_label string a project label
    hypothesis_content_ids string comma separated list of hypotheses identifiers
    hypothesis string comma separated hypothesis titles
    designset_content_ids string a comma separated list of design set identifiers
    designset string comma separate list of design set titles
    status string comma separated list of compound statuses; e.g. Draft, Ready for review, ...
    author string comma separated list of display names of compound authors
    assignee string comma separated list of display names for compound assignees
    structure string chemical query structure in SMARTS or CXSMARTS format
    searchType string chemical search type. One of sss, sim, or dup. Default: sub.
    create_date string a relative date filter to show compounds that were created within the desired time frame; accepted values are from this set: [1d, 1w, 1m, 3m, 1y, 10y]
    create_date_before Date in ISO8601 format in UTC the creation date of the compound has to be before this date. If a value for create_date is given, this parameter will be ignored.
    create_date_after Date in ISO8601 format in UTC the creation date of the compound has to be after this date. If a value for create_date is given, this parameter will be ignored.
    modify_date string a relative date filter to show compounds that were modified within the desired time frame; accepted values are from this set: [1d, 1w, 1m, 3m, 1y, 10y]
    modify_date_before Date in ISO8601 format in UTC the last modification date of the compound has to be before this date. If a value for modify_date is given, this parameter will be ignored.
    modify_date_after Date in ISO8601 format in UTC the last modification date has to be after this date. If a value for modify_date is given, this parameter will be ignored.
    visibility string tharing related state of a compound. One of: private, public or mixed. Default: mixed.

    Response body:

    {
      "compounds": [
        {
          "id": string,
          "private": boolean,
          "project_label": string,
          "project_key": string,
          "designset": string,
          "hypothesis": string,
          "author": string,
          "assignee": string,
          "create_date": string,
          "modify_date": string,
          <calculated data fields>
        },
        ...
      ],
      "total": number,
      "limit": number,
      "offset": number,
      "hasMore": boolean
    }
    Property name Value Description
    compounds list A list of compound records ordered by record creation date.
    compounds[*].id string Latest known ID of the compound, e.g. "CXN-123456".
    compounds[*].private boolean Visibility of the compound.
    compounds[*].project_label string The project to which this compound belongs.
    compounds[*].project_key string The project identifier to which the compound belongs.
    compounds[*].designset_title string The design set title to which the compound belongs.
    compounds[*].designset_content_id string The design set identifier to which the compound belongs.
    compounds[*].hypothesis_title string The hypothesis title to which the compound belongs.
    compounds[*].hypothesis_content_id string The hypothesis identifier to which the compound belongs.
    compounds[*].author string The username of the compound's author.
    compounds[*].assignee string The username of the user to which the compound is assigned.
    compounds[*].create_date string The date when the compund was created, in ISO date format, UTC timezone.
    compounds[*].modify_date string The date when the compund was last changed, in ISO date format, UTC timezone.
    compounds[*].source string MRV formatted source of the compound.
    compounds[*].<calculated data fields> string|number|boolean Additional fields containing calculated date for the compound.
    total number Number of all public compounds that can be obtained using this endpoint.
    offset number Index of the first compound in this result set.
    limit number Number of compounds requested.
    hasMore boolean Indicates that there are more compunds matching the specified filters.

    Multipart form upload

    HTTP Request: POST /upload/api

    Purpose: Provides a way for simple web sites to send molecules to Design Hub.

    Request content-type: multipart/form-data

    Request body: a chemical structure file recognized by Chemaxon IO system

    Response content-type: application/json

    Response body: a HTTP redirect that should be opened by the user's browser

    Example:

    A curl command produces valid multipart request, when the data flag refers to a file using the @ symbol:

    user:~/app$ curl -X POST -F structures=@/path/to/file/filename.sdf "http://localhost:8888/upload/api"

    A browser form with a file input also produces a valid multipart request, when the form’s action attribute and the file input’s name attribute are specified as below:

    <form action="http://design-hub-example.com/upload/api" enctype="multipart/form-data" method="post">
      <input type="file" name="structures" />
      <button>Upload</button>
    </form>

    When submitted, this sends the following HTTP request:

    POST /upload/api HTTP/1.1
    Host: design-hub-example.com
    Content-Type: multipart/form-data; boundary="the_boundary"
    Content-Length: number_of_bytes_in_entire_request_body
    --the_boundary
    Content-Disposition: form-data; name="structures"; filename="records.mrv"
    Content-Type: application/octet-stream
    
    Chemical file data
    --the_boundary--

    If the request succeeds, the server returns HTTP 302 Moved temporarily status code, along with a redirect URL containing a unique ID that references the parsed contents of the file. Integrating applications should open this URL in the user’s browser. This unique URL is valid for 5 minutes.

    HTTP/1.1 302
    Location: /new/compound/?cache=1164293e37ca9d47cbdfded5

    JSON upload

    HTTP Request: POST /upload/api

    Purpose: Provides a way for applications to send molecules to Design Hub.

    Request content-type: application/json

    Request body:

    Property name Value Description
    structures string A string serialized representation of a chemical structure file recognized by Chemaxon IO system

    Response content-type : application/json

    Response body : a JSON object including the following properties:

    Property name Value Description
    url string a root relative URL (path) that should be opened by the user's browser

    Example:

    A valid request has the Content-Type of application/json and the body contains a JSON structure, with the file contents under the structures key:

    POST /upload/api HTTP/1.1
    Host: design-hub-example.com
    Content-Type: application/json
    Content-Length: number_of_bytes_in_entire_request_body
    { "structures": "chemical file data" }

    If the request succeeds, the server returns a simple JSON object containing a unique URL that references the parsed contents of the file. Integrating applications should open this URL in the user’s browser. This unique URL is valid for 5 minutes.

    HTTP/1.1 200
    {
      "url": "/new/compound/?cache=1164293e37ca9d47cbdfded5"
    }