NAV Navbar
shell ruby python javascript

Introduction

Welcome to the OCLAVI API Documentation! You can use our API to access OCLAVI API endpoints, with which you can create projects and consume the annotated data.

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

To authorize, use this code:

require 'net/http'

url = URI.parse('https://app.oclavi.com/oapi/apiexport?email=EMAIL_ID&projectId=PROJECT_ID&token=TOKEN_KEY&activeStorage=STORAGE_NAME')
req = Net::HTTP::Get.new(url.to_s)
res = Net::HTTP.start(url.host, url.port) {|http|
  http.request(req)
}
puts res.body
import requests

api = requests.get('https://app.oclavi.com/oapi/apiexport?email=EMAIL_ID&projectId=PROJECT_ID&token=TOKEN_KEY&activeStorage=STORAGE_NAME')
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "API_KEY: 065355ef-1682-41ec-8ebb-12fd432ef39d" \
  -H "USER_ID: 5883d387971bb840b7399130"
# With Jquery
$.ajax({
  type: 'GET',
  url: 'end_point_url',
  headers: {
    "API_KEY": "065355ef-1682-41ec-8ebb-12fd432ef39d",
    "USER_ID": "5883d387971bb840b7399130"
  }
});

# With NodeJS request
var request = require('request');

request.get({
    url: 'end_point_url',
    json: true,
    headers: {'User-Agent': 'request', "API_KEY": "065355ef-1682-41ec-8ebb-12fd432ef39d", "USER_ID": "5883d387971bb840b7399130"}
  }, (err, res, data) => {
    if (err) {
      console.log('Error:', err);
    } else if (res.statusCode !== 200) {
      console.log('Status:', res.statusCode);
    } else {
      // data is already parsed as JSON:
      console.log(data.html_url);
    }
});

Make sure to replace 065355ef-1682-41ec-8ebb-12fd432ef39d with your API key and 5883d387971bb840b7399130 with your USER ID.

OCLAVI uses API token keys to allow access to the API. You can get a token key with-in the project folder at OCLAVI.

OCLAVI expects a API Key and USER ID to be included in all API requests to the server in a header that looks like the following:

API Key: 468404dd-c286-4b72-92e6-2e521932ad6b

User ID: 5883d387971bb840b7399130

EMAIL_ID: demo@oclavi.com

Project ID: c8444c62-363d-4484-b98e-dadeadec53da

Token: 065355ef-1682-41ec-8ebb-12fd432ef39d

Active Storage: GOOGLE_DRIVE

Projects

Get All Projects

require 'net/http'

