NAV Navbar
shell python javascript

Introduction

Our API makes it extremely easy to integrate Raidon into your existing machine learning applications allowing you to leverage our human workers to delegate data annotation tasks. Raidon's API enables a variety of capabilities, including: creating a new data annotation task, deleting tasks or updating instructions.

We've designed our API with a developer first mindset. As a result, we employed predictable, resource-oriented URLs as well HTTP response codes to communicate errors. Due to our API being organised around REST, JSON is returned by all API responses.

Authentication

To authorize, use this code:

import requests

response = requests.get("api_endpoint_here", headers={"Authorization": "Token  49fa77ade8a3b9504a8d5138836030b44dd9ea46"})
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46"
let response = fetch("api_endpoint_here", {
  method: "GET",
  headers = {
    Authorization: "Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46"
  }
})

Make sure to replace Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46 with your API key.

Raidon uses API keys to allow access to private API endpoint. You can obtain these by logging on and then going to Settings/API. These API keys should be kept private and not shared with anybody.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Error Codes

Raidon's API complies with convention HTTP response codes, with all 200 HTTP response codes being treated as being succesful. An important note to make is that when deleting a task, a 204 HTTP response code will be sent if the deletion is succesful with no content.

In general: 2xx codes indicate success, 4xx codes indicate failure caused by either providing incorrect paramters or accessing API endpoints the user is not authorised to visit and 5xx codes indicate failure by the server.

HTTP Response Code Table

Code Description
200 - OK Your request was successful.
204 - No Content Your task was deleted and we have nothing to return.
400 - Bad Request The request cannot be fulfilled due to bad syntax.
403 - Forbidden You're unathorised to perform this task or you're trying to access a forbidden API endpoint.
404 - Not Found The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.
405 - Method Not Allow A request was made of a resource using a request method not supported by that particular resource. This may include performing GET on a POST API endpoint.
418 - I'm A Teapot I'm a teapot and therefore cannot do what you asked me to do :).
429 - Too Many Requests You've exceeding Raidon's API Limit and we've throttled you're account.
500, 502, 503, 504 - Server Errors Something went wrong on our end.

Task Object

Every task object represents one piece of work that you'd like on of our workers to complete for you. It is the most fundamental part of our API.

Attributes

An example of task object

{
    "task_id": "Iieck5Gb0mYyWxWgMhgTccQBDHGXR2Nv",
    "created_at": "2018-08-09T13:17:28.504253Z",
    "type": "boxes",
    "tag": "Tag all the houses or cars from this drone image. Also use tight bouding boxes.",
    "data": {
        "attachment": "https://dummyimageurl.com/drone_image.jpg",
        "annotation_categories": ["house", "car"]
    },
    "importance": "standard",
    "status": "completed",
    "callback_url": "https://raidon.io/api/v1/task/Iieck5Gb0mYyWxWgMhgTccQBDHGXR2Nv",
    "response": {
        "9f1vs6Ad.jpg": {
            "annotation": {
                "size": {
                    "depth": "3",
                    "width": "800",
                    "height": "1079"
                },
                "object": {
                    "name": "house",
                    "pose": "Unspecified",
                    "bndbox": {
                        "xmax": "760",
                        "xmin": "66",
                        "ymax": "1039",
                        "ymin": "948"
                    },
                    "occluded": "0",
                    "difficult": "0",
                    "truncated": "0"
                },
                "filename": "drone_image.jpg",
                "segmented": "0"
            }
        }
    },
    "completed_at": "2018-08-09T13:19:47.905099Z"
}
Parameter Type Description
task_id string A unique 32 length identifier for a task.
created_at timestamp A string of the UTC timestamp used to identify when task was created.
type string Type of task you want the worker to complete. Currently supported options include boxes, polygons, lines, landmarks and audiotranscription. All options are case-sensitive.
tag string Instructions to the worker on how to annotate the image or analyse the attachment.
data JSON object The source of the data to be annotated/anaylsed. The keys will vary dending on the task but for most data annotated tasks will include attachment.
importance string String describing the urgency of the task. Options include urgency or standard. If not provided, it will default to standard.
status string The progress of the task. Can either be pending or completed.
callback_url string A url string where the task creator can monitor the progress of the task.
response null or JSON object An object containing the provided annotation/anaylsis for each attachment. Will be null if task has not been completed
completed_at timestamp A string of the UTC timestamp used to identify when the task was completed. Will be null if the task has not been completed.
credit_cost float The cost of performing the task. This will be calculated automatically depending on how many attachments are to be annotated/anaylsed. All pricing is included on the website.

Attachments

Raidon's API supports two ways to provide an attachment. The simplest way is to provide the API endpoint with a string to the url of where the image/file will be founded. Raidon will automatically then attempt to download the image/file.

Alternatively, if you want to provide an attachment that's stored locally, then Raidon supports PUT endpoints allowing the user to upload the image/file without having to go through the hussle to store the data on third-party servers.

Credit Cost

Raidon will automatically provide credit cost associated with a particular task object. This will vary depending on the number of images/files to be annotated/anaylsed as well as whether the task is of Standard or Urgency importance.

