# 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](/annotations-and-relations/annotations.md#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](/annotations-and-relations/annotations.md#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="/pages/-MR1mhs6Kumxrgzkeijp#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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.annolab.ai/annotations-and-relations/canonical-tags.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.