Annotations

Retrieve annotations attached to Media Drive items. An annotation is a shape with a category and derived measurements, produced by an AI App or drawn by a reviewer. Every annotation belongs to an annotation set, identified by its labelGroupId. Endpoints return Annotation, Annotation Set or Annotation Summary Row objects.

Base URL

https://api.unleashlive.com

---

Authentication

All endpoints require a Bearer token in the Authorization header. We recommend using a Personal Access Token (PAT). See the Authentication section for how to create one.

Authorization: Bearer <YOUR_PAT>

The team is resolved from the token.

---

Endpoints

Get Annotations for Media Drive Items

POST /v1/library/annotations

POST Try it →

Returns all annotations for the given Media Drive items, with decoded shape geometry. The response is an array of arrays: each inner array corresponds to the item at the same index in libraryItemIds, and is empty when that item has no annotations. Response is not paginated.

Request Body

Parameter	Type	Description
libraryItemIds	String[]	Required. Media Drive item IDs, as returned by the Media Drive API

Example Request

{
  "libraryItemIds": [
    "MTc0NTg4NDIwMTAwMCM4N2UyZjllOS03Mjk2LTQ1NDktYThkMy1lMjA0OWUxN2E3MWU",
    "MTc0NTg4NDIwMjAwMCMyNWJhYTA3Ny02YTRlLTQyNjQtYjg0Ni04ZjM0ZmJiMmFiYWE"
  ]
}

Example Response

[
  [
    {
      "id": "7c3f5d81-2b64-4e0a-9f1d-3a8e5c2d7b40",
      "libraryItemId": "MTc0NTg4NDIwMTAwMCM4N2UyZjllOS03Mjk2LTQ1NDktYThkMy1lMjA0OWUxN2E3MWU",
      "labelGroupId": "a3f21c40-9d17-4b8e-b2c1-77e0a94d3f12#1745884213000",
      "folderId": "MTc0NTg4NDIwMDAwMCNiZGQ5NDM2YS0zZmQ0LTQ0YjQtOGZjYS03M2FmNmJlM2EyNDU",
      "shapeType": "POLYGON",
      "shape": {
        "vertices": [
          { "x": 812.31, "y": 466.02 },
          { "x": 908.77, "y": 470.55 },
          { "x": 901.4, "y": 540.18 },
          { "x": 806.12, "y": 534.9 }
        ]
      },
      "category": "Crack",
      "classId": "Crack",
      "suggestedCategory": "Crack",
      "severity": 3,
      "comment": "Long crack near leading edge",
      "color": "#eb5757",
      "area": 118.4,
      "distance": 21.7,
      "width": 12.6,
      "height": 9.1,
      "isAI": true,
      "aiAppId": "a3f21c40-9d17-4b8e-b2c1-77e0a94d3f12",
      "createdAt": 1745884213411,
      "updatedAt": 1745970613002
    },
    {
      "id": "b18e4a97-6d2c-4f83-a0b5-91cd7e4f2a63",
      "libraryItemId": "MTc0NTg4NDIwMTAwMCM4N2UyZjllOS03Mjk2LTQ1NDktYThkMy1lMjA0OWUxN2E3MWU",
      "labelGroupId": "a3f21c40-9d17-4b8e-b2c1-77e0a94d3f12#1745884213000",
      "folderId": "MTc0NTg4NDIwMDAwMCNiZGQ5NDM2YS0zZmQ0LTQ0YjQtOGZjYS03M2FmNmJlM2EyNDU",
      "shapeType": "RECTANGLE",
      "shape": { "x": 320.5, "y": 210.25, "width": 84, "height": 56.75 },
      "category": "Leading edge erosion",
      "classId": "Leading edge erosion",
      "severity": 2,
      "color": "#f2994a",
      "isAI": true,
      "aiAppId": "a3f21c40-9d17-4b8e-b2c1-77e0a94d3f12",
      "createdAt": 1745884213498,
      "updatedAt": 1745884213498
    }
  ],
  []
]

---

Get Annotation

GET /v1/library/annotation/{libraryItemId}/{labelGroupId}/{labelId}

GET Try it →

Returns a single Annotation with decoded shape geometry. Each path segment must be URL-encoded: a labelGroupId normally contains a #, which otherwise truncates the request at the fragment marker.

Path Parameters

Parameter	Type	Description
libraryItemId	String	Media Drive item ID
labelGroupId	String	Annotation set ID, as returned on the annotation
labelId	String	Annotation ID, the id field of the annotation

Example Request