Annotation Tasks

Create An Annotation Task

Every task object regardless of annotation type is created via the url: https://raidon.io/api/v1/task/annotation/

curl -X POST \
  https://raidon.io/api/v1/task/annotation/ \
  -H 'Authorization: Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46' \
  -d type='boxes' \
  -d tag='Label all the houses and cars in this drone image' \
  -d attachment='https://dummyimageurl.com/drone_image.jpg' \
  -d categories='house' \
  -d categories='car'
import requests 

headers = {'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46'}
data = {'type': 'boxes', 
        'tag': 'Label all the houses and cars in this drone image', 
        'attachment': 'https://dummyimageurl.com/drone_image.jpg', 
        'categories': ['house', 'car']}
r = requests.post('https://raidon.io/api/v1/task/annotation/',
                  headers=headers,
                  data=data)
r.content
const request = await fetch('https://raidon.io/api/v1/task/annotation', method={
    method: 'POST', 
    headers: {
        'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46', 
    }, 
    body: {
        type: 'boxes',
        tag: 'Label all the houses and cars in this drone image',
        attachment: 'https://dummyimageurl.com/drone_image.jpg', 
        categories: ['house', 'car']
    }
})
const response = await request.json()
console.log(response)

Alternatively, you can provide attachment as a file when making a PUT request.

curl -X PUT \
  https://raidon.io/api/v1/task/annotation/group/ \
  -H 'Authorization: Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46' \
  -F type=boxes \
  -F 'tag=Label all the houses and cars in this drone image' \
  -F attachment=@/Users/username/Documents/drone_image.jpg \
  -F categories=house \
  -F categories=car 
import requests 

headers = {'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46'}
data = {'type': 'boxes', 
        'tag': 'Label all the houses and cars in this drone image', 
        'attachment': open('/Users/username/Documents/drone_image.jpg', 'r').read(), 
        'categories': ['house', 'car']}
r = requests.post('https://raidon.io/api/v1/task/annotation/',
                  headers=headers,
                  data=data)
r.content

The above command returns JSON structured like this:

{
    "task_id": "3nVwbDc1fatgvIyFlMkGbUSfexHojSCT",
    "created_at": "2018-08-10T16:35:45.677764Z",
    "type": "boxes",
    "tag": "Label all the houses and cars in this drone image",
    "data": {
        "attachment": "https://dummyimageurl.com/drone_image.jpg",
        "categories": [
            "house",
            "car"
        ]
    },
    "importance": "standard",
    "status": "Pending",
    "callback_url": "www.raidon.io/api/v1/task/3nVwbDc1fatgvIyFlMkGbUSfexHojSCT",
    "response": null,
    "completed_at": null,
    "credit_cost": "$0.08"
}

This API endpoint is used for the creation of an annotation task object. The required paramaters are type, tag, attachment and categories. The attachment parameter must be provided as a url to the image/file if making a POST request. Alternatively, the file can be uploaded directly when making a PUT request.

Optional parameters include importance. Our workers aim to complete urgency tasks within 12 hours and standard tasks within 3 days. However, this will vary depening on how many images need to be anaylsed.

Upon creating a task object, you're provided a short description of the created task including the callback_url. You can visit this url instantly to review the progress of the task. Furthermore, credit_cost will inform you of the cost of this particular operation. All payments are taken at the end of the calender month.

HTTP Request

https://raidon.io/api/v1/task/annotation/

Parameters

Parameter Type Required Description
type string Yes Type of task you want the worker to complete. Currently supported options include boxes, polygons, lines and landmarks. All options are case-sensitive
tag string Yes Instructions to the worker on how to annotate the image.
attachment URL or File Yes A string URL of the source to be annotated if making a POST request. Otherwise, the file to be annotated when making a PUT request.
categories list Yes A JSON list of strings describing the intended categories.
importance string No String describing the urgency of the task. Options include urgency or standard. If not provided, it will default to standard.

Annotation Task Response

The response will vary for an annotation task depending on the type of task it was.

2D Boxes Task Response

{
    "task_id": "3nVwbDc1fatgvIyFlMkGbUSfexHojSCT",
    "created_at": "2018-08-10T16:35:45.677764Z",
    "type": "boxes",
    "tag": "Label all the houses and cars in this drone image",
    "data": {
        "attachment": "https://dummyimageurl.com/drone_image.jpg",
        "categories": [
            "house",
            "car"
        ]
    },
    "importance": "standard",
    "status": "completed",
    "callback_url": "www.raidon.io/api/v1/task/3nVwbDc1fatgvIyFlMkGbUSfexHojSCT",
    "response": {
        "annotation": {
            "size": {
                "depth": "3",
                "width": "250",
                "height": "175"
            },
            "object": [
                {
                    "name": "car",
                    "pose": "Unspecified",
                    "bndbox": {
                        "xmax": "194",
                        "xmin": "169",
                        "ymax": "72",
                        "ymin": "52"
                    },
                    "occluded": "0",
                    "difficult": "0",
                    "truncated": "0"
                },
                {
                    "name": "house",
                    "pose": "Unspecified",
                    "bndbox": {
                        "xmax": "161",
                        "xmin": "111",
                        "ymax": "73",
                        "ymin": "34"
                    },
                    "occluded": "0",
                    "difficult": "0",
                    "truncated": "0"
                },
                {
                    "name": "car",
                    "pose": "Unspecified",
                    "bndbox": {
                        "xmax": "124",
                        "xmin": "101",
                        "ymax": "105",
                        "ymin": "86"
                    },
                    "occluded": "0",
                    "difficult": "0",
                    "truncated": "0"
                }
            ],
            "filename": "drone_image.jpg",
            "segmented": "0"
        }
    },
    "completed_at": "2018-08-10T18:37:41.308384Z",
    "credit_cost": "$0.08"
}

