Getting started

The Encord API is a REST API that allows you to programmatically query resources such as projects, datasets, labels etc. The API also allows you to use our powerful automation features such as automated labeling, training and inference.

We recommend using our Python Encord SDK to call our API as it does much of the heavy lifting. This documentation explains how to construct the correct requests if you are not in a position to use our SDK.

API endpoint

The Encord API has the following endpoint

https://api.encord.com/public

URIs referenced in the documentation are relative to this endpoint.

API authentication

All API requests are authenticated. To authenticate requests with Encord, you simply need to:

1. Set up authentication keys
2. Set authorization headers

1. Set up authentication keys

You can authenticate with Encord on a user basis by registering a public key, or on a specific project or dataset basis by using an Encord-generated API key tied to that resource.

• Register a public key: registering a public key gives you full access, allowing you to access all your projects and datasets, as well as create new projects and datasets
• Create an API key: creating an API key gives you access restricted to a particular project or dataset

Public keys are used to authenticate the user for activities that require user-level access, for example creating projects and datasets. API keys are more restrictive and are tied to a particular project or dataset. API keys are used to authenticate calls that only require resource-level access, for example downloading label rows from a particular project.

Register a public key

Public keys are tied to the user so need to be added to your profile. To register a public key, please follow the instructions in Public keys.

Create an API key

API keys are tied to specific projects or datasets. You can generate multiple keys for each project or dataset. To create an API key:

1. Log in to your account on app.encord.com
2. Navigate to the Projects or Datasets tab in the Navigation bar
3. Select a project or dataset
4. Navigate to the 'Settings' tab and select the 'API access' pane on the left
5. Click on the + New API key button, select relevant scopes and click the Create button
6. Copy your API key and make a note of project or dataset ID. The API key is only displayed once.

2. Set authorization headers

Once you have registered a public key or created an API key, you can authenticate your requests by using your keys in the authorization header of your API calls.

Public key authentication

For user-level operations, set the authorization header to your registered public key followed by a hash of your request data signed by the corresponding private key.

Here is an example of how you can create the correct authorization header using Node

const crypto = require('crypto');
const sshpk = require('sshpk');

const generateAuthHeader = (data, privateKey) => {
    const pkParsed = sshpk.parsePrivateKey(privateKey, 'openssh');
    const hashedData = crypto.createHash('sha256').update(data).digest();
    const s = pkParsed.createSign('sha512');
    s.update(hashedData);
    const signature = s.sign();
    const publicKey = pkParsed.toPublic();
    const pkData = publicKey.parts[0].data;
    const pkDataString = pkData.toString('hex');
    return `${pkDataString}:${signature.parts[0].data.toString('hex')}`;
};

// Some request data created
// ...

var request = {
   method: 'post',
   url: 'https://api.encord.com/public',
   headers: {
      'Content-Type': 'application/json',
      'Authorization': generateAuthHeader('<request_data>', '<private_key>'),
      'Accept': 'application/json'
   },
   data : '<request_data>'
};

API key authentication

For resource-level operations, set the authorization header of your request to the API key of the resource in question.

Here is an example in Javascript

var request = {
   method: 'post',
   url: 'https://api.encord.com/public',
   headers: {
      'Content-Type': 'application/json',
      'Authorization': '<API_key>',
      'Accept': 'application/json'
   },
   data : '<request_data>'
};

Examples

Fetch project information

Create a project API key and note both the key and project ID. Here is an example in Node on how to request project information

var axios = require('axios');
var data = JSON.stringify(
  {
    "query_type": "project",
    "query_method":"GET",
    "values": {
      "uid": null,
      "payload": null
    }
  });

var config = {
  method: 'post',
  url: 'https://api.encord.com/public',
  headers: {
    'Content-Type': 'application/json',
    'ResourceID': '<project_id>',
    'Authorization': '<project_api_key>', 
    'Accept': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

The response contains the title, description, editor ontology, datasets, and associated label rows, in Python JSON.

Fetch dataset information

Create a dataset API key and note both the key and dataset ID. Here is an example in Node on how to request dataset information

var axios = require('axios');
var data = JSON.stringify(
  {
    "query_type": "dataset",
    "query_method":"GET",
    "values": {
      "uid": null,
      "payload": null
    }
  });

var config = {
  method: 'post',
  url: 'https://api.encord.com/public',
  headers: {
    'Content-Type': 'application/json',
    'ResourceID': '<dataset_id>',
    'Authorization': '<dataset_api_key>',   
    'Accept': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

The response contains the title, description, dataset type (e.g. Encord storage vs. AWS S3), and associated data rows, in Python JSON.