GET /v1/library/annotation/MTc0NTg4NDIwMTAwMCM4N2UyZjllOS03Mjk2LTQ1NDktYThkMy1lMjA0OWUxN2E3MWU/a3f21c40-9d17-4b8e-b2c1-77e0a94d3f12%231745884213000/7c3f5d81-2b64-4e0a-9f1d-3a8e5c2d7b40

Example Response

{
  "id": "7c3f5d81-2b64-4e0a-9f1d-3a8e5c2d7b40",
  "libraryItemId": "MTc0NTg4NDIwMTAwMCM4N2UyZjllOS03Mjk2LTQ1NDktYThkMy1lMjA0OWUxN2E3MWU",
  "labelGroupId": "a3f21c40-9d17-4b8e-b2c1-77e0a94d3f12#1745884213000",
  "folderId": "MTc0NTg4NDIwMDAwMCNiZGQ5NDM2YS0zZmQ0LTQ0YjQtOGZjYS03M2FmNmJlM2EyNDU",
  "shapeType": "POLYGON",
  "shape": {
    "vertices": [
      { "x": 812.31, "y": 466.02 },
      { "x": 908.77, "y": 470.55 },
      { "x": 901.4, "y": 540.18 },
      { "x": 806.12, "y": 534.9 }
    ]
  },
  "category": "Crack",
  "classId": "Crack",
  "severity": 3,
  "comment": "Long crack near leading edge",
  "color": "#eb5757",
  "area": 118.4,
  "distance": 21.7,
  "isAI": true,
  "aiAppId": "a3f21c40-9d17-4b8e-b2c1-77e0a94d3f12",
  "createdAt": 1745884213411,
  "updatedAt": 1745970613002
}

Error Responses

Status	Meaning
404	No annotation matches the given libraryItemId / labelGroupId / labelId.

---

List Annotation Sets

POST /v1/annotation/set/{id}

POST Try it →

Returns a paginated list of Annotation Set objects for one AI App or one project. Ordering is not guaranteed.

Path Parameters

Parameter	Type	Description
id	String	AI App (add-on) ID when type is ai-app, or project ID when type is project

Request Body

Parameter	Type	Description
type	String	Required. ai-app or project. Determines how id is resolved
libraryItemIds	String[]	Optional scope filter. Applied only when type is ai-app
limit	String	Maximum number of sets per page
nextToken	String	Pagination token from a previous response

libraryItemIds matches by folder, not by file: a folder ID matches its whole subtree, and a file ID matches every set anchored in that file’s folder.

Example Request

{
  "type": "ai-app",
  "libraryItemIds": [
    "MTc0NTg4NDIwMDAwMCNiZGQ5NDM2YS0zZmQ0LTQ0YjQtOGZjYS03M2FmNmJlM2EyNDU"
  ],
  "limit": "50"
}

Example Response

{
  "items": [
    {
      "id": "a3f21c40-9d17-4b8e-b2c1-77e0a94d3f12#1745884213000",
      "name": "Blade defect detection",
      "annotationCount": 42,
      "classes": [
        { "id": "4e1d9a06-3f52-4b78-8c14-6ad02e9b7f31", "name": "Crack" },
        { "id": "9b7c2f48-51a3-4d6e-b092-c8e14a7d305f", "name": "Leading edge erosion" }
      ],
      "createdAt": 1745884213000,
      "updatedAt": 1745970613000
    },
    {
      "id": "a3f21c40-9d17-4b8e-b2c1-77e0a94d3f12#root",
      "name": "Manual review",
      "annotationCount": 7,
      "classes": [],
      "createdAt": 1745712000000,
      "updatedAt": 1745798400000
    }
  ]
}

Error Responses

Status	Meaning
422	type is missing or not one of ai-app / project.
404	A supplied libraryItemIds entry does not exist.

---

List Annotation Summary Rows

POST /v1/library/annotation/summary

POST Try it →

Returns a paginated list of Annotation Summary Row objects: one row per annotation, joined with the Media Drive item it belongs to. Rows do not include shape or bbox.

Request Body

Parameter	Type	Description
libraryItemIdArr	String[]	Required. Media Drive item IDs to summarise. Duplicates are ignored
limit	Integer	Maximum number of source items per page. Defaults to 500, capped at 1000
nextToken	String	Pagination token from a previous response

Example Request

{
  "libraryItemIdArr": [
    "MTc0NTg4NDIwMTAwMCM4N2UyZjllOS03Mjk2LTQ1NDktYThkMy1lMjA0OWUxN2E3MWU",
    "MTc0NTg4NDIwMjAwMCMyNWJhYTA3Ny02YTRlLTQyNjQtYjg0Ni04ZjM0ZmJiMmFiYWE"
  ],
  "limit": 500
}