If the task was succesfully completed by the worker, the response object will contain a single key, namely: annotation. It itself will include a number of keys with the most important property being object. This will give details about each object deteted along with the bounding box cordinates represented by the property bndbox. Every bndbox will have the following properties:

Polygon Task Response

{
    "task_id": "tlWDJl9VPKVPa93y4O4G9mB4gWwkVHlg",
    "created_at": "2018-08-10T16:35:45.677764Z",
    "type": "boxes",
    "tag": "Label all the houses and cars in this drone image",
    "data": {
        "attachment": "https://dummyimageurl.com/drone_image.jpg",
        "categories": [
            "house",
            "car"
        ]
    },
    "importance": "standard",
    "status": "completed",
    "callback_url": "www.raidon.io/api/v1/task/tlWDJl9VPKVPa93y4O4G9mB4gWwkVHlg",
    "response": {
        "annotation": {
            "size": {
                "depth": "3",
                "width": "250",
                "height": "175"
            },
            "object": [
                {
                    "name": "car",
                    "pose": "Unspecified",
                    "polygon": {
                        "x1": "98",
                        "x2": "122",
                        "x3": "122",
                        "x4": "98",
                        "y1": "149",
                        "y2": "149",
                        "y3": "140",
                        "y4": "140"
                    },
                    "occluded": "0",
                    "difficult": "0",
                    "truncated": "0"
                },
                {
                    "name": "house",
                    "pose": "Unspecified",
                    "polygon": {
                        "x1": "184",
                        "x2": "201",
                        "x3": "200",
                        "x4": "183",
                        "y1": "102",
                        "y2": "102",
                        "y3": "85",
                        "y4": "86"
                    },
                    "occluded": "0",
                    "difficult": "0",
                    "truncated": "0"
                },
                {
                    "name": "car",
                    "pose": "Unspecified",
                    "polygon": {
                        "x1": "89",
                        "x2": "163",
                        "x3": "146",
                        "x4": "90",
                        "y1": "127",
                        "y2": "125",
                        "y3": "38",
                        "y4": "61"
                    },
                    "occluded": "0",
                    "difficult": "0",
                    "truncated": "0"
                }
            ],
            "filename": "drone_image.jpg",
            "segmented": "0"
        }
    },
    "completed_at": "2018-08-10T18:37:41.308384Z",
    "credit_cost": "$0.08"
}

If the task was succesfully completed by the worker, the response object will contain a single key, namely: annotation. It itself will include a number of keys with the most important property being object. This will give details about each object deteted along with the polygon cordinates represented by the property polygon. Every polygon will have the following properties:

Lines Task Response

{
    "task_id": "iCxkah7KCUKJQO7TZ3cznF7rxu9CfRgQ",
    "created_at": "2018-08-10T18:36:42.649433Z",
    "type": "lines",
    "tag": "Tag the train tracks in this image",
    "data": {
        "attachment": "https://dummyimageurl.com/drone_image.jpg",
        "categories": [
            "track"
        ]
    },
    "importance": "standard",
    "status": "completed",
    "callback_url": "www.raidon.io/api/v1/task/iCxkah7KCUKJQO7TZ3cznF7rxu9CfRgQ",
    "response": {
        "annotation": {
            "size": {
                "depth": "3",
                "width": "250",
                "height": "175"
            },
            "object": [
                {
                    "line": {
                        "x1": "509",
                        "x2": "466",
                        "y1": "467",
                        "y2": "440"
                    },
                    "name": "track",
                    "pose": "Unspecified",
                    "occluded": "0",
                    "difficult": "0",
                    "truncated": "0"
                },
                {
                    "line": {
                        "x1": "487",
                        "x2": "451",
                        "y1": "467",
                        "y2": "439"
                    },
                    "name": "track",
                    "pose": "Unspecified",
                    "occluded": "0",
                    "difficult": "0",
                    "truncated": "0"
                },
                {
                    "line": {
                        "x1": "475",
                        "x2": "446",
                        "y1": "467",
                        "y2": "440"
                    },
                    "name": "track",
                    "pose": "Unspecified",
                    "occluded": "0",
                    "difficult": "0",
                    "truncated": "0"
                }
            ],
            "filename": "drone_image.jpg",
            "segmented": "0"
        }
    },
    "completed_at": "2018-08-10T20:37:48.623466Z",
    "credit_cost": "$0.08"
}

