# Canonical Tags

Canonical Tags are a way to reference a singular entity that is comprised of multiple fixed annotations. This is a useful abstraction when dealing with things like Airframes (Make, Model, Serial), People (First, Middle, Last), or Land (Section, Township, Range, QQ1, QQ2, etc). They are intended as a uniquely disambiguating abstraction for the multiple ways that a single entity can be expressed or written in a document.

Canonical Tags exist in two states. In their unattached state as [CanonicalTag](#canonicaltag-object) objects and as [AttachedCanonicalTag](#attachedcanonicaltag-object) object when describing a CanonicalTag that has been attached to an entire instrument or source file.

## CanonicalTag Object

A canonical tag describes a unique entity defined by a type and an array of attributes

| Attribute Name  | Type                                                                                     | Description                                                                                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| typeName        | String                                                                                   | Name describing the type of canonical tag                                                                                                                            |
| attributes      | [CanonicalAnnotation](https://docs.annolab.ai/annotations#canonicalannotation-object)\[] | Array of canonical annotations that comprise the canonical tag                                                                                                       |
| domainEntityId? | Integer                                                                                  | Unique id describing the canonical tag object                                                                                                                        |
| status?         | String                                                                                   | <p>"Created" or "Found"<br>Returned when creating tags in bulk to reflect whether each tag already exists (Found) or was newly created in the request (Created).</p> |

```json
{
  "typeName": "Airframe Inventory",  
  "attributes": [
      {"name": "Make", "value": "Beech"}, {"name": "Model", "value": "C24R"}, {"name": "Serial Number", "value": "MC-453"}
  ]
}
```

## List the tags in a project

<mark style="color:blue;">`GET`</mark> `https://api.annolab.ai/v1/project/{group_name}/{project_name}/tags`

Returns a paginated list of tags in a project. Returns a limit of 10,000 tags per page/request.

#### Headers

| Name                                            | Type   | Description                                                                                                                                                         |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | <p>Where you put your api key. Exporting a project requires a key with "Read" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

#### Request Body

| Name | Type    | Description                                                                                                                                              |
| ---- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page | Integer | <p>Which page to return. Defaults to 1.<br>E.g. { "page" : 1 } returns first 1,000 results. { "page" : 2 } returns results 1,001 through 2,000. etc.</p> |

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

```json
[{
  "typeName": "Airframe Tag",
  "domainEntityId": 235,
  "attributes": [
      {"name": "Make", "value": "Raytheon"}, 
      {"name": "Model", "value": "850XP"}, 
      {"name": "Serial Number", "value": "755"},
      {"name": "Internal ID", "value": 4501}
  ],
  "createdBy": {"id": 14, "email": "tester@gmail.com", "username": "tester"}
}, {
  "typeName": "Airframe Tag",
  "domainEntityId": 240,
  "attributes": [
      {"name": "Make", "value": "CESSNA"}, 
      {"name": "Model", "value": "T303"}, 
      {"name": "Serial Number", "value": "T30300300"},
      {"name": "Internal ID", "value": 3561}
  ],
  "createdBy": {"id": 14, "email": "tester@gmail.com", "username": "tester"}
}]
```

{% endtab %}
{% endtabs %}

## Create one or more Tags

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

Creates canonical tags. (Does not attach). If an identical canonical tag already exists, it does not create at duplicate.

#### Headers

| Name                                            | Type | Description                                                                                                                                                         |
| ----------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> |      | <p>Where you put your api key. Exporting a project requires a key with "Read" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

#### Request Body

| Name                                                | Type            | Description                                                                           |
| --------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- |
| projectIdentifier<mark style="color:red;">\*</mark> | String\|Number  | Project name or id of the project                                                     |
| tags<mark style="color:red;">\*</mark>              | CanonicalTag\[] | List of [CanonicalTag](#canonicaltag-object) objects to create                        |
| groupName                                           | String          | Name of the group that owns the project (only required if projectIdentifer is string) |

{% tabs %}
{% tab title="201: Created Array of created (or found) CanonicalTag objects." %}

```json
[{
  "typeName": "Airframe Tag",
  "domainEntityId": 235,
  "attributes": [
      {"name": "Make", "value": "Raytheon"}, 
      {"name": "Model", "value": "850XP"}, 
      {"name": "Serial Number", "value": "755"},
      {"name": "Internal ID", "value": 4501}
  ],
  "createdBy": {"id": 14, "email": "tester@gmail.com", "username": "tester"}
}, {
  "typeName": "Airframe Tag",
  "domainEntityId": 240,
  "attributes": [
      {"name": "Make", "value": "CESSNA"}, 
      {"name": "Model", "value": "T303"}, 
      {"name": "Serial Number", "value": "T30300300"},
      {"name": "Internal ID", "value": 3561}
  ],
  "createdBy": {"id": 14, "email": "tester@gmail.com", "username": "tester"}
}]
```

{% endtab %}
{% endtabs %}

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

```python
import requests

ANNO_LAB_API_KEY = 'XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX' 

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

create_tag_url = 'https://api.annolab.ai/v1/tag'

project_name = "title-demo" 
group_name = "AnnoLab"
tag_list = [
  {
    'typeName': 'Airframe Inventory', 
    'attributes': [
      {'name': 'Make', 'value': 'Cessna'},
      {'name': 'Model', 'value': '501'},
      {'name': 'Serial Number', 'value': '501-0050'}
    ]
  }
]

tagPayload = {
  "projectIdentifier": project_name,
  "groupName": group_name,
  "tags": tag_list
}

r = requests.post(create_tag_url, headers=headers, json=tagPayload)

json_response = r.json()

print(json_response)

```

{% endtab %}
{% endtabs %}

## Edit a tag's values

<mark style="color:green;">`POST`</mark> `https://api.annolab.ai/v1/tag/{domain_entity_id}`

Edits a [CanonicalTag](#canonicaltag-object)'s typeName and/or attributes. Does not alter attachments.

#### Headers

| Name                                            | Type   | Description                                                                                                                                                         |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | <p>Where you put your api key. Exporting a project requires a key with "Read" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

#### Request Body

| Name                                            | Type                   | Description                                                                                                                                |
| ----------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| typeName<mark style="color:red;">\*</mark>      | String                 | Name describing the type of canonical tag                                                                                                  |
| attributes\[]<mark style="color:red;">\*</mark> | CanonicalAnnotation\[] | Array of [CanonicalAnnotation](https://docs.annolab.ai/annotations#canonicalannotation-object)\[] objects that comprise the canonical tag. |

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

```json
{
    "typeName": "Airframe Tag",
    "domainEntityId": 235,
    "attributes": [
        {"name": "Make", "value": "Raytheon"}, 
        {"name": "Model", "value": "850XP"}, 
        {"name": "Serial Number", "value": "755"},
        {"name": "Internal ID", "value": 4501}
    ],
    "createdBy": {"id": 14, "email": "tester@gmail.com", "username": "tester"}
}
```

{% endtab %}
{% endtabs %}

## Delete a single tag by its domainEntityId

<mark style="color:red;">`DELETE`</mark> `https://api.annolab.ai/v1/tag/{domainEntityId}`

Deletes a [CanonicalTag](#canonicaltag-object). Delete will cascade and delete all related [AttachedCanonicalTag](#attachedcanonicaltag-object) objects as well.

#### Headers

| Name                                            | Type   | Description                                                                                                                                                         |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | <p>Where you put your api key. Exporting a project requires a key with "Read" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

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

{% endtab %}
{% endtabs %}

## Bulk delete tags by values

<mark style="color:red;">`DELETE`</mark> `https://api.annolab.ai/v1/tag`

Deletes a [CanonicalTag](#canonicaltag-object). Delete will cascade and delete all related [AttachedCanonicalTag](#attachedcanonicaltag-object) objects as well.

#### Headers

| Name                                            | Type   | Description                                                                                                                                                         |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | <p>Where you put your api key. Exporting a project requires a key with "Read" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

#### Request Body

| Name                                                | Type            | Description                                                                                         |
| --------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------- |
| projectIdentifier<mark style="color:red;">\*</mark> | String\|Integer | String of the project containing the tag or the unique identifier of the project                    |
| tags<mark style="color:red;">\*</mark>              | CanonicalTag\[] | List of [CanonicalTag](#canonicaltag-object) objects to delete                                      |
| groupName                                           | String          | Name of the group that owns the project (only required if projectIdentifier is a string and not id) |

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

```javascript
{
}
```

{% endtab %}
{% endtabs %}

## AttachedCanonicalTag Object

An attached canonical tag object describes the attachment of a canonical tag to some Instrument or Source

<table><thead><tr><th width="206.33333333333331">Attribute Name</th><th width="211">Type</th><th>Description</th></tr></thead><tbody><tr><td>tagType</td><td>String</td><td>What the canonical tag is attached to. Can be attached to either "Instrument" or "Source"</td></tr><tr><td>typeName</td><td>String</td><td>Name describing the type of canonical tag</td></tr><tr><td>domainEntityId</td><td>Integer</td><td>Unique id of the canonical tag</td></tr><tr><td>annotationId?</td><td>Integer</td><td>Unique id describing where the canonical tag is attached. e.g. the unique id of the instrument</td></tr><tr><td>sourceReferenceId?</td><td>Integer</td><td>Unique id describing where the canonical tag is attached. e.g. the unique id of the file</td></tr><tr><td>attributes</td><td><a href="../annotations#canonicalannotation-object">CanonicalAnnotation</a>[]</td><td>Array of canonical annotations that comprise the canonical tag</td></tr><tr><td>createdBy</td><td>UserObject|Null</td><td>Object that consists of a id, email, and username associated with the person who assigned the tag </td></tr></tbody></table>

```json
{
  "tagType": "Instrument", 
  "typeName": "Airframe Inventory", 
  "domainEntityId": 39, 
  "annotationId": 402970, 
  "attributes": [
      {"name": "Make", "value": "Beech"}, {"name": "Model", "value": "C24R"}, {"name": "Serial Number", "value": "MC-453"}
  ],
  "createdBy": {
      "id": 15,
      "email": "tester@gmail.com",
      "usernname": "tester"
  }
}
```

## Attach a tag to an instrument

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

Attaches a canonical tag to an instrument.&#x20;

#### Headers

| Name                                            | Type   | Description                                                                                                                                                         |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | <p>Where you put your api key. Exporting a project requires a key with "Read" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

#### Request Body

| Name                                           | Type         | Description                                                |
| ---------------------------------------------- | ------------ | ---------------------------------------------------------- |
| instrumentId<mark style="color:red;">\*</mark> | Integer      | Unique identifier for the instrument you wish to attach to |
| tag<mark style="color:red;">\*</mark>          | CanonicalTag | [CanonicalTag](#canonicaltag-object) object to attach      |

{% tabs %}
{% tab title="201: Created Information about the AttachedCanonicalTag that was created" %}

```javascript
{
  "tagType": "Instrument",
  "typeName": "Airframe Tag",
  "domainEntityId": 235,
  "attributes": [
      {"name": "Make", "value": "Raytheon"}, 
      {"name": "Model", "value": "850XP"}, 
      {"name": "Serial Number", "value": "755"},
      {"name": "Internal ID", "value": 4501}
  ],
  "createdBy": {"id": 14, "email": "tester@gmail.com", "username": "tester"}
}
```

{% endtab %}
{% endtabs %}

## Unattach a tag from an instrument

<mark style="color:red;">`DELETE`</mark> `https://api.annolab.ai/v1/instrument-tag`

Removes a canonical tag attachment from an instrument

#### Headers

| Name                                            | Type   | Description                                                                                                                                                         |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | <p>Where you put your api key. Exporting a project requires a key with "Read" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

#### Request Body

| Name                                           | Type         | Description                                                |
| ---------------------------------------------- | ------------ | ---------------------------------------------------------- |
| instrumentId<mark style="color:red;">\*</mark> | Integer      | Unique identifier for the instrument you wish to attach to |
| tag<mark style="color:red;">\*</mark>          | CanonicalTag | [CanonicalTag](#canonicaltag-object) object to delete      |

{% tabs %}
{% tab title="204: No Content " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## (Alternate) Unattach a tag from an instrument

<mark style="color:red;">`DELETE`</mark> `https://api.annolab.ai/v1/instrument-tag/{instrument_id}/{domain_entity_id}`

Alternative endpoint to unattach a tag from an instrument using the instrument id and domain entity id of the tag.

An instrument id is equivalent to the annotation id of a classification annotation.

#### Path Parameters

| Name                                             | Type    | Description                                                                                                                            |
| ------------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| instrument\_id<mark style="color:red;">\*</mark> | Integer | The instrument\_id from which to unattach the tag. An instrument id is equivalent to the annotation id of a classification annotation. |
| domain\_entity\_id                               | Integer | The domain\_entity\_id of the canonical tag.                                                                                           |

#### Headers

| Name                                            | Type   | Description                                                                                                                                                         |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | <p>Where you put your api key. Exporting a project requires a key with "Read" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

{% tabs %}
{% tab title="200: OK The tag was unattached succesfully." %}

{% endtab %}

{% tab title="404: Not Found Either the tag or instrument do not exist, or the tag is not attached to that instrument." %}

{% endtab %}
{% endtabs %}

## Attach a tag to a source

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

Attaches a canonical tag to a source.

#### Headers

| Name                                            | Type   | Description                                                                                                                                                         |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | <p>Where you put your api key. Exporting a project requires a key with "Read" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

#### Request Body

| Name                                                | Type              | Description                                                                                                                         |
| --------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| projectIdentifier<mark style="color:red;">\*</mark> | String \| Integer | Either the project name or id of the project containing the source. If passing the project name, groupName is a required parameter. |
| groupName                                           | String            | The name of the group which owns the project. Required when passing a project name.                                                 |
| directoryIdentifier                                 | String \| Integer | Name or id of the directory containing the source. Required when passing a source name.                                             |
| sourceIdentifier<mark style="color:red;">\*</mark>  | String \| Integer | Either the source file name or id of the source to attach the tag. If passing source name, directoryIdentifier is required.         |
| tag<mark style="color:red;">\*</mark>               | CanonicalTag      | [CanonicalTag](#canonicaltag-object) object to attach                                                                               |

{% tabs %}
{% tab title="201: Created Information about the newly created attachment" %}

```
{
  "tagType": "Source File",
  "typeName": "Airframe Tag",
  "domainEntityId": 235,
  "attributes": [
      {"name": "Make", "value": "Raytheon"}, 
      {"name": "Model", "value": "850XP"}, 
      {"name": "Serial Number", "value": "755"},
      {"name": "Internal ID", "value": 4501}
  ],
  "createdBy": {"id": 14, "email": "tester@gmail.com", "username": "tester"}
}
```

{% endtab %}
{% endtabs %}

## Unattach a tag from a source.

<mark style="color:red;">`DELETE`</mark> `https://api.annolab.ai/v1/source-tag`

Removes a canonical tag attachment from a source

#### Headers

| Name                                            | Type   | Description                                                                                                                                                         |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | <p>Where you put your api key. Exporting a project requires a key with "Read" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

#### Request Body

| Name                                                | Type              | Description                                                                                                                         |
| --------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| projectIdentifier<mark style="color:red;">\*</mark> | String \| Integer | Either the project name or id of the project containing the source. If passing the project name, groupName is a required parameter. |
| sourceIdentifier<mark style="color:red;">\*</mark>  | String \| Integer | Either the source file name or id of the source to attach the tag. If passing source name, directoryIdentifier is required.         |
| tag<mark style="color:red;">\*</mark>               | CanonicalTag      | [CanonicalTag](#canonicaltag-object) object to attach                                                                               |
| groupName                                           | String            | The name of the group which owns the project. Required when passing a project name.                                                 |
| directoryIdentifier                                 | String \| Integer | Name or id of the directory containing the source. Required when passing a source name.                                             |

{% tabs %}
{% tab title="201: Created " %}

{% endtab %}
{% endtabs %}

## (Alternate) Unattach a tag from a source

<mark style="color:red;">`DELETE`</mark> `https://api.annolab.ai/v1/source-tag/{source_id}/{domain_entity_id}`

Alternative endpoint to unattach a tag from a source using the source id and domain entity id of the tag.

#### Path Parameters

| Name               | Type    | Description                                           |
| ------------------ | ------- | ----------------------------------------------------- |
| source\_id         | Integer | Id of the source file from which to unattach the tag. |
| domain\_entity\_id | Integer | The domain\_entity\_id of the canonical tag.          |

#### Headers

| Name          | Type   | Description                                                                                                                                                         |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | String | <p>Where you put your api key. Exporting a project requires a key with "Read" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

{% tabs %}
{% tab title="200: OK The tag was successfully unattached from the source file." %}

{% endtab %}

{% tab title="404: Not Found Either the tag or source do not exist, or the tag is not attached to that source." %}

{% endtab %}
{% endtabs %}