REST API Data Access and Queries

By setting up your API key on the Nuklai marketplace, you will be able to query your data through our REST API. You can also integrate the Nuklai REST API into the applications that you are building as a developer or a data professional.

In this user guide, we will show you how to set up your API and query your first dataset.

To use Nuklai’s REST API, you should have:

  • Knowledge of programming languages and the query language SQL

  • A code editor or Jupyter Notebook set-up on your device.

When you arrive on the Nuklai marketplace, in the sidebar there will be a menu item called Settings. When you click on this menu item, a sub-menu will unfold, and you will see a sub-menu called API key. When you click on this sub-menu, a screen will appear where you can generate your API key.

Setting up your API key

The API key is set up with the rights to query all datasets that the user has uploaded to the Nuklai marketplace and the user can query all datasets that have an active subscription.

You will also be asked to select how many days the API key stays valid in the Duration Days field. This is done for security purposes – we suggest renewing your API keys every 90 days, but you can select a time between 1 day and 365 days.

Give your API key a name to distinguish them from other active API keys. You will be able to generate up to 5 different keys.

Now click the Generate button. In the API Key field, you will see a long string. This string is your API key. You will need to store this key in a secure place – if you lose this key, you will need to generate a new one. You can click the copy button (two squares) to copy the API key.

Generate your API key

Send a query via the API

You can now open up your preferred code editor, if you have not set up any code editor and if you are familiar with Python, you can also choose to set up a Jupyter Notebook. We recommend you follow the official guide for installing JupyterLab on your device.

To set up your API in your code editor you should set up three variables. The API url, the API key, and the DatasetID.

HTTP Method: POST

API Url: https://api.nukl.ai/api/public/v1/datasets/:datasetId/queries

Response format: JSON

The Dataset-ID you can get from the url of the dataset you want to query. It is a 36-character hexadecimal string and it is split into 5 parts.

For example: https://app.nukl.ai/dataset/061e6d78-205e-43e0-b9c1-499cea3b759c

Where 061e6d78-205e-43e0-b9c1-499cea3b759c is the Dataset-ID.

// Setting up the variables

const ApiUrl = "https://api.nukl.ai/api/public/v1/datasets/:datasetId/queries";
const ApiKey = "[API_KEY]";
const DatasetId = "[DATASET_ID]";

To make a proper query you should also set the headers. The first one is for the content type (JSON) and the second is for the authentication.

// Setting up the header

const headers = {
  "Content-Type": "application/json",
  'authentication': ApiKey
}

You are now able to add an SQL query to the body of the dataset. In this example, we will query all columns and the first 5 records of the dataset by writing the following SQL query:

// Selecting 5 records from the dataset

select * from @dataset limit 5

This query is added to the body in the following way:

// @dataset represents your dataset rows as a table

const body = {
  sqlQuery: "select * from @dataset limit 5",
}

Your code should now look like this to make the query:

// variables
const ApiUrl = "https://api.nukl.ai/api/public/v1/datasets/:datasetId/queries";
const ApiKey = "[API_KEY]";
const DatasetId = "[DATASET_ID]";

// header
const headers = {
  "Content-Type": "application/json",
  'authentication': ApiKey
}

// body with sql query
const body = {
  sqlQuery: "select * from @dataset limit 5",
}

// make a request
fetch(ApiUrl.replace(':datasetId', DatasetId), {
  method: "POST",
  headers: headers,
  body: JSON.stringify(body), // convert to json object
})
  .then((response) => response.json())
  .then((data) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Once you run the code, you will get a response. This response is a job-ID.

For example: 061e6d78-205e-43e0-b9c1-499cea3b759c

This job-ID can have three responses:

  • Pending

    • Your query is still running, wait until the job is finished.

  • Failed

    • There might be a problem with your SQL query. We suggest first writing the correct SQL query within the UI.

  • Completed

    • Your query has been completed, you will now be able to see the result as an object.

Retrieving your data

HTTP Method: GET

API Url: https://api.nukl.ai/api/public/v1/datasets/:datasetId/queries

Response format: JSON

Your code should now look like something like this to fetch the response of the query:

// variables
const ApiUrl = "https://api.nukl.ai/api/public/v1/datasets/:datasetId/queries/:jobId";
const ApiKey = "[API_KEY]";
const DatasetId = "[DATASET_ID]";
const JobId = "[JOB_ID]"; // retrieved from /queries request

// header
const headers = {
  "Content-Type": "application/json",
  'authentication': ApiKey
}

// make a request
fetch(ApiUrl.replace(':datasetId', DatasetId).replace(':jobId', JobId), {
  method: "GET",
  headers: headers
})
  .then((response) => response.json())
  .then((data) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Congratulations you have now set up your API key and queried your first dataset through the REST API!

Last updated