If the task was succesfully completed by the worker, the response object will contain a single key, namely: annotation. It itself will include a number of keys with the most important property being object. This will give details about each object deteted along with the line cordinates represented by the property line. Every line will have the following properties:

Landmarks Task Response

{
    "task_id": "iCxkah7KCUKJQO7TZ3cznF7rxu9CfRgQ",
    "created_at": "2018-08-10T18:36:42.649433Z",
    "type": "landmarks",
    "tag": "Tag the appropriate features",
    "data": {
        "attachment": "https://dummyimageurl.com/face.jpg",
        "categories": [
            "left_eye",
            "right_eye",
            "lip",
            "face_underline"
        ]
    },
    "importance": "standard",
    "status": "completed",
    "callback_url": "www.raidon.io/api/v1/task/iCxkah7KCUKJQO7TZ3cznF7rxu9CfRgQ",
    "response": {
        "annotation": {
            "size": {
                "depth": "3",
                "width": "250",
                "height": "175"
            },
            "object": [
                {
                    "name": "face_underline",
                    "pose": "Unspecified",
                    "landmark": {
                        "x1": "358",
                        "y1": "256"
                    },
                    "occluded": "0",
                    "difficult": "0",
                    "truncated": "0"
                },
                {
                    "name": "face_underline",
                    "pose": "Unspecified",
                    "landmark": {
                        "x1": "354",
                        "y1": "269"
                    },
                    "occluded": "0",
                    "difficult": "0",
                    "truncated": "0"
                },
                {
                    "name": "lip",
                    "pose": "Unspecified",
                    "landmark": {
                        "x1": "256",
                        "y1": "266"
                    },
                    "occluded": "0",
                    "difficult": "0",
                    "truncated": "0"
                },...
            ],
            "filename": "face.jpg",
            "segmented": "0"
        }
    },
    "completed_at": "2018-08-10T20:37:48.623466Z",
    "credit_cost": "$0.08"
}

If the task was succesfully completed by the worker, the response object will contain a single key, namely: annotation. It itself will include a number of keys with the most important property being object. This will give details about each object deteted along with the landmarks cordinates represented by the property landmarks. Every landmarks will have the following properties:

Audio Transcription Tasks

Create An Audio Trans. Task

curl -X POST \
  https://raidon.io/api/v1/task/audiotranscription/ \
  -H 'Authorization: Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46' \
  -d tag='Transcribe the video after 10:20' \
  -d attachment='https://youtube.com/video_link' 
import requests 

headers = {'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46'}
data = {'tag': 'Transcribe the video after 10:20', 
        'attachment': 'https://youtube.com/video_link'}
r = requests.post('https://raidon.io/api/v1/task/audiotranscription/',
                  headers=headers,
                  data=data)
r.content
const request = await fetch('https://raidon.io/api/v1/task/audiotranscription/', method={
    method: 'POST', 
    headers: {
        'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46', 
    }, 
    body: {
        tag: 'Transcribe the video after 10:20',
        attachment: 'https://youtube.com/video_link'
    }
})
const response = await request.json()
console.log(response)

Alternatively, you can provide attachment as a file when making a PUT request.

curl -X PUT \
  https://raidon.io/api/v1/task/audiotranscription/ \
  -H 'Authorization: Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46' \
  -F 'tag=Transcribe the video after 10:20' \
  -F attachment=@/Users/username/Downloads/audio_file.mp4
import requests 

headers = {'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46'}
data = {'tag': 'Transcribe the video after 10:20', 
        'attachment': open('/Users/username/Documents/audio_file.mp4', 'r').read()}
r = requests.post('https://raidon.io/api/v1/task/audiotranscription/',
                  headers=headers,
                  data=data)
r.content

The above command returns JSON structured like this:

{
    "task_id": "Y4dXbtUXgu2R2mws0GPSzZwytLZSYxDk",
    "created_at": "2018-08-12T17:05:00.002412Z",
    "type": "audiotranscription",
    "tag": "Transcribe the video after 10:20",
    "data": {
        "attachment": "https://www.youtube.com/video_link"
    },
    "importance": "standard",
    "status": "pending",
    "callback_url": "www.raidon.io/api/v1/task/Y4dXbtUXgu2R2mws0GPSzZwytLZSYxDk",
    "response": null,
    "completed_at": null,
    "credit_cost": "$None"
}

This API endpoint is used for the creation of an audiotranscription task object. The required paramaters are tag and attachment. The attachment parameter must be provided as a url to the audio file to be anaylsed if making a POST request. Alternatively, the audio file can be uploaded directly when making a PUT request.

Optional parameters include importance. Our workers aim to complete urgency tasks within 12 hours and standard tasks within 3 days. However, this will vary depening on how many images need to be anaylsed.

Upon creating a task object, you're provided a short description of the created task including the callback_url. You can visit this url instantly to review the progress of the task. Furthermore, credit_cost will inform you of the cost of this particular operation. All payments are taken at the end of the calender month. The credit_cost will initially be null but will be updated upon the creation of the task.

