Making a Request

In order to make a successful request, you should be aware of the following variables:

• ARDOQ_API_TOKEN. The API token that you will use for authorization. You can read more about tokens here.

  Info

  All requests to the Ardoq API must include an Authorization header with the bearer set to this value.

  Authorization: Bearer ${ARDOQ_API_TOKEN}
  

  If you use a token that has expired you will get a 401 Authentication error.

• ARDOQ_API_HOST. The host address that you access the Ardoq app on.

  Info

  If you are unsure about what value to use for ARDOQ_API_HOST open the Ardoq app and log in to the organization that you want to interact with. Once you have logged in note the url in your browsers address bar. The value of ARDOQ_API_HOST should have the form https://<something>.ardoq.com. If <something> is any other value than app, then you are using a custom domain.

• ARDOQ_ORG_LABEL. The label of your organization.

  Info

  If you are NOT using a custom domain, then this value MUST be included in your requests under the X-org header. If you are using a custom domain, then the X-org header is optional. As an example, if your org label is myorg then the header would be "X-org: myorg". The Knowledge Base article that covers generating an API token also shows you how to find this label.

Using Postman

You can download and import all of the Ardoq Public API endpoints into Postman, an app used to test and work with APIs.

1. Download the latest version of our Postman collection.
2. Import the collection into your Postman workspace.
3. Set the variables ARDOQ_API_TOKEN, ARDOQ_ORG_LABEL and ARDOQ_API_HOST.
4. Make your first request to the Ardoq API!

Using a Script

Create a file called me that contains any of the the following code snippets:

CurlPythonNode

#!/bin/sh
curl "${ARDOQ_API_HOST="https://app.ardoq.com"}/api/v2/me" \
  --header "Authorization: Bearer ${ARDOQ_API_TOKEN}" \
  --header "X-org: ${ARDOQ_ORG_LABEL}" \
  --no-progress-meter \
  --fail-with-body # this will ensure that any errors are displayed

#!/usr/bin/env python3
import json
import os
import urllib.request

url = os.getenv("ARDOQ_API_HOST", "https://app.ardoq.com") + "/api/v2/me"

req = urllib.request.Request(url)
req.add_header("X-org", os.getenv("ARDOQ_ORG_LABEL"))
req.add_header("Authorization", "Bearer " + os.getenv("ARDOQ_API_TOKEN"))
with urllib.request.urlopen(req) as resp:
    data = json.loads(resp.read().decode("utf-8"))

print(data)

#!/usr/bin/env node
const https = require('https')

const url = (process.env.ARDOQ_API_HOST || "https://app.ardoq.com") + "/api/v2/me"
const headers = { "Authorization": "Bearer " + process.env.ARDOQ_API_TOKEN, "User-Agent": "Node" }
if (process.env.ARDOQ_ORG_LABEL) {
    headers["X-org"] = process.env.ARDOQ_ORG_LABEL
}
https.get(url, { headers }, (res) => {
    res.on('data', (d) => {
        process.stdout.write(d);
    });
}).on('error', (e) => {
    console.error(e);
});

Make sure that the script is executable, for example by using the command chmod +x me.

If you are using a custom domain then you MUST set the ARDOQ_API_HOST environment variable to point to your host.

Assuming that your org label is "myorg" and your token is "123", you can now run the following command:

ARDOQ_API_HOST="https://myorg.ardoq.com" ARDOQ_ORG_LABEL="myorg" ARDOQ_API_TOKEN="123" ./me

If the request succeeds, then the values for ARDOQ_API_TOKEN, ARDOQ_ORG_LABEL and ARDOQ_API_HOST are correct.

{
  "user": {
    "email": "me@myorg.com"
  },
  "org": {
    "name": "My Org",
    "label": "myorg"
  }
}

The following shows a general utility function for making requests against the the Ardoq API. It is assumed that you have set the env variables ARDOQ_API_TOKEN, ARDOQ_ORG_LABEL and potentially ARDOQ_API_HOST.

PythonNode

#!/usr/bin/env python3
import json
import os
import urllib.request
import urllib.parse

def ardoq_request(resource, method="GET", query_params=None, data=None):
    host = os.getenv("ARDOQ_API_HOST","https://app.ardoq.com")
    api_token = os.getenv("ARDOQ_API_TOKEN")
    org_label = os.getenv("ARDOQ_ORG_LABEL")
    url = host + resource
    # support optional query parameters {"foo":"bar","baz":2}
    if query_params:
        url = url + "?" + urllib.parse.urlencode(query_params)
    req = urllib.request.Request(url, method=method)
    req.add_header("Authorization", "Bearer " + api_token)
    if org_label is not None:
        req.add_header("X-org", org_label)
    if data is not None:
        req.add_header("Content-Type", "application/json; charset=utf-8")
        data = json.dumps(data).encode("utf-8")
    with urllib.request.urlopen(req, data=data) as resp:
        return json.loads(resp.read().decode("utf-8"))

#!/usr/bin/env node
const https = require('https')

const ardoq_request = async (path, options) => {
    const url = new URL(path, process.env.ARDOQ_API_HOST || "https://app.ardoq.com")
    const query_params = options?.query_params
    Object.entries(query_params || {}).forEach(([k,v]) => {
        url.searchParams.append(k,v)
    });
    const method = options?.method || "GET"
    const headers = {
        "Authorization": "Bearer " + process.env.ARDOQ_API_TOKEN,
        "User-Agent": "Node",
    }
    if (process.env.ARDOQ_ORG_LABEL) {
        headers["X-org"] = process.env.ARDOQ_ORG_LABEL
    }
    return new Promise((resolve, reject) => {
        const options = { headers, method }
        const req = https.request(url, options, res => {
            let body = ''
            res.on('data', (chunk) => { body += chunk });
            res.on('error', reject)
            res.on('end', () => {
                resolve(JSON.parse(body))
            })
        });
        req.on('error', reject);
        req.end();
    })
}

which can be used in the following way:

PythonNode

resp = ardoq_request("/api/v2/me")
print(resp)

(async () => {
    const resp = await ardoq_request("/api/v2/me")
    console.log(resp)
})()