Example Response

{
  "items": [
    {
      "libraryItemId": "MTc0NTg4NDIwMTAwMCM4N2UyZjllOS03Mjk2LTQ1NDktYThkMy1lMjA0OWUxN2E3MWU",
      "fileName": "DJI_0661.JPG",
      "breadcrumbs": "Wind Farm Alpha/T01/Blade A",
      "tags": "aiResultsNum:2",
      "isApproved": true,
      "addonId": "a3f21c40-9d17-4b8e-b2c1-77e0a94d3f12",
      "labelGroupId": "a3f21c40-9d17-4b8e-b2c1-77e0a94d3f12#1745884213000",
      "annotation": {
        "id": "7c3f5d81-2b64-4e0a-9f1d-3a8e5c2d7b40",
        "name": "Crack",
        "color": "#eb5757",
        "isAI": true,
        "area": 118.4,
        "distance": 21.7,
        "severity": 3,
        "comment": "Long crack near leading edge"
      }
    }
  ],
  "nextToken": "eyJpdGVtSW5kZXgiOjEsImxhc3RLZXkiOm51bGx9"
}

Pagination

limit counts source items, not rows. A response that contains a nextToken string has a further page: pass the token to the next request, together with the same libraryItemIdArr. A response with no nextToken is the last page.

---

Reference

Annotation

Responses may include additional fields that are not part of the API contract.

Field	Type	Description
id	String	Annotation ID, unique within the annotation set
libraryItemId	String	Media Drive item the annotation belongs to
labelGroupId	String	Annotation set ID. Matches id on the Annotation Set
folderId	String	Media Drive folder containing the item
shapeType	String	POINT, RECTANGLE, or POLYGON
shape	Object	Geometry, see Annotation Shape
bbox	Number[]	Bounding box as [x, y, width, height] in pixels. Optional
category	String	Defect or object class, for example Crack
classId	String	Label class the category resolves to
suggestedCategory	String	Category inferred by the model, retained after category is edited
severity	Integer	1 to 5, where 5 is most severe
comment	String	Free-text note
color	String	Display colour as a CSS colour string
area	Number	Defect area in cm²
distance	Number	Distance from the hub in metres
width	Number	Real-world width in cm
height	Number	Real-world height in cm
isAI	Boolean	Whether the annotation was produced by a model
aiAppId	String	AI App (add-on) that produced it. Absent for hand-drawn annotations
frameId	Integer	Frame number, for annotations on video
frameTimestamp	Number	Frame offset in seconds, for annotations on video
thermal	Object	min, max and avg readings in °C, for radiometric images
createdAt	Integer	UNIX timestamp in ms
updatedAt	Integer	UNIX timestamp in ms

Annotation Shape

Coordinates are source-image pixels with the origin at the top-left corner, rounded to two decimal places. They are not normalised and not geographic. The variant is determined by shapeType.

To draw an overlay, scale each axis by the ratio of the rendered size to the source size. Take the source dimensions from the Media Drive item’s metadata.width and metadata.height:

const scaleX = renderedWidth / item.metadata.width;
const scaleY = renderedHeight / item.metadata.height;
// point:     [shape.x * scaleX, shape.y * scaleY]
// rectangle: also scale shape.width by scaleX and shape.height by scaleY

shapeType	shape fields
POINT	x, y, and optional angle in degrees
RECTANGLE	x, y (top-left corner), width, height
POLYGON	vertices, an ordered array of { x, y }. The ring is closed implicitly

Annotation Set

Field	Type	Description
id	String	Annotation set ID. Appears as labelGroupId on its annotations
name	String	Display name of the set
classes	Object[]	Label classes used by the set, as { id, name }
annotationCount	Integer	Number of annotations in the set
createdAt	Integer	UNIX timestamp in ms
updatedAt	Integer	UNIX timestamp in ms

Annotation Summary Row

Field	Type	Description
libraryItemId	String	Media Drive item the annotation belongs to
fileName	String	Name of the file
breadcrumbs	String	Folder path of the item
tags	String	Tags on the Media Drive item
isApproved	Boolean	Whether the item has been reviewed and approved
addonId	String	AI App that produced the annotation. Empty string for hand-drawn annotations
labelGroupId	String	Annotation set ID
annotation	Object	id, name (the category), color, isAI, and any of severity, comment, area, distance, width, height, frameId, frameTimestamp that are set

Error

Returned for every non-2xx response.

Field	Type	Description
message	String	Human-readable error message
name	String	Error class name, for example ItemNotFoundException (404) or MissingParamsError (422)