HTTP Request

https://raidon.io/api/v1/task/audiotranscription/

Parameters

Parameter Type Required Description
tag string Yes Instructions to the worker on how to annotate the image.
attachment URL or File Yes A string URL of the source to be anaylsed if making a POST request. Otherwise, the file to be anaylsed when making a PUT request.
importance string No String describing the urgency of the task. Options include urgency or standard. If not provided, it will default to standard.

Audio Trans. Task Response

{
    "task_id": "Y4dXbtUXgu2R2mws0GPSzZwytLZSYxDk",
    "created_at": "2018-08-12T17:05:00.002412Z",
    "type": "audiotranscription",
    "tag": "Transcribe the video after 10:20",
    "data": {
        "attachment": "https://www.youtube.com/video_link"
    },
    "importance": "standard",
    "status": "completed",
    "callback_url": "www.raidon.io/api/v1/task/Y4dXbtUXgu2R2mws0GPSzZwytLZSYxDk",
    "response": {
        "text": "b'Raidon is an amazing service to use for data annotation or audio transcription. It leverages real human workers to power your machine learning applications!'",
        "filename": "www.youtube.com/video_link/"
    },
    "completed_at": "2018-08-12T17:10:07.932296Z",
    "credit_cost": "$1.0"
}

If the task was succesfully completed by the worker, the response object will contain two keys, namely: text and filename. The text parameter will contain what our worker transcribed from the audio file and filename will include the source of the audio.

Grouped Tasks

A grouped task allows you to organise smaller tasks into one giving you the freedom to include more than one attachment. It provides an easier and simpler approach to creating a task for the annotation/anaylses of a number of attachments that may be seen as being part of the same project.

For example, if you have 1000s of pictures to be annotated by bounding boxes for a machine-learning project, rather than creating 1000s of task objects or sending 1000s of API calls you can send a single API call. This provides you a single URL to check the progress of the project.

Grouped Annotation Tasks

Create a Grouped Annotation Task

curl -X POST \
  https://raidon.io/api/v1/task/annotation/group/ \
  -H 'Authorization: Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46' \
  -d type='boxes' \
  -d tag='Label all the houses and cars in this drone image' \
  -d attachment='https://dummyimageurl.com/drone_image.jpg' \
  -d attachment='https://dummyimageurl.com/drone_image_2.jpg' \
  -d categories='house' \
  -d categories='car'
import requests 

headers = {'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46'}
data = {'type': 'boxes', 
        'tag': 'Label all the houses and cars in this drone image', 
        'attachment': ['https://dummyimageurl.com/drone_image.jpg',
                       'https://dummyimageurl.com/drone_image_2.jpg'], 
        'categories': ['house', 'car']}
r = requests.post('https://raidon.io/api/v1/task/annotation/group',
                  headers=headers,
                  data=data)
r.content
const request = await fetch('https://raidon.io/api/v1/task/annotation/group', method={
    method: 'POST', 
    headers: {
        'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46', 
    }, 
    body: {
        type: 'boxes',
        tag: 'Label all the houses and cars in this drone image',
        attachment: ['https://dummyimageurl.com/drone_image.jpg',
                     'https://dummyimageurl.com/drone_image_2.jpg'], 
        categories: ['house', 'car']
    }
})
const response = await request.json()
console.log(response)

Alternatively, you can provide attachment as a list of files when making a PUT request.

curl -X PUT \
  https://raidon.io/api/v1/task/annotation/group/ \
  -H 'Authorization: Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46' \
  -F type=boxes \
  -F 'tag=Label all the houses and cars in this drone image' \
  -F attachment=@/Users/username/Documents/drone_image.jpg \
  -F attachment=@/Users/username/Documents/drone_image_2.jpg \
  -F categories=house \
  -F categories=car 
import requests 

headers = {'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46'}
data = {'type': 'boxes', 
        'tag': 'Label all the houses and cars in this drone image', 
        'attachment': [open('/Users/username/Documents/drone_image.jpg', 'r').read(),
                       open('/Users/username/Documents/drone_image_2.jpg', 'r').read()], 
        'categories': ['house', 'car']}
r = requests.post('https://raidon.io/api/v1/task/annotation/group',
                  headers=headers,
                  data=data)
r.content

The above command returns JSON structured like this:

{
    "task_id": "RVeZQeJFuHnnpg0Bjqt0tPJSlYAgtqy6",
    "created_at": "2018-08-10T16:35:45.677764Z",
    "type": "boxes",
    "tag": "Label all the houses and cars in this drone image",
    "data": {
        "attachment": [
            "https://dummyimageurl.com/drone_image.jpg", 
            "https://dummyimageurl.com/drone_image_2.jpg"
        ],
        "categories": [
            "house",
            "car"
        ]
    },
    "importance": "standard",
    "status": "pending",
    "callback_url": "www.raidon.io/api/v1/task/RVeZQeJFuHnnpg0Bjqt0tPJSlYAgtqy6",
    "response": null,
    "completed_at": null,
    "credit_cost": "$0.16"
}

