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.

Encord SDK

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

Generate authentication a public / private key pair in our platform.
Set authorization headers when making API calls.

1. Set up authentication keys

You can authenticate with Encord on a user basis by registering a public key in the Encord web-app.

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.