# Annotations

## Create Annotation

<mark style="color:green;">`POST`</mark> `https://api.annolab.ai/v1/annotation/create`

Create an annotation of some type on a source file. For text file sources, an annotation may reside over an array of character offsets or may simply be a document level (manual) annotation.

#### Headers

| Name          | Type   | Description                                                                                                                                                                 |
| ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | string | <p>Where you put your api key. Creating an annotation requires a key with "Write" permissions.<br><br><code>{"Authorization": "Api-key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

#### Request Body

<table><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>clientId</td><td>string</td><td>string or integer that will be "passed through" the request. Useful in situations where async or bulk requests are used, and relation inserts will follow annotation inserts.</td></tr><tr><td>offsets</td><td>array</td><td>Array of integers describing where the annotation exists in terms of character offsets inside the source text. Leave undefined for document-level annotations or image annotations.</td></tr><tr><td>preventDuplication</td><td>boolean</td><td>Boolean indicating whether duplication protection should be in place. By default this is set to true. <br><br>Duplication being defined by any annotation with the exact same annotation type, offsets, layer, and source. Usually you only want to set this to false if you have multiple manual annotations (e.g. non-offset based) of the same type that you need to add on a source.</td></tr><tr><td>value</td><td>string</td><td>User defined value associated with the annotation</td></tr><tr><td>directoryIdentifier</td><td>string</td><td>Identifier of the directory containing the source that will have the annotation. Either the id or the unique name.</td></tr><tr><td>annoTypeIdentifier</td><td>string</td><td>Identifier of the annotation type associated with the annotation. Either the id or the unique name.</td></tr><tr><td>projectIdentifier</td><td>string</td><td>Identifier of the project containing the annotation. Either the id or the unique name.</td></tr><tr><td>layerIdentifier</td><td>integer</td><td>Identifier of the layer containing the annotation. Either the id or the unique name.</td></tr><tr><td>sourceIdentifier</td><td>integer</td><td>Identifier of the source where the annotation will be created. Either the id or the unique name.</td></tr><tr><td>textBounds</td><td>Geometry|Null</td><td><p>Polygon or MultiPolygon geometry object describing the location of the text the annotation contains within the page. </p><p></p><p>IMPORTANT: Ensure coordinates are in provided clockwise order, ideally from top-left. Otherwise annotations may not render correctly in AnnoLab or other viewers utilizing polygon data.</p><p></p><p>Example:</p><pre class="language-json"><code class="lang-json">{
  "type": "MultiPolygon",
  "coordinates": [
    [[
      [ 0.33, 0.32 ],
      [ 0.37, 0.32 ],
      [ 0.37, 0.34 ],
      [ 0.33, 0.34 ],
      [ 0.33, 0.32 ]
    ]],
    [[
      [ 0.376, 0.329 ],
      [ 0.405, 0.329 ],
      [ 0.405, 0.344 ],
      [ 0.376, 0.344 ],
      [ 0.376, 0.329 ]
    ]]
  ],
}
</code></pre></td></tr><tr><td>imageBounds</td><td>Geometry|Null</td><td><p>Polygon or MultiPolygon geometry object describing the location of the box drawn by a model or user on the page (always rectangular).<br><br>IMPORTANT: Ensure coordinates are provided in clockwise order, ideally from top-left. Otherwise annotations may not render correctly in AnnoLab or other viewers utilizing polygon data.<br><br>Example:</p><pre class="language-json"><code class="lang-json">{
  "type": "Polygon",
  "coordinates": [
    [
      [ 0.33, 0.32 ],
      [ 0.37, 0.32 ],
      [ 0.37, 0.34 ],
      [ 0.33, 0.34 ],
      [ 0.33, 0.32 ]
    ]
  ],
}
</code></pre></td></tr></tbody></table>

{% tabs %}
{% tab title="200 Annotation already exists" %}

```
{
  "id": 44,
  "typeId": 51,
  "typeName": "Place Name",
  "layerId": 5,
  "sourceId": 145,
  "typeId": 112,
  "value": '{latitude:"37.983810", longitude:"23.727539"}',
  "rawValue": 'Athens',
  "offsets": [0, 5]
 }
```

{% endtab %}

{% tab title="201 Annotation was successfully created" %}

```
{
  "id": 44,
  "typeId": 51,
  "typeName": "Place Name",
  "layerId": 5,
  "sourceId": 145,
  "typeId": 112,
  "value": '{latitude:"37.983810", longitude:"23.727539"}',
  "rawValue": 'Athens',
  "offsets": [0, 5]
}
```

{% endtab %}

{% tab title="400 Annotation creation failed" %}

```
{
    "message": "Information about why creation failed"
}
```

{% endtab %}
{% endtabs %}

Examples of how to make an annotation create request

{% tabs %}
{% tab title="Python" %}

```python
import requests

ANNO_LAB_API_KEY = 'XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX'

annotation = {
  'annoTypeIdentifier': 'Place Name',
  'projectIdentifier': 'New NER Project',
  'layerIdentifier': 'NER Gold',
  'sourceIdentifier': 145,
  'offsets': [0, 5],
  'directoryIdentifier': 'Wikipedia Subset',
  'value': '{latitude:"37.983810", longitude:"23.727539"}'
}

headers = {
  'Authorization': 'Api-Key '+ANNO_LAB_API_KEY,
}

url = 'https://api.annolab.ai/v1/annotation/create'

response = requests.post(url, headers=headers, json=annotation)

print(response.json())
```

{% endtab %}
{% endtabs %}

## Bulk Create Annotations

<mark style="color:green;">`POST`</mark> `https://api.annolab.ai/v1/annotation/bulk-create`

Create a set of up to 2000 annotations in one request (can be a mix of many different annotation types and spread across many source files). \
\
80% faster than individual inserts in most cases

#### Headers

| Name          | Type   | Description                                                                                                                                                               |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | string | <p>Where you put your api key. Creating annotations requires a key with "write" permissions.<br><br><code>{"Authorization": "Api-key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

#### Request Body

| Name               | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| preventDuplication | boolean | <p>Boolean indicating whether duplication protection should be in place. By default this will be set to true<br><br>Duplication being defined by any annotation with the exact same annotation type, offsets, layer, and source. <br><br>We recommend only setting this to false if you are 100% sure that no duplications exist in the request, in which case it will be much quicker.</p> |
| annotations        | array   | Array of annotation objects that you wish to insert.A maximum of 2000 annotations can be created in one request.                                                                                                                                                                                                                                                                            |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

Examples of how to bulk create annotations

{% tabs %}
{% tab title="Python" %}

```python
import requests

ANNO_LAB_API_KEY = 'XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX'

headers = {
  'Authorization': 'Api-Key '+ANNO_LAB_API_KEY,
}

bulk_request = {
  'preventDuplication': True
  'annotations': [
    {
      'annoTypeIdentifier': 'Place Name',
      'projectIdentifier': 'New NER Project',
      'schemaIdentifier': 'NER',
      'layerIdentifier': 'NER Gold',
      'sourceIdentifier': 145,
      'offsets': [0, 5],
      'directoryIdentifier': 'Wikipedia Subset',
      'value': '{latitude:"37.983810", longitude:"23.727539"}',
      'clientId': "24a"
    },
    {
      'annoTypeIdentifier': 'Place Name',
      'projectIdentifier': 'New NER Project',
      'schemaIdentifier': 'NER',
      'layerIdentifier': 'NER Gold',
      'sourceIdentifier': 145,
      'offsets': [120, 128],
      'directoryIdentifier': 'Wikipedia Subset',
      'value': '{latitude:"37.983810", longitude:"23.727539"}',
      'clientId': "24b"
    }
  ]
}

url = 'https://api.annolab.ai/v1/annotation/bulk-create'

response = requests.post(url, headers=headers, json=bulk_request)
```

{% endtab %}
{% endtabs %}

## Annotation Object

An object corresponding to a single annotation

<table><thead><tr><th width="193.33333333333331">Attribute Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>annotationId</td><td>Integer</td><td>Unique id for the annotation</td></tr><tr><td>sourceReferenceId</td><td>Integer</td><td>Unique id for the file that contains the annotation</td></tr><tr><td>typeName</td><td>String</td><td>Name of the type of annotation</td></tr><tr><td>value</td><td>String</td><td>By default is the text that the annotation contains (can be manually overidden)</td></tr><tr><td>pageNumber</td><td>Integer</td><td>Starting page of the annotation</td></tr><tr><td>endPageNumber</td><td>Integer|Null</td><td>Ending page of the annotation (if single page annotation will be null)</td></tr><tr><td>offsets</td><td>Integer[]</td><td>Array describing character offsets of the annotation within the source</td></tr><tr><td>textBounds</td><td>Geometry|Null</td><td><p>MultiPolygon geometry object describing the location of the text the annotation contains within the page. </p><p></p><p>IMPORTANT: Ensure coordinates are in provided clockwise order, ideally from top-left. Otherwise annotations may not render correctly in AnnoLab or other viewers utilizing polygon data.</p><p></p><p>Example:</p><pre class="language-json"><code class="lang-json">{
  "type": "MultiPolygon",
  "coordinates": [
    [[
      [ 0.33, 0.32 ],
      [ 0.37, 0.32 ],
      [ 0.37, 0.34 ],
      [ 0.33, 0.34 ],
      [ 0.33, 0.32 ]
    ]],
    [[
      [ 0.376, 0.329 ],
      [ 0.405, 0.329 ],
      [ 0.405, 0.344 ],
      [ 0.376, 0.344 ],
      [ 0.376, 0.329 ]
    ]]
  ],
}
</code></pre></td></tr><tr><td>imageBounds</td><td>Geometry|Null</td><td><p>Polygon or MultiPolygon geometry object describing the location of the box drawn by a model or user on the page (always rectangular).<br><br>IMPORTANT: Ensure coordinates are provided in clockwise order, ideally from top-left. Otherwise annotations may not render correctly in AnnoLab or other viewers utilizing polygon data.<br><br>Example:</p><pre class="language-json"><code class="lang-json">{
  "type": "Polygon",
  "coordinates": [
    [
      [ 0.33, 0.32 ],
      [ 0.37, 0.32 ],
      [ 0.37, 0.34 ],
      [ 0.33, 0.34 ],
      [ 0.33, 0.32 ]
    ]
  ],
}
</code></pre></td></tr><tr><td>createdBy</td><td>Integer</td><td>User id that created the annotation (or user id that invoked the model)</td></tr><tr><td>updatedBy</td><td>Integer</td><td>User Id that updated the annotation</td></tr><tr><td>confidence</td><td>Float</td><td>Value between 0 and 100 representing the confidence of the OCR translation of any text bounds the annotation contains. <br>If annotation contains multiple text bounds, will be an average of all containing texts.</td></tr><tr><td>score</td><td>Float</td><td>Value between 0 and 1 representing sureness of a machine learning model in applying the annotation.<br><br>We calculate this by taking the average of the SoftMax for all tokens comprising the annotation</td></tr><tr><td>layerId</td><td>Integer</td><td>Id for the layer that contains the annotation</td></tr><tr><td>isReviewed</td><td>Boolean</td><td>Has the annotation been reviewed</td></tr><tr><td>reviewedBy</td><td>Integer|Null</td><td>Reviewer that reviewed the annotation</td></tr><tr><td>reviewedAt</td><td>DateTime|Null</td><td>Time of review</td></tr><tr><td>modelSourceId</td><td>Integer</td><td>Id for the model that produced the annotation</td></tr><tr><td>modelSource</td><td>String</td><td>Name of the model that produced the annotation</td></tr></tbody></table>

```json
{
    'annotationId': 403992,
    'sourceReferenceId': 12341, 
    'typeName': 'Grantor', 
    'value': ' Carsuo', 
    'pageNumber': 3, 
    'endPageNumber': null, 
    'offsets': [1320, 1326], 
    'textBounds': {'type': 'MultiPolygon', 'coordinates': [[[[0.565917551517487, 0.769474387168884], [0.609824299812317, 0.769511699676514], [0.609820425510406, 0.778583765029907], [0.565913617610931, 0.778546392917633], [0.565917551517487, 0.769474387168884]]]]}, 
    'imageBounds': null, 
    'createdBy': 5, 
    'updatedBy': null, 
    'confidence': 96.7900390625, 
    'score': 0.7074922025203705, 
    'layerId': 635, 
    'isReviewed': False, 
    'reviewedBy': null, 
    'reviewedAt': null, 
    'modelSourceId': 12, 
    'modelSource': 'Party Name Extractor'
}
```

## CanonicalAnnotation Object

An abstract form of an annotation that is not grounded in any explicit mention or context, simplified to the components of name and value.&#x20;

These objects cannot be created directly, instead they exist as attributes of [CanonicalTag](https://docs.annolab.ai/canonical-tags#canonicaltag-object) objects.

<table><thead><tr><th width="166.33333333333331">Attribute Name</th><th width="163">Type</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>String</td><td>The annotation type name. Must already exist as an annotation type in your project</td></tr><tr><td>value</td><td>String</td><td>Canonical value describing the annotation</td></tr></tbody></table>

```json
{
    "name": "Make",
    "value": "Cessna",
}
```