This‌ ‌API‌ ‌was‌ ‌developed‌ ‌to‌ ‌make‌ ‌it‌ ‌easy‌ ‌for‌ ‌you‌ ‌to‌ ‌submit‌ ‌images‌ ‌for‌ ‌annotation,‌ ‌receive‌ ‌the‌ ‌ results‌ ‌of‌ ‌images‌ ‌processing‌ ‌and‌ ‌monitor‌ ‌your‌ ‌expenses.‌ ‌The‌ ‌API‌ ‌is‌ ‌implemented‌ ‌as‌ ‌a‌ ‌small‌ ‌ set‌ ‌of‌ ‌REST‌ ‌methods,‌ ‌so‌ ‌you‌ ‌can‌ ‌call‌ ‌them‌ ‌from‌ ‌whatever‌ ‌programming‌ ‌language‌ ‌or‌ ‌environment‌ ‌you're‌ ‌accustomed‌ ‌to‌ ‌use.‌ ‌‌Also‌ ‌you‌ ‌can‌ ‌use‌ ‌the‌ tagias-node‌ ‌npm‌ ‌package‌‌‌ ‌directly‌ ‌in‌ ‌your‌ ‌Node.js‌ ‌projects‌ ‌without‌ ‌any‌ ‌complexity‌ ‌of‌ ‌composing‌ ‌proper‌ ‌HTTP‌ ‌requests‌ ‌manually.‌ ‌And‌ ‌you‌ ‌can‌ ‌install‌ ‌the‌ ‌‌tagias-python‌ ‌package‌‌ ‌if‌ ‌you're‌ ‌using‌ ‌Python.‌

Before calling the API methods you need to get an API key on the tagias.com web page. This key has to be included in every API call - just put it into the HTTP Authorization header using the "Api-Key" prefix (e.g. "Api-Key whLUN5vkMFuaR8RuSN3Xg%qLlGfWvfDz").

If the API key is not provided in the Authorization header or if it's incorrect then the API call returns the 401 (Unauthorized) HTTP status code.

If the API call was accepted and processed then it returns the 200 (OK) HTTP status code and JSON object in a response body. This JSON object indicates whether the call was processed successfully or not. In case of error the response body will be like this:

{
    "status": "error",
    "error": "ERRORCODE"
}

The status field will have the value of "error" and the error field will hold the code that explains the cause of the error.

And if the API call was processed successfully then the status field's value will be "ok":

{
    "status": "ok"
}

The detailed description of the response object is provided for each API method.

It is much simpler to use the tagias-node npm package to work with the API. This package is using the axios npm package to make HTTP calls. First of all, you need to install the tagias-node npm package. Just execute the following command in your project's folder: npm install tagias-node --save

Then you need to reference the helper classes within your javascript file:

const { Tagias, TagiasTypes, TagiasStatuses, TagiasError, TagiasErrors } = require('tagias-node');

import { Tagias, TagiasTypes, TagiasStatuses, TagiasError, TagiasErrors } from 'tagias-node';

There are 5 classes to reference:

• Tagias - the main helper class; you need to create an instance of this class to make calls to API methods
• TagiasTypes - an enumeration containing the available annotation types; see the Package Types section for more details
• TagiasStatuses - an enumeration containing a list of possible package statuses; see the Package Statuses section for more details
• TagiasError - an exception object that will be thrown when an authentication problem occurs or any unsuccessful API call happens (when response status equals to "error"); the message property contains the error description in English and the code property contains the error code extracted from the response
• TagiasErrors - an enumeration containing all possible Tagias error codes in case you need to analyze the TagiasError object's code property value in your exception handler.

You can omit any class you don't need in the require (import) statement.

After referencing the required helper classes you need to create an instance of the Tagias class providing your API key to the constructor call:

const tagias = new Tagias('­­­­­whLUN5vkMFuaR8RuSN3Xg%qLlGfWvfDz');

And now you can use the created tagias instance object to make calls to the API methods. All helper's methods are asynchronous, so do not forget the await keyword. For example, here is how you can get the list of all your packages:

const packages = await tagias.getPackages();
for (const pack of packages) {
    console.log(`${pack.name}, ${pack.type}, ${pack.status}`);
}

It is recommended to enclose your calls in the try-catch statement and handle TagiasError exceptions and the axios package exceptions that could be thrown during code execution:

// reference the helper classes
const { Tagias, TagiasError } = require('tagias-node');

try {
    // create tagias helper object
    const tagias = new Tagias('­­­­­whLUN5vkMFuaR8RuSN3Xg%qLlGfWvfDz');

    // get the list of all your packages
    const packages = await tagias.getPackages();
    for (const pack of packages) {
        console.log(`${pack.name}, ${pack.type}, ${pack.status}`);
    }
} catch (e) {
    if (e instanceof TagiasError) {
        // handle a TagiasError exception
        console.log(`${e.name}: ${e.message} (${e.code})`);
    } else {
        // all other (e.g. axios) exceptions
        console.log(e);
    }
}

