API Access

A web API endpoint for executing DSL queries is available. The Python script below illustrates how to make a DSL query using the web API.


The analytics API (/api/ enpoint) is limited to 30 requests per IP address per minute. The runtime API (which does not support faceting for example) has no rate limitations.

Python Example

import requests

#   The credentials to be used
login = {
    'username': 'your username',
    'password': 'your password'

#   Send credentials to login url to retrieve token. Raise
#   an error, if the return code indicates a problem.
#   Please use the URL of the system you'd like to access the API
#   in the example below.
resp = requests.post('https://<your-url.dimensions.ai>/api/auth.json', json=login)

#   Create http header using the generated token.
headers = {
    'Authorization': "JWT " + resp.json()['token']

#   Execute DSL query.
resp = requests.post(
    data='search publications return publications'.encode(),

#   Display raw result


Please note escaping rules in Python <http://python-reference.readthedocs.io/en/latest/docs/str/escapes.html>. For example, when writing a query with escaped quotes, such as:

search publications for "\"phrase 1\" AND \"phrase 2\""

in Python, it is necessary to escape the backslashes as well, so it would look like:

resp = requests.post(
    data='search publications for "\\"phrase 1\\" AND \\"phrase 2\\""',

Similar escaping rules might apply to other programming languages than Python as well.

CURL + JQ Example

This example shows a minimal way to query the API. This should be easily transferable to any other programming language or environment.

export DSL_TOKEN=$(curl https://<your-url.dimensions.ai>/api/auth.json -d '{"username": "your username", "password": "your password"}' -s|jq -r .token)

curl https://<your-url.dimensions.ai>/api/dsl.json -H "Authorization: JWT $DSL_TOKEN" -d 'search publications return publications' -s|jq


Note that jq tool is used to extract a “token” value from the JSON response in the first request. In the second request, jq is used only to pretty print the result so it’s use is optional.

PowerShell Example

This is an equivalent example of the above CURL + JQ Example, but usable in the PowerShell enivornment.

$DSL_TOKEN = (Invoke-RestMethod -Uri https://<your-url.dimensions.ai>/api/auth.json -Method Post -Body (@{'username' = 'your username'; 'password' = 'your password'} | ConvertTo-JSON)).token

Invoke-RestMethod -Uri https://<your-url.dimensions.ai>/api/dsl.json -Method Post -H @{Authorization = "JWT $DSL_TOKEN"} -Body 'search publications return publications'