This API endpoint is used for the creation of a grouped annotation task object. The required paramaters are type, tag, attachment and categories. The attachment parameter must be provided as a JSON list of urls to the image/file to be annotated if making a POST request. Alternatively, when making a PUT, the attachment parameter must be provided as a JSON list of files to be annotated.

Optional parameters include importance. Our workers aim to complete urgency tasks within 12 hours and standard tasks within 3 days. However, this will vary depening on how many images need to be anaylsed.

Upon creating a task object, you're provided a short description of the created task including the callback_url. You can visit this url instantly to review the progress of the task. Furthermore, credit_cost will inform you of the cost of this particular operation. All payments are taken at the end of the calender month.

HTTP Request

https://raidon.io/api/v1/task/annotation/group/

Parameters

Parameter Type Required Description
type string Yes Type of task you want the worker to complete. Currently supported options include boxes, polygons, lines and landmarks. All options are case-sensitive
tag string Yes Instructions to the worker on how to annotate the image.
attachment JSON list of URLs or files Yes A JSON list of URLs of the source to be annotated if making a POST request. Otherwise, a JSON list of files to be annotated when making a PUT request.
categories list Yes A JSON list of strings describing the intended categories.
importance string No String describing the urgency of the task. Options include urgency or standard. If not provided, it will default to standard.

Grouped Annotation Task Response

An example of a response from a grouped annotation task

{
    "task_id": "RVeZQeJFuHnnpg0Bjqt0tPJSlYAgtqy6",
    "created_at": "2018-08-12T20:38:44.248784Z",
    "type": "boxes",
    "tag": "Label all the houses and cars in this drone image",
    "data": {
        "attachment": [
            "https://dummyimageurl.com/drone_image.jpg", 
            "https://dummyimageurl.com/drone_image_2.jpg"
        ],
        "categories": [
            "house", 
            "car"
        ]
    },
    "importance": "standard",
    "status": "completed",
    "callback_url": "www.raidon.io/api/v1/task/RVeZQeJFuHnnpg0Bjqt0tPJSlYAgtqy6",
    "response": [
        {
            "annotation": {
                "size": {
                    "depth": "3",
                    "width": "250",
                    "height": "175"
                },
                "object": [
                {
                    "name": "car",
                    "pose": "Unspecified",
                    "bndbox": {
                        "xmax": "194",
                        "xmin": "169",
                        "ymax": "72",
                        "ymin": "52"
                    },
                    "occluded": "0",
                    "difficult": "0",
                    "truncated": "0"
                },
                {
                    "name": "house",
                    "pose": "Unspecified",
                    "bndbox": {
                        "xmax": "161",
                        "xmin": "111",
                        "ymax": "73",
                        "ymin": "34"
                    },
                    "occluded": "0",
                    "difficult": "0",
                    "truncated": "0"
                },
                {
                    "name": "car",
                    "pose": "Unspecified",
                    "bndbox": {
                        "xmax": "124",
                        "xmin": "101",
                        "ymax": "105",
                        "ymin": "86"
                    },
                    "occluded": "0",
                    "difficult": "0",
                    "truncated": "0"
                }
            ],
                "filename": "drone_image.jpg",
                "segmented": "0"
            }
        }, 
        {
            "annotation": {
                "size": {
                    "depth": "3",
                    "width": "800",
                    "height": "600"
                },
                "object": [
                    {
                        "name": "car",
                        "pose": "Unspecified",
                        "bndbox": {
                            "xmax": "420",
                            "xmin": "315",
                            "ymax": "511",
                            "ymin": "433"
                        },
                        "occluded": "0",
                        "difficult": "0",
                        "truncated": "0"
                    },
                    {
                        "name": "car",
                        "pose": "Unspecified",
                        "bndbox": {
                            "xmax": "272",
                            "xmin": "200",
                            "ymax": "522",
                            "ymin": "430"
                        },
                        "occluded": "0",
                        "difficult": "0",
                        "truncated": "0"
                    },
                    {
                        "name": "car",
                        "pose": "Unspecified",
                        "bndbox": {
                            "xmax": "172",
                            "xmin": "92",
                            "ymax": "537",
                            "ymin": "417"
                        },
                        "occluded": "0",
                        "difficult": "0",
                        "truncated": "0"
                    },
                    {
                        "name": "car",
                        "pose": "Unspecified",
                        "bndbox": {
                            "xmax": "640",
                            "xmin": "529",
                            "ymax": "239",
                            "ymin": "138"
                        },
                        "occluded": "0",
                        "difficult": "0",
                        "truncated": "0"
                    },
                    {
                        "name": "house",
                        "pose": "Unspecified",
                        "bndbox": {
                            "xmax": "373",
                            "xmin": "226",
                            "ymax": "364",
                            "ymin": "221"
                        },
                        "occluded": "0",
                        "difficult": "0",
                        "truncated": "0"
                    }
                ],
                "filename": "drone_image_2.jpg",
                "segmented": "0"
            }
        }
    ],
    "completed_at": "2018-08-12T20:41:02.261393Z",
    "credit_cost": "$0.16"
}

