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,
    "key": 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[*].key string Unique identifier 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
    format string (optional) output compound format supported by JChem Microservices IO. See file formats here

    Response body:

    {
  "compounds": [
    {
      "content_id": string,
      "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[*].content_id string Internal ID of the compound, e.g. "9d9c663085df0d12e5e826107eefcd5dcd99d06a"
    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 formatted source of the compound (formatted by provided format, MRV if format not provided)
    compounds[*].url string A root relative URL to the compound's dedicated webpage, e.g.: "/compounds/find/CXN-123456"
    compounds[*].formattedSourceError string Error detail if compound cannot be converted to specified format.
    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

    Upload data to compound

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

    Purpose: adds uploaded data to a compound

    Request headers : X-API-KEY required

    URL parameters:

    Parameter name type Description
    id string the content ID, virtual ID or substance ID of the selected compound

    Request parameters:

    Parameter name type Description
    column string Column name for the uploaded value
    value string or number Uploaded value

    Response: Http status 200 in case of success, error code otherwise

    Upload additional field value to compound

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

    Purpose: uploads value of given additional field to a compound

    Request headers : X-API-KEY required

    URL parameters:

    Parameter name type Description
    id string the content ID, virtual ID or substance ID of the selected compound

    Request parameters:

    Parameter name type Description
    name string Name of the additional field (not label)
    value string or number New value of the field

    Response: Http status 200 in case of success, error code otherwise

    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
    visibility string the visibility type of the attachement. One of internal or public. Default: public.

    Response body:

    {
  "contentUrl": string
}

    Attach internal data to compound

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

    Same as Attach internal data to compound used with the visibility parameter set to internal.

    Deprecated in favor of Attach internal data to compound.

    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
    format string (optional) output compound format supported by JChem Microservices IO. See file formats here.
    registration_ids string a comma separated list of latest known ID of the compounds
    project_label string a comma separated list of project labels
    project_key string a comma separated list of project keys
    project_id string a comma separated list of Design Hub's internal project IDs
    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
    author_username string comma separated list of unique IDs (usernames) of compound authors
    assignee string comma separated list of display names for compound assignees
    assignee_username string comma separated list of unique IDs (usernames) 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,
      "content_id": string,
      "private": boolean,
      "project_label": string,
      "project_key": string,
      "project_id": number,
      "designset_content_id": string;
      "designset_title": string;
      "hypothesis_content_id": string;
      "hypothesis_title": string;
      "author": string,
      "author_username": string,
      "assignee": string,
      "assignee_username": string,
      "create_date": string,
      "modify_date": string,
      "status": string,
      "source": 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[*].content_id string Design Hub's internal ID of the compound, e.g. "9d9c663085df0d12e5e826107eefcd5dcd99d06a".
    compounds[*].private boolean Visibility of the compound.
    compounds[*].project_label string The project to which this compound belongs.
    compounds[*].project_key string The unique ID of the project to which the compound belongs.
    compounds[*].project_id number Design Hub's internal ID of the project to which this 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 display name of the compound's author as known to other users.
    compounds[*].author_username string The unique ID (username) of the compound's author.
    compounds[*].assignee string The display name of the user to which the compound is assigned as known to other users.
    compounds[*].assignee_username string The unique ID (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[*].status string Status of the compound
    compounds[*].source string formatted source of the compound (formatted by provided format, MRV if format not provided).
    compounds[*].<calculated data fields> string|number|boolean Additional fields containing calculated date for the compound.
    compounds[*].formattedSourceError string Error detail if compound cannot be converted to specified format.
    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.

    Upload tags to compound, designset or hypothesis

    HTTP Request: POST /api/tags/:id

    Purpose: uploads tags to a compound, designset or hypothesis

    Request headers : X-API-KEY required

    URL parameters:

    Parameter name type Description
    id string the content ID, virtual ID or substance ID of a compound or content ID of a designset or content ID of a hypothesis

    Request parameters:

    Parameter name type Description
    command string Either Add or ReplaceAll. Add adds the list of tags to the existing tags, ReplaceAll removes all existing tags and replace them with the provided array
    tags array of strings Tags to be added (ReplaceAll with empty array removes the existing tags)

    Response: Http status 200 in case of success, error code otherwise

    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 as a string:

    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"
}

    Import raw data

    HTTP Request: POST /api/import/rawdata

    Purpose: Provides a way for uploading raw data, similarly to the import plugins.

    Request content-type: application/json

    Request body: An array of objects, with the following properties:

    Property name Type Required Description
    external_id string Yes A unique record identifier
    substance_id string No Physical substance identifier of the compound
    virtual_id string No A non-Design Hub generated virtual identifier of the compound
    source string Yes Chemical structure of the compound
    owner_username string Yes username or identifier as obtained from the identity provider
    generate_virtual_id boolean No Deprecated
    project_id number One of project_id and project_key required Design Hub internal project identifier
    project_key string One of project_id and project_key required Design Hub external project identifier (acquired when fetching projects from company plugin)
    hypothesis_title string No title of a hypothesis in which compounds is stored
    designset_title string No title of a design set in which compound is stored
    status_id number One of status_id and status_label required Design Hub internal status identifier
    status_label string One of status_id and status_label required Status label
    source_system string No Label of the compound source. This attribute will be published for storage plugins.
    visibility number No private/shared visibility flag. for private use 0, for public use 1. default is 1
    raw_data Object No Compound properties. Object keys matching the name of compoundFields will be used to update the value of custom fields, while the rest are stored as Imported data.
    add_tags string[] No Tags to be added to the compound records.
    allow_user_provisioning boolean No When set to false, then unknown owner_username records will fail. When set to true, then unknown owner_username records will succeed and create new deactivated user accounts.

    Response content-type : application/json

    Response body : a JSON object including the following properties:

    Property name Value Description
    import_session_id number The import session id.

    Example (import.json is the data file):

    curl -X POST "http://localhost:8888/api/import/rawdata" -H "X-API-KEY: <my key>" -H "Content-Type: application/json" -d @import.json

    If the request succeeds, the server returns a response containing the started import session id:

    E.g:

    {"import_session_id":6}

    Get status of the raw data import

    HTTP Request: GET /api/import/rawdata/status/:id

    Purpose: Provides a way to check the status of an import.

    Request content-type: application/json

    Request parameters:

    Parameter Value Description
    id string import session id

    Response content-type : application/json

    Response body : a JSON object including the following properties:

    Property name Value Description
    error_count number The number of records that threw exceptions and couldn't be imported.
    remaining_count number The number of records that are still not imported.
    total_count number The total number of records.
    last_error object { description, timestamp} The description and timestamp (both as strings) of the last encountered error. Returned only if an error occurs.

    Example - querying the status of an import task:

    curl "http://localhost:8888/api/import/rawdata/status/6" -H "X-API-KEY: <my key>"

    Response example:

    {
  "remaining_count":0,
  "error_count":3,
  "total_count":3,
  "last_error":{
    "timestamp":"2023-10-17T09:30:44.731Z",
    "description":"rest-api: Unknown user stageworkern..." 
  }
}

    Get the errors of the raw data import

    HTTP Request: GET /api/import/rawdata/errors/:id

    Purpose: Provides a way to check the errors that occured during an import.

    Request content-type: application/json

    Request parameters:

    Parameter Value Description
    id string import session id

    Query parameters:

    Parameter Value Description
    offset number The number of errors to skip in the beginning of the list, default is 0.
    limit number The maximum size of the list, default and maximum is 100.

    Response content-type : application/json

    Response body : a JSON object containing a list of objects with he following properties:

    Property name Value Description
    external_id string The external id coming from the record in the imported file.
    error_cause number The description of the error.
    content_id number The content id from Design Hub, if it exists.

    curl example - asking for the errors that occured during an import with import session id 6:

    curl "http://localhost:8888/api/import/rawdata/errors/6" -H "X-API-KEY: <my key>"

    Response example:

    [{
"external_id":"VVVVV11113",
"content_id":null,
"error_cause":"Unknown user stageworker\nError: Unknown user stageworker..." 
}]