Canonical Tags

Unique entities described by a set of annotations

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 objects and as AttachedCanonicalTag 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

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

List the tags in a project

GET 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

Request Body

200: OK

[{
  "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": "[e-mail]", "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": "[e-mail]", "username": "tester"}
}]

Create one or more Tags

POST 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

Request Body

201: Created Array of created (or found) CanonicalTag objects.

[{
  "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": "[e-mail]", "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": "[e-mail]", "username": "tester"}
}]

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)

Edit a tag's values

POST https://api.annolab.ai/v1/tag/{domain_entity_id}

Edits a CanonicalTag's typeName and/or attributes. Does not alter attachments.

Headers

Request Body

200: OK

{
    "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": "[e-mail]", "username": "tester"}
}

Delete a single tag by its domainEntityId

DELETE https://api.annolab.ai/v1/tag/{domainEntityId}

Deletes a CanonicalTag. Delete will cascade and delete all related AttachedCanonicalTag objects as well.

Headers

200: OK

Bulk delete tags by values

DELETE https://api.annolab.ai/v1/tag

Deletes a CanonicalTag. Delete will cascade and delete all related AttachedCanonicalTag objects as well.

Headers

Request Body

200: OK

{
}

AttachedCanonicalTag Object

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

{
  "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": "[e-mail]",
      "usernname": "tester"
  }
}

Attach a tag to an instrument

POST https://api.annolab.ai/v1/instrument-tag

Attaches a canonical tag to an instrument.

Headers

Request Body

201: Created Information about the AttachedCanonicalTag that was created

{
  "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": "[e-mail]", "username": "tester"}
}

Unattach a tag from an instrument

DELETE https://api.annolab.ai/v1/instrument-tag

Removes a canonical tag attachment from an instrument

Headers

Request Body

204: No Content

{
    // Response
}

(Alternate) Unattach a tag from an instrument

DELETE 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

Headers

200: OK The tag was unattached succesfully.

404: Not Found Either the tag or instrument do not exist, or the tag is not attached to that instrument.

Attach a tag to a source

POST https://api.annolab.ai/v1/source-tag

Attaches a canonical tag to a source.

Headers

Request Body

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": "[e-mail]", "username": "tester"}
}

Unattach a tag from a source.

DELETE https://api.annolab.ai/v1/source-tag

Removes a canonical tag attachment from a source

Headers

Request Body

201: Created

(Alternate) Unattach a tag from a source

DELETE 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

Headers

200: OK The tag was successfully unattached from the source file.

404: Not Found Either the tag or source do not exist, or the tag is not attached to that source.