If the task was succesfully completed by the worker, the response object will be a list of dictionaries with every dictionary having a single key, namely: annotation . It itself will include a number of keys with the most important property being object. This will give details about each object deteted along with the bndbox, polygon , line or landmark coordinates depending on the type of task. In conclusion, the responses from a grouped annotation will be near identical to the response from excecuting a single task with the only difference being that response will be a list.

Grouped Audio Trans. Tasks

curl -X POST \
  https://raidon.io/api/v1/task/audiotranscription/group/ \
  -H 'Authorization: Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46' \
  -d tag='Transcribe the first video after 10:20 and second from the start' \
  -d attachment='https://www.youtube.com/video_link' \
  -d attachment='https://www.youtube.com/video_link_2'
import requests 

headers = {'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46'}
data = {'tag': 'Transcribe the video after 10:20', 
        'attachment': ['https://youtube.com/video_link',
                       'https://youtube.com/video_link_2']}
r = requests.post('https://raidon.io/api/v1/task/audiotranscription/group/',
                  headers=headers,
                  data=data)
r.content
const request = await fetch('https://raidon.io/api/v1/task/audiotranscription/group/', method={
    method: 'POST', 
    headers: {
        'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46', 
    }, 
    body: {
        tag: 'Transcribe the video after 10:20',
        attachment: [
            'https://youtube.com/video_link',
            'https://youtube.com/video_link_2'
        ]
    }
})
const response = await request.json()
console.log(response)

Alternatively, you can provide attachment as a list to include more than one image

curl -X POST \
  https://raidon.io/api/v1/task/audiotranscription/group \
  -H 'Authorization: Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46' \
  -F 'tag=Transcribe the first video after 10:20 and the second from the start' \
  -F attachment=@/Users/username/Documents/audio_file.mp4 \
  -F attachment=@/Users/username/Documents/audio_file_2.mp4
import requests 

headers = {'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46'}
data = {'tag': 'Transcribe the video after 10:20', 
        'attachment': [open('/Users/username/Documents/audio_file.mp4', 'r').read(),
                       open('/Users/username/Documents/audo_file_2.mp4', 'r').read()]}
r = requests.post('https://raidon.io/api/v1/task/audiotranscription/group/',
                  headers=headers,
                  data=data)
r.content

The above command returns JSON structured like this:

{
    "task_id": "Y4dXbtUXgu2R2mws0GPSzZwytLZSYxDk",
    "created_at": "2018-08-12T17:05:00.002412Z",
    "type": "audiotranscription",
    "tag": "Transcribe the first video after 10:20 and the second from the start",
    "data": {
        "attachment": [
            "https://www.youtube.com/video_link", 
            "https://www.youtube.com/video_link_2"
        ]
    },
    "importance": "standard",
    "status": "pending",
    "callback_url": "www.raidon.io/api/v1/task/Y4dXbtUXgu2R2mws0GPSzZwytLZSYxDk",
    "response": null,
    "completed_at": null,
    "credit_cost": "$None"
}

This API endpoint is used for the creation of a grouped audiotranscription task object. The required paramaters are tag and attachment. The attachment parameter must be provided as a JSON list of urls to the audio file to be anaylsed if making a POST request. Alternatively, when making a PUT, the attachment parameter must be provided as a JSON list of audio files to be anaylsed.

Optional parameters include importance. Our workers aim to complete urgency tasks within 12 hours and standard tasks within 3 days. However, this will vary depening on how many images need to be anaylsed.

Upon creating a task object, you're provided a short description of the created task including the callback_url. You can visit this url instantly to review the progress of the task. Furthermore, credit_cost will inform you of the cost of this particular operation. All payments are taken at the end of the calender month. The credit_cost will initially be null but will be updated upon the creation of the task.

HTTP Requesr

https://raidon.io/api/v1/task/audiotranscription/group/

Parameters

Parameter Type Required Description
tag string Yes Instructions to the worker on how to annotate the image.
attachment JSON list of URLs or files Yes A JSON list of URLs of the sources to be anaylsed if making a POST request. Otherwise, a JSON list of files to be anaylsed when making a PUT request.
importance string No String describing the urgency of the task. Options include urgency or standard. If not provided, it will default to standard.

Grouped Audio Transcription Task Response

{
    "task_id": "Y4dXbtUXgu2R2mws0GPSzZwytLZSYxDk",
    "created_at": "2018-08-12T17:05:00.002412Z",
    "type": "audiotranscription",
    "tag": "Transcribe the first video after 10:20 and the second from the start",
    "data": {
        "attachment": [
            "https://www.youtube.com/video_link",
            "https://www.youtube.com/video_link_2"
        ]
    },
    "importance": "standard",
    "status": "completed",
    "callback_url": "www.raidon.io/api/v1/task/Y4dXbtUXgu2R2mws0GPSzZwytLZSYxDk",
    "response": [
        {
            "text": "b'Raidon is an amazing service to use for data annotation or audio transcription. It leverages real human workers to power your machine learning applications!'",
            "filename": "www.youtube.com/video_link/"
        },
        {
            "text": "b'Raidon's API provides a grouped task endpoint allowing you to organise smaller tasks into one giving you the freedom to include more than one attachment. It provides an easier and simpler approach to creating a task for the annotation/anaylses of a number of attachments that may be seen as being part of the same project.'",
            "filename": "www.youtube.com/video_link_2/"
        }
    ],
    "completed_at": "2018-08-12T17:10:07.932296Z",
    "credit_cost": "$1.0"
}

