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

Attribute Name	Type	Description
typeName	String	Name describing the type of canonical tag
attributes	CanonicalAnnotation[]	Array of canonical annotations that comprise the canonical tag
domainEntityId?	Integer	Unique id describing the canonical tag object
status?	String	"Created" or "Found" Returned when creating tags in bulk to reflect whether each tag already exists (Found) or was newly created in the request (Created).

{
  "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

Name	Type	Description
Authorization*	String	Where you put your api key. Exporting a project requires a key with "Read" permissions. {"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}

Request Body

Name	Type	Description
page	Integer	Which page to return. Defaults to 1. E.g. { "page" : 1 } returns first 1,000 results. { "page" : 2 } returns results 1,001 through 2,000. etc.

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": "[email protected]", "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": "[email protected]", "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

Name	Type	Description
Authorization*		Where you put your api key. Exporting a project requires a key with "Read" permissions. {"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}

Request Body

Name	Type	Description
projectIdentifier*	String|Number	Project name or id of the project
tags*	CanonicalTag[]	List of CanonicalTag objects to create
groupName	String	Name of the group that owns the project (only required if projectIdentifer is string)

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": "[email protected]", "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": "[email protected]", "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

Name	Type	Description
Authorization*	String	Where you put your api key. Exporting a project requires a key with "Read" permissions. {"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}

Request Body

Name	Type	Description
typeName*	String	Name describing the type of canonical tag
attributes[]*	CanonicalAnnotation[]	Array of CanonicalAnnotation[] objects that comprise the canonical tag.

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": "[email protected]", "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

Name	Type	Description
Authorization*	String	Where you put your api key. Exporting a project requires a key with "Read" permissions. {"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}

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

Name	Type	Description
Authorization*	String	Where you put your api key. Exporting a project requires a key with "Read" permissions. {"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}

Request Body

Name	Type	Description
projectIdentifier*	String|Integer	String of the project containing the tag or the unique identifier of the project
tags*	CanonicalTag[]	List of CanonicalTag objects to delete
groupName	String	Name of the group that owns the project (only required if projectIdentifier is a string and not id)

200: OK

{
}

AttachedCanonicalTag Object

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

Attribute Name	Type	Description
tagType	String	What the canonical tag is attached to. Can be attached to either "Instrument" or "Source"
typeName	String	Name describing the type of canonical tag
domainEntityId	Integer	Unique id of the canonical tag
annotationId?	Integer	Unique id describing where the canonical tag is attached. e.g. the unique id of the instrument
sourceReferenceId?	Integer	Unique id describing where the canonical tag is attached. e.g. the unique id of the file
attributes	CanonicalAnnotation[]	Array of canonical annotations that comprise the canonical tag
createdBy	UserObject|Null	Object that consists of a id, email, and username associated with the person who assigned the tag

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

Attach a tag to an instrument

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

Attaches a canonical tag to an instrument.

Headers

Name	Type	Description
Authorization*	String	Where you put your api key. Exporting a project requires a key with "Read" permissions. {"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}

Request Body

Name	Type	Description
instrumentId*	Integer	Unique identifier for the instrument you wish to attach to
tag*	CanonicalTag	CanonicalTag object to attach

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": "[email protected]", "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

Name	Type	Description
Authorization*	String	Where you put your api key. Exporting a project requires a key with "Read" permissions. {"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}

Request Body

Name	Type	Description
instrumentId*	Integer	Unique identifier for the instrument you wish to attach to
tag*	CanonicalTag	CanonicalTag object to delete

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

Name	Type	Description
instrument_id*	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*	String	Where you put your api key. Exporting a project requires a key with "Read" permissions. {"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}

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

Name	Type	Description
Authorization*	String	Where you put your api key. Exporting a project requires a key with "Read" permissions. {"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}

Request Body

Name	Type	Description
projectIdentifier*	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*	String | Integer	Either the source file name or id of the source to attach the tag. If passing source name, directoryIdentifier is required.
tag*	CanonicalTag	CanonicalTag object to attach

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": "[email protected]", "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

Name	Type	Description
Authorization*	String	Where you put your api key. Exporting a project requires a key with "Read" permissions. {"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}

Request Body

Name	Type	Description
projectIdentifier*	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*	String | Integer	Either the source file name or id of the source to attach the tag. If passing source name, directoryIdentifier is required.
tag*	CanonicalTag	CanonicalTag 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.

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

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	Where you put your api key. Exporting a project requires a key with "Read" permissions. {"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}

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.