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
String
Name describing the type of canonical tag
attributes
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).
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
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
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.
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
Authorization*
Where you put your api key. Exporting a project requires a key with "Read" permissions.
{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}
Request Body
projectIdentifier*
String|Number
Project name or id of the project
tags*
CanonicalTag[]
groupName
String
Name of the group that owns the project (only required if projectIdentifer is string)
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
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
typeName*
String
Name describing the type of canonical tag
attributes[]*
CanonicalAnnotation[]
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
Authorization*
String
Where you put your api key. Exporting a project requires a key with "Read" permissions.
{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}
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
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
projectIdentifier*
String|Integer
String of the project containing the tag or the unique identifier of the project
tags*
CanonicalTag[]
groupName
String
Name of the group that owns the project (only required if projectIdentifier is a string and not id)
AttachedCanonicalTag Object
An attached canonical tag object describes the attachment of a canonical tag to some Instrument or Source
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
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
Attach a tag to an instrument
POST
https://api.annolab.ai/v1/instrument-tag
Attaches a canonical tag to an instrument.
Headers
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
instrumentId*
Integer
Unique identifier for the instrument you wish to attach to
tag*
CanonicalTag
Unattach a tag from an instrument
DELETE
https://api.annolab.ai/v1/instrument-tag
Removes a canonical tag attachment from an instrument
Headers
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
instrumentId*
Integer
Unique identifier for the instrument you wish to attach to
tag*
CanonicalTag
(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
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
Authorization*
String
Where you put your api key. Exporting a project requires a key with "Read" permissions.
{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}
Attach a tag to a source
POST
https://api.annolab.ai/v1/source-tag
Attaches a canonical tag to a source.
Headers
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
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
Unattach a tag from a source.
DELETE
https://api.annolab.ai/v1/source-tag
Removes a canonical tag attachment from a source
Headers
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
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
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.
(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
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
Authorization
String
Where you put your api key. Exporting a project requires a key with "Read" permissions.
{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}
Last updated