If the task was succesfully completed by the worker, the response object will be a list of dictionaries with every dictionary containing two keys, namely: text and filename. The text parameter will contain what our worker transcribed from the audio file and filename will include the source of the audio.

Task Endpoints

Retrieve a Task

curl -X GET \
  https://raidon.io/api/v1/task/{task_id}/ \
  -H 'Authorization: Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46' 
import requests 

headers = {'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46'}
r = requests.get('https://raidon.io/api/v1/task/{task_id}/', 
                 headers=headers)
r.content
const request = await fetch('https://raidon.io/api/v1/task/{task_id}/', {
    method: 'GET', 
    headers: {
        'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46'
    }
})
const response = await request.json()
console.log(response)

The above command returns JSON structured like this:

{
    "task_id": "Iieck5Gb0mYyWxWgMhgTccQBDHGXR2Nv",
    "created_at": "2018-08-09T13:17:28.504253Z",
    "type": "boxes",
    "tag": "Tag all the houses or cars from this drone image. Also use tight bouding boxes.",
    "data": {
        "attachment": "https://dummyimageurl.com/drone_image.jpg",
        "annotation_categories": ["house", "car"]
    },
    "importance": "standard",
    "status": "pending",
    "callback_url": "https://raidon.io/api/v1/task/Iieck5Gb0mYyWxWgMhgTccQBDHGXR2Nv",
    "response": null,
    "completed_at": null
}

This API endpoint is used for retrieval of any task regardless of it's type.

HTTP Request

https://raidon.io/api/v1/task/{task_id}/

Parameters

Parameter Type Required Description
task_id string Yes A unique 32 length identifier for a task.

Update a Task

curl -X PATCH \
  https://raidon.io/api/v1/task/update/{task_id}/ \
  -H 'Authorization: Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46' \
  -d type='polygons'
import requests 

headers = {'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46'}
data = {'type': 'polygons'}
r = requests.patch('https://raidon.io/api/v1/task/update/{task_id}/',
                    headers=headers, 
                    data=data)
r.content
const request = await fetch('https://raidon.io/api/v1/task/update/{task_id}/', {
    method: 'PATCH', 
    headers: {
        'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46'
    }, 
    body: {
        'type': 'polygons'
    }
})
const response = await request.json()
console.log(response)

The above command returns JSON structured like this:

{
    "task_id": "Iieck5Gb0mYyWxWgMhgTccQBDHGXR2Nv",
    "created_at": "2018-08-09T13:17:28.504253Z",
    "type": "polygons",
    "tag": "Tag all the houses or cars from this drone image. Also use tight bouding boxes.",
    "data": {
        "attachment": "https://dummyimageurl.com/drone_image.jpg",
        "annotation_categories": ["house", "car"]
    },
    "importance": "standard",
    "status": "pending",
    "callback_url": "https://raidon.io/api/v1/task/Iieck5Gb0mYyWxWgMhgTccQBDHGXR2Nv",
    "response": null,
    "completed_at": null
}

This API endpoint is used for updating a task's type, tag or importance. You can only update a task if it hasn't been completed.

HTTP Request

https://raidon.io/api/v1/task/update/{task_id}/

Parameters

Parameter Type Required Description
type string No Type of task you want the worker to complete. Currently supported options include boxes, polygons, lines, landmarks and audiotranscription. All options are case-sensitive.
tag string No Instructions to the worker on how to annotate the image or analyse the attachment.
importance string No String describing the urgency of the task. Options include urgency or standard. If not provided, it will default to standard.

Delete a Task

curl -X DELETE \
  https://raidon.io/api/v1/task/destroy/{task_id}/ \
  -H 'Authorization: Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46' 
import requests 

headers = {'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46'}
r = requests.delete('https://raidon.io/api/v1/task/destroy/{task_id}/',
                    headers=headers)
r.content
const request = await fetch('https://raidon.io/api/v1/task/destroy/{task_id}/', {
    method: 'DELETE', 
    headers: {
        'Authorization': 'Token 49fa77ade8a3b9504a8d5138836030b44dd9ea46'
    }
})
const response = await request.json()
console.log(response)

The above command returns 204 No Content if the deletion was successful

This API endpoint is used for deleting a task. You can only delete a task if it hasn't been completed.

HTTP Request

https://raidon.io/api/v1/task/destroy/{task_id}/

Parameters

Parameter Type Required Description
task_id string Yes A unique 32 length identifier for a task.