The examples of usage for all helper's methods you can find in the API Methods section.

Also there is the tagias-python package if you're using Python. First of all, you need to install it. Just execute the following command in your project's folder:

pip install tagias

python -m pip install tagias

from tagias.tagias import TagiasHelper, TagiasError, TagiasTypes, TagiasStatuses

There are 5 classes to reference:

• TagiasHelper - the main helper class; you need to create an instance of this class to make calls to API methods
• TagiasTypes - an enumeration containing the available annotation types; see the Package Types section for more details
• TagiasStatuses - an enumeration containing a list of possible package statuses; see the Package Statuses section for more details
• TagiasError - an exception object that will be thrown when an authentication problem occurs or any unsuccessful API call happens (when response status equals to "error"); the message property contains the error description in English and the code property contains the error code extracted from the response
• TagiasErrors - an enumeration containing all possible Tagias error codes in case you need to analyze the TagiasError object's code property value in your exception handler.

You can omit any class you don't need in the import statement.

After referencing the required helper classes you need to create an instance of the TagiasHelper class providing your API key to the constructor call:

helper = TagiasHelper('­­­­­whLUN5vkMFuaR8RuSN3Xg%qLlGfWvfDz')

And now you can use the created helper instance object to make calls to the API methods. For example, here is how you can get the list of all your packages:

helper = TagiasHelper('­­­­­whLUN5vkMFuaR8RuSN3Xg%qLlGfWvfDz')
packages = helper.get_packages()
for package in packages: print(' {} {} {}'.format(package['id'], package['name'], package['status']))

It is recommended to enclose your calls in the try-except statement and handle TagiasError exceptions and all communication exceptions that could be thrown during code execution:

# import the tagias api helper classes
from tagias.tagias import TagiasHelper, TagiasError

# Replace the test API key with your own private API key
apiKey = 'test'

# Testing the TAGIAS external API methods
try:
# create tagias helper object
helper = TagiasHelper(apiKey)

# get the list of all your packages
packages = helper.get_packages()
print('Packages:')
for package in packages: print(' * {} {}'.format(package['id'], package['name']))
except TagiasError as e:
# handle a TagiasError exception
print('TagiasError: {} ({})'.format(e.message, e.code))

The images submitted for annotation have to be grouped in packages. Each package defines the annotation type and other properties important for the processing:

• name - name that you should assign to each package to recognize it later on web pages and reports
• type - defines the annotation type you'd like to get for each image in the package
• descr - detailed description of the desired annotation (which objects should be marked and how, the criteria for the perfect annotation, any specific requirements, etc.)
• labels - list of text labels (should be provided for the ClassificationSingle and ClassificationMultiple package types only)
• callback - URL where the result annotations will be POSTed upon package completion (or balance exhaustion)
• baseurl - if all images are available from the same web server then you can put the starting part of the URL here to avoid repeating it for every image URL
• pictures - list of URLs for images aimed for annotation; the actual URL for each image is created by concatenation of the baseurl value and each pictures element value (image name)

All specified image files should be hosted somewhere on publicly accessible web servers and they should be accessible without any authentication via provided image URLs.

Currently there are 6 types of annotations (package types) supported by tagias.com. Each type defines the format of annotation to be created for each image within this particular package. The formats are described below for package types individually.

The coordinates, the width and the height values that are provided in all annotation elements are absolute values taken within the image space.

For example, if the width of an image is 1024 and its height is 720 then the value for the x coordinate is from 0 to 1023, and the value for the y coordinate is from 0 to 719.

Each object on each image will be surrounded by a separate rectangle. The result annotation for each image is an array of objects with the following fields:

The objects of interest on each image are marked by multi-segment lines

The objects could be marked with multi-segment lines forming a polygonal figure around the object

The annotation will consist of one or multiple points pinned to specific objects on the image

You have to provide a list of text labels and each image will be associated with only one label from that list

You have to provide a list of text labels and each image will be associated with one or multiple labels from that list

Each package has the status property value of which could be one of the following:

ACTIVE, SUSPENDED, STOPPED, DELETED, FINISHED.

When you create a package it gets the ACTIVE status and it is ready for processing immediately. Using the "Modify package status" method you can change the ACTIVE status to the STOPPED status and then back to ACTIVE. While in the STOPPED status the package is not available for processing. Also you can change the status to DELETED - this status excludes the package from the processing and from the "Get the list of all packages" method's response

When there are many images within the package that cannot be accessed or have inappropriate content then the package gets the SUSPENDED status and temporarily gets excluded from processing. Please contact us to resolve this issue.

