Working with projects (API)

Suggest Edits

ℹ️

Note

Projects can't be deleted via the SDK or the API, as this is a significant and irreversible operation. Please use our web-app to delete projects.

Creating a project

First you need to create a private key for Encord.

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')}`;
};

var axios = require('axios');
var data = JSON.stringify(
  {
    "query_type": "project",
    "query_method":"POST",
    "values": {
      "uid": null,
      "payload": {
          "title": '<Project title>',
          "description": '<Project description>',
          "dataset_hashes": '<List of dataset hashes to add>',
          "ontology_hash": '<Ontology hash>', // Optional parameter. Specify an existing ontology to associate the project with.
      }
    }
  });

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

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


curl --location --request POST 'https://api.encord.com/public/user' \
--header 'Content-Type: application/json' \
--header 'Authorization: <auth_header>' \
--header 'Accept: application/json' \
--data-raw '{
    "query_type": "project",
    "query_method":"POST",
    "values": {
      "uid": null,
      "payload": {
          "title": '<Project title>',
          "description": '<Project description>',
          "dataset_hashes": '<List of dataset hashes to add>'
      }
    }
  }'

The above API call returns the unique identifier of the project known as project_hash, and makes the caller the Admin of the project.

Creating a project API key

You can create a project API key via the API to interact with the project.
You'll need to provide the project_hash to uniquely identify your project.

ℹ️

Note

This capability is available to only the Admin of the project.

The APIKeyScopes provides the following values to restrict access to specific functionality via the API.

  1. LABEL_READ : For access to getting label rows
  2. LABEL_WRITE : For access to creating/saving label rows
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')}`;
};

var axios = require('axios');
var data = JSON.stringify(
  {
    "query_type": "projectapikey",
    "query_method":"POST",
    "values": {
      "uid": '<project_id>',
      "payload": {
          "title": '<API key title>',
          "scopes": '<["label.read", "label.write"]>'
      }
    }
  });

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

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


curl --location --request POST 'https://api.encord.com/public/user' \
--header 'Content-Type: application/json' \
--header 'Authorization: <auth_header>' \
--header 'Accept: application/json' \
--data-raw '{
    "query_type": "projectapikey",
    "query_method":"POST",
    "values": {
      "uid": '<project_id>',
      "payload": {
          "title": '<API key title>',
          "scopes": '<["label.read", "label.write"]>'
      }
    }
  }'

Fetching a project API key

Via the API you can get all API keys for an existing project.

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

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')}`;
};

var data = JSON.stringify(
    {
        "query_type": "projectapikey",
        "query_method":"GET",
        "values": {
            "uid": '<project_id>',
            "payload": null,
        }
    });

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

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

curl --location --request POST 'https://api.encord.com/public/user' \
--header 'Content-Type: application/json' \
--header 'Authorization: <auth_header>' \
--header 'Accept: application/json' \
--data-raw '{
        "query_type": "projectapikey",
        "query_method":"GET",
        "values": {
            "uid": '<project_id>',
            "payload": null,
        }
    }'

Adding datasets to a project

Via the API you can add existing datasets to a project.

ℹ️

Note

You need to be the Admin of the datasets that you want to add, as well as the project itself.

The unique identifier dataset_hash for every dataset is needed for this functionality.

var axios = require('axios');
var data = JSON.stringify(
  {
    "query_type": "projectdataset",
    "query_method":"POST",
    "values": {
      "uid": null,
      "payload": {
          "dataset_hashes": '["aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee1", "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee2"]'
      }
    }
  });

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);
});


curl --location --request POST 'https://api.encord.com/public' \
--header 'Content-Type: application/json' \
--header 'ResourceID: <project_id>' \
--header 'Authorization: <project_api_key>' \
--header 'Accept: application/json' \
--data-raw '{
    "query_type": "projectdataset",
    "query_method":"POST",
    "values": {
      "uid": null,
      "payload": {
          "dataset_hashes": '["aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee1", "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee2"]'
      }
    }
  }'

Removing datasets from a project

You can remove existing datasets to a project via the API.

The unique identifier dataset_hash is required for every dataset to be removed

ℹ️

Note

Only the Admin of a project is eligible to execute this functionality.

var axios = require('axios');
var data = JSON.stringify(
  {
    "query_type": "projectdataset",
    "query_method":"DELETE",
    "values": {
      "uid": '<List of dataset hashes to delete>',
    }
  });

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);
});


curl --location --request POST 'https://api.encord.com/public' \
--header 'Content-Type: application/json' \
--header 'ResourceID: <project_id>' \
--header 'Authorization: <project_api_key>' \
--header 'Accept: application/json' \
--data-raw '{
    "query_type": "projectdataset",
    "query_method":"DELETE",
    "values": {
      "uid": '<List of dataset hashes to delete>',
    }
  }'

Adding users to a project

Add users to an existing project via the API.

The email_id of the users need to be provided as an input.

Project user roles are
Admin = 0,
Annotator = 1,
Reviewer = 2,
Annotator & Reviewer = 3,
Team manager = 4

var axios = require('axios');
var data = JSON.stringify(
  {
    "query_type": "projectusers",
    "query_method":"POST",
    "values": {
      "uid": '<project_id>',
      "payload": {
          "user_emails": '<List of user emails>',
          "user_role": '<User role of the new users>'
      }
    }
  });

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);
});


curl --location --request POST 'https://api.encord.com/public' \
--header 'Content-Type: application/json' \
--header 'ResourceID: <project_id>' \
--header 'Authorization: <project_api_key>' \
--header 'Accept: application/json' \
--data-raw '{
    "query_type": "projectusers",
    "query_method":"POST",
    "values": {
      "uid": null,
      "payload": {
          "user_emails": '<List of user emails>',
          "user_role": '<User role of the new users>'
      }
    }
  }'

Fetching project information

Fetch information associated with a given project.


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);
});



curl --location --request POST 'https://api.encord.com/public' \
--header 'Content-Type: application/json' \
--header 'ResourceID: <project_id>' \
--header 'Authorization: <project_api_key>' \
--header 'Accept: application/json' \
--data-raw '{
    "query_type": "project",
    "query_method": "GET",
    "values": {
        "uid": null,
        "payload": null
    }
}'

Fetching project ontology

You can fetch the ontology of an existing project using the above API call. The editor ontology can be found in the API response under the key editor_ontology.

Updated 5 months ago