url = URI.parse('https://app.oclavi.com/oapi/v1/projects/?API_KEY=468404dd-c286-4b72-92e6-2e521932ad6b&USER_ID=5883d387971bb840b7399130')
req = Net::HTTP::Get.new(url.to_s)
res = Net::HTTP.start(url.host, url.port) {|http|
  http.request(req)
import requests

api = requests.get('https://app.oclavi.com/oapi/v1/projects/?API_KEY=468404dd-c286-4b72-92e6-2e521932ad6b&USER_ID=5883d387971bb840b7399130')
curl "https://app.oclavi.com/oapi/v1/projects"
  -H "API_KEY: 065355ef-1682-41ec-8ebb-12fd432ef39d" \
  -H "USER_ID: 5883d387971bb840b7399130"
# With Jquery
$.ajax({
  type: 'GET',
  url: 'https://app.oclavi.com/oapi/v1/projects',
  headers: {
    "API_KEY": "065355ef-1682-41ec-8ebb-12fd432ef39d",
    "USER_ID": "5883d387971bb840b7399130"
  }
});

# With NodeJS request
var request = require('request');

request.get({
    url: 'https://app.oclavi.com/oapi/v1/projects',
    json: true,
    headers: {'User-Agent': 'request', "API_KEY": "065355ef-1682-41ec-8ebb-12fd432ef39d", "USER_ID": "5883d387971bb840b7399130"}
  }, (err, res, data) => {
    if (err) {
      console.log('Error:', err);
    } else if (res.statusCode !== 200) {
      console.log('Status:', res.statusCode);
    } else {
      // data is already parsed as JSON:
      console.log(data.html_url);
    }
});

The above command returns JSON structured like this:

[
  {
    "PROJECT_ID": "DEFAULT",
  },
  {
    "PROJECT_ID": "50857a71-b531-11e8-b4a8-d14c3f3d99f9"
  },
]

This endpoint retrieves all OCLAVI projects ID's for a respective user.

HTTP Request

GET https://app.oclavi.com/oapi/v1/projects

HEADER Parameters

Parameter Default Description
Content-Type application/json the content type is json
API_KEY You'll get the API Key from your profile settings->Developer tab
USER_ID You'll get the USER ID from your profile settings->Developer tab

OUTPUT Fields

Parameter Example Value DataType Description
PROJECT_ID 50857a71-b531-11e8-b4a8-d14c3f3d99f9 string Unique project id

Get a Specific Project Details

require 'net/http'

url = URI.parse('https://app.oclavi.com/oapi/v1/project/?API_KEY=468404dd-c286-4b72-92e6-2e521932ad6b&USER_ID=5883d387971bb840b7399130&PROJECT_ID=50857a71-b531-11e8-b4a8-d14c3f3d99f9')
req = Net::HTTP::Get.new(url.to_s)
res = Net::HTTP.start(url.host, url.port) {|http|
  http.request(req)
import requests

api = requests.get('https://app.oclavi.com/oapi/v1/projects/?API_KEY=468404dd-c286-4b72-92e6-2e521932ad6b&USER_ID=5883d387971bb840b7399130&PROJECT_ID=50857a71-b531-11e8-b4a8-d14c3f3d99f9')
curl "https://app.oclavi.com/oapi/v1/project"
  -H "API_KEY: 065355ef-1682-41ec-8ebb-12fd432ef39d" \
  -H "USER_ID: 5883d387971bb840b7399130" \
  -H "PROJECT_ID : 50857a71-b531-11e8-b4a8-d14c3f3d99f9"
# With Jquery
$.ajax({
  type: 'GET',
  url: 'https://app.oclavi.com/oapi/v1/project',
  headers: {
    "API_KEY": "065355ef-1682-41ec-8ebb-12fd432ef39d",
    "USER_ID": "5883d387971bb840b7399130",
    "PROJECT_ID" : "50857a71-b531-11e8-b4a8-d14c3f3d99f9"
  }
});

# With NodeJS request
var request = require('request');

request.get({
    url: 'https://app.oclavi.com/oapi/v1/project',
    json: true,
    headers: {'User-Agent': 'request', "API_KEY": "065355ef-1682-41ec-8ebb-12fd432ef39d", "USER_ID": "5883d387971bb840b7399130", "PROJECT_ID" : "50857a71-b531-11e8-b4a8-d14c3f3d99f9"}
  }, (err, res, data) => {
    if (err) {
      console.log('Error:', err);
    } else if (res.statusCode !== 200) {
      console.log('Status:', res.statusCode);
    } else {
      // data is already parsed as JSON:
      console.log(data.html_url);
    }
});

The above command returns JSON structured like this:

[
  {
    "PROJECT_ID": "50857a71-b531-11e8-b4a8-d14c3f3d99f9",
    "NAME": "CARS",
    "DATE_CREATED": 1536608177239,
    "ACTIVE_STORAGE": "GOOGLE_DRIVE",
    "EXPORT_TOKEN": "s222670-b530-11e8-b4a8-d14c3f3d99f9",
    "STATUS": "ACTIVE",
    "CONNECTED_ACCOUNT": "email_address",
    "FOLDER_NAME_ON_DRIVE": "cars",
    "LAST_SYNCHRONIZATION_DATE": 1536608459218,
    "TOTAL_IMAGES": 100,
    "TOTAL_CLASSIFIED_IMAGES": 40
  },
]

This endpoint retrieves a specific OCLAVI project.

HTTP Request

GET https://app.oclavi.com/oapi/v1/project/<PROJECT_ID>

HEADER Parameters

Parameter Example Value Description
Content-Type application/json the content type is json
API_KEY You'll get the API Key from your profile settings->Developer tab
USER_ID You'll get the USER ID from your profile settings->Developer tab

OUTPUT Fields

Parameter Example Value DataType Description
PROJECT_ID 50857a71-b531-11e8-b4a8-d14c3f3d99f9 string Unique project id
NAME CARS string Name of the project
DATE_CREATED 1536608177239 epochtime Date when the project was created
ACTIVE_STORAGE GOOGLE_DRIVE string Storage provided where the data was added from
EXPORT_TOKEN s222670-b530-11e8-b4a8-d14c3f3d99f9 string Export token for exporting the annotated data
STATUS ACTIVE string Project status
CONNECTED_ACCOUNT email_address string Email ID which is used to connect the google drive
FOLDER_NAME_ON_DRIVE cars string Folder name that's been connected to the Project
LAST_SYNCHRONIZATION_DATE 1536608459218 epochtime Date when the project was last synced
TOTAL_IMAGES 100 int Total image that were uploaded for annotation
TOTAL_CLASSIFIED_IMAGES 40 int Total image that were classfied

Export

Get Annotated Data

require 'net/http'

url = URI.parse('https://app.oclavi.com/oapi/apiexport?email=EMAIL_ID&projectId=PROJECT_ID&token=TOKEN_KEY&activeStorage=STORAGE_NAME')
req = Net::HTTP::Get.new(url.to_s)
res = Net::HTTP.start(url.host, url.port) {|http|
  http.request(req)
import requests

api = requests.get('https://app.oclavi.com/oapi/apiexport?email=EMAIL_ID&projectId=PROJECT_ID&token=TOKEN_KEY&activeStorage=STORAGE_NAME')
curl "https://app.oclavi.com/oapi/apiexport?email=EMAIL_ID&projectId=PROJECT_ID&token=TOKEN_KEY&activeStorage=STORAGE_NAME"
  -H "email: EMAIL_ID" \
  -H "projectId: 50857a71-b531-11e8-b4a8-d14c3f3d99f9" \
  -H "token : EXPORT_TOKEN" \
  -H "activeStorage: STORAGE_NAME"
# With Jquery
$.ajax({
  type: 'GET',
  url: 'https://app.oclavi.com/oapi/apiexport?email=EMAIL_ID&projectId=PROJECT_ID&token=TOKEN_KEY&activeStorage=STORAGE_NAME',
  headers: {
    "email": "EMAIL_ID",
    "projectId" : "50857a71-b531-11e8-b4a8-d14c3f3d99f9",
    "token": "EXPORT_TOKEN",
    "activeStorage": "STORAGE_NAME"
  }
});

# With NodeJS request
var request = require('request');

request.get({
    url: 'https://app.oclavi.com/oapi/apiexport?email=EMAIL_ID&projectId=PROJECT_ID&token=TOKEN_KEY&activeStorage=STORAGE_NAME',
    json: true,
    headers: {'User-Agent': 'request'}
  }, (err, res, data) => {
    if (err) {
      console.log('Error:', err);
    } else if (res.statusCode !== 200) {
      console.log('Status:', res.statusCode);
    } else {
      // data is already parsed as JSON:
      console.log(data.html_url);
    }
});

The above command returns JSON structured like this:

[
  {
    LABEL_DETAILS: [
      {
        LABEL_NAME: "Cat",
        EDGES_RECT: [
          {
            START_X: 2664.488299531981,
            START_Y: 1250.2010582010582,
            HEIGHT: 1699.4920634920636,
            WIDTH: 993.3806552262091,
            START_X_PERCENT: 44.77379095163806,
            START_Y_PERCENT: 33.86243386243386,
            HEIGHT_PERCENT: 46.03174603174603,
            WIDTH_PERCENT: 16.69266770670827
          },
          {
            START_X: 4163.843213728549,
            START_Y: 1458.567901234568,
            HEIGHT: 1380.430335097002,
            WIDTH: 640.5912636505459,
            START_X_PERCENT: 69.96879875195008,
            START_Y_PERCENT: 39.50617283950617,
            HEIGHT_PERCENT: 37.38977072310406,
            WIDTH_PERCENT: 10.764430577223088
          }
        ]
      },
      {
        LABEL_NAME: "Dog",
        EDGES_RECT: [
          {
            START_X: 4836.928237129485,
            START_Y: 2591.562610229277,
            HEIGHT: 221.38977072310405,
            WIDTH: 343.50546021840876,
            START_X_PERCENT: 81.2792511700468,
            START_Y_PERCENT: 70.19400352733686,
            HEIGHT_PERCENT: 5.996472663139329,
            WIDTH_PERCENT: 5.77223088923557
          }
        ]
      }
    ],
      IMAGE_WIDTH: 5951,
      IMAGE_HEIGHT: 3692,
      IMAGE_NAME: "big-ben-bus-england-45923.jpg",
      OBJECT_STORAGE: "GOOGLE_DRIVE",
      CLASSIFIED_BY: ""
  }
]

This endpoint exports a specific OCLAVI Project annotated data.

HTTP Request

GET https://app.oclavi.com/oapi/apiexport?email=EMAIL_ID&projectId=PROJECT_ID&token=TOKEN_KEY&activeStorage=STORAGE_NAME

HEADER Parameters

Parameter Example Value Description
Content-Type application/json the content type is json
email demooclavicom Your registered email id associated to the project without any special characters
projectId 50857a71-b531-11e8-b4a8-d14c3f3d99f9 Unique project id
token s222670-b530-11e8-b4a8-d14c3f3d99f9 Project specific export token
activeStorage GOOGLE_DRIVE Storage provider where the data was added from

OUTPUT Fields

Parameter Example Value DataType Description
LABEL_NAME Person string Label name
EDGE_RECT [] array All the annotations of a boundbox is saved as a array with title "EDGE_RECT". Each Boundbox is stored as an object within the "EDGE_RECT" array of a label
START_X 4836.928237129485 number Represent the starting point of the box and is with-in the shape array of a particular label
START_Y 2591.562610229277 number Represent the starting point of the box and is with-in the shape array of a particular label
HEIGHT 221.38977072310405 number Represent the height of the bound-box and is with-in the shape array of a label
WIDTH 343.50546021840876 number Represent the width of the bound-box and is with-in the shape array of a label
START_X_PERCENT 81.2792511700468 percentage(%) Represent the starting point of the box in a percentage and is with-in the shape array of a particular label
START_Y_PERCENT 70.19400352733686 percentage(%) Represent the starting point of the box in a percentage and is with-in the shape array of a particular label
HEIGHT_PERCENT 5.996472663139329 percentage(%) Represent the height of the bound-box in percentage and is with-in the shape array of a label
WIDTH_PERCENT 5.77223088923557 percentage(%) Represent the width of the bound-box in percentage and is with-in the shape array of a label
IMAGE_WIDTH 5951 number The actual image width
IMAGE_HEIGHT 3692 number The actual image height
IMAGE_NAME big-ben-bus-england-45923.jpg string Represent image name that was stored in GDrive or S3

Errors

The OCLAVI API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The OCLAVI requested is hidden for administrators only.
404 Not Found -- The specified OCLAVI Project could not be found.
405 Method Not Allowed -- You tried to access a OCLAVI Project with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The OCLAVI project requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many OCLAVI Projects! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.