And when all images within the package got their annotations then the package gets the FINISHED status. After that the array of result annotations for all completed images is POSTed to the callback URL (if you have specified it during package creation).

When all images from the package are annotated (or when the balance is not positive anymore) the result JSON object (constructed of annotated images information) is delivered to you using the callback URL specified for each package.

The result is placed into the request body and is POSTed to that URL so you can automatically receive and store it. We will try to send the result up to 10 times until we get the 200 HTTP response

The POST request will contain the callback key in the Authorization HTTP header (with the "Api-Key" prefix) as a proof that the information comes from us. You can find this key on the tagias.com website.

The result is sent along with the finished date that defines the moment when the last annotation was saved. If your callback endpoint receives the result information with the same finished date as before then you can ignore it (probably it is an additional try because we could get the 200 response for the first try).

POST https://p.tagias.com/api/v1/tagias/packages

This method creates a new package of images and makes it ACTIVE (i.e. available for processing).

Request body:

Each image URL is constructed by concatenating the baseurl property value and each element from the pictures array. For example, the following properties define same images URLs:

{
    "baseurl": "https://p.tagias.com/samples/",
    "pictures": [
        "dog.8001.jpg",
        "dog.8002.jpg",
        "dog.8003.jpg"
    ]
}

                    

{
    "baseurl": "",
    "pictures": [
        "https://p.tagias.com/samples/dog.8001.jpg",
        "https://p.tagias.com/samples/dog.8002.jpg",
        "https://p.tagias.com/samples/dog.8003.jpg"
    ]
}

                    

Still the sample on the top is smaller and easier to read. Also the result annotations will contain short image names instead of full URLs in this case and that will make the result object smaller as well.

The constructed full URL must start with "http", otherwise this image will be ignored and not loaded within the created package. The number of loaded images is returned in the pictures_num property of the response body

Success response body:

Possible error codes (when response status equals "error"):

• NONAME - package name is missing
• NOPICTURES - no or empty picture array
• NOLABELS - no label array for the classification task (or less than 2 items in the array)
• BADCALLBACK - the callback URL is malformed
• BADBASEURL - the baseurl URL is malformed
• BADTYPE - the type value is not among the allowed values
• INTERNAL - an internal error has occurred

GET https://p.tagias.com/api/v1/tagias/packages

This method retrieves the list of all packages you have created earlier sorted by the creation date. Only a limited set of properties for each package is returned by this method. To get all properties for a particular package you can use the "Get package properties" method.

Success response body:

Possible error codes (when response status equals "error"):

• INTERNAL - an internal error has occurred

GET https://p.tagias.com/api/v1/tagias/packages/:id

This method retrieves all properties for a package using its unique identifier specified in the query URL.

Request parameter: id - unique package identifier

Success response body:

Possible error codes (when response status equals "error"):

• NOTFOUND - the package with the specified id does not exist
• INTERNAL - an internal error has occurred

PATCH https://p.tagias.com/api/v1/tagias/packages/:id

This method modifies the status of a package using its unique identifier specified in the query URL.

The following status changes are allowed:

• from ACTIVE to STOPPED
• from STOPPED to ACTIVE
• from ACTIVE, SUSPENDED, STOPPED, FINISHED to DELETED

Request parameter: id - unique package identifier

Request body:

Success response body:

Possible error codes (when response status equals "error"):

• NOTFOUND - the package with the specified id does not exist
• BADSTATUS - the status value is not among the allowed values or this kind of change is not allowed
• INTERNAL - an internal error has occurred

POST https://p.tagias.com/api/v1/tagias/packages/result/:id

This method asks the tagias.com server to send currently available annotations for all completed images from the specified package to the package's callback endpoint. See the Annotation Results section for more details.

Request parameter: id - unique package identifier

Success response body:

Possible error codes (when response status equals "error")::

• NOTFOUND - the package with the specified id does not exist
• BADCALLBACK - the package's callback URL is malformed or empty
• INTERNAL - an internal error has occurred

The results will be sent to the callback endpoint with the following information:

The content of the result field depends on the annotation type. You can find the proper formats and examples in the Package Types section. If this particular image could not be accessed or has inappropriate content then the result object will have the error property with the value of "Declined by moderator".

GET https://p.tagias.com/api/v1/tagias/packages/result/:id

This method returns currently available annotations for all completed images from the specified package.

Request parameter: id - unique package identifier

Success response body:

Possible error codes (when response status equals "error"):

• NOTFOUND - the package with the specified id does not exist
• INTERNAL - an internal error has occurred

GET https://p.tagias.com/api/v1/tagias/balance

This method returns the current balance amount and the list of all operations modifying the balance amount sorted from the newest to the oldest.

Success response body:

Possible error codes (when response status equals "error"):

• NOTFOUND - the balance record does not exist
• INTERNAL - an internal error has occurred