Media Drive

Media Drive is a GraphQL-based API for managing files, folders, and media assets. It supports queries (read operations) and mutations (create, update, delete operations).

Operation Type	Description
Query	Retrieve or list existing media items
Mutation	Create, update, move, rename, or delete items

Prerequisites

Node.js v19 or later
A valid account on cloud.unleashlive.com

For a full working sample project, see the Media Drive samples on GitHub.

Endpoint

All GraphQL operations are sent as POST requests to:

https://mediadrive-api.unleashlive.com/graphql

Authentication

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

Authorization: Bearer <YOUR_PAT>

Schema Types

Media Drive Item

The primary resource returned by queries and mutations.

Field	Type	Description
`id`	String`!`	Item ID
`teamId`	String`!`	Team the resource belongs to
`parentId`	String`!`	Parent item ID, typically a folder ID
`tags`	String	Tags assigned to the item
`type`	String	Item type (see Item Type values)
`location`	String	Hierarchy path where the item is placed, separated by `#`
`deviceId`	String	ID of the device used to create the item (if any)
`name`	String	Name of the item
`createdAt`	AWSTimestamp`!`	UTC timestamp of item creation
`updatedAt`	AWSTimestamp	UTC timestamp of last update
`uploadedAt`	AWSTimestamp	UTC timestamp of when upload completed
`ownerId`	String`!`	ID of the author/owner
`s3Path`	String	Storage path of the file associated with the item
`metadata`	Object	File metadata (see Metadata)
`mimeType`	String`!`	MIME type (see Custom MimeTypes)
`annotations`	AWSJSON	JSON annotations (see Annotations)
`isApproved`	Boolean	Whether the item has been reviewed/approved

Fields marked with ! are required.

Item Type

Key	Description
`I`	Image
`V`	Video
`M`	Model
`R`	Report
`FL`	Flight log
`D`	General document
`U`	Undefined type

Metadata

Field	Type	Description
`size`	Long	File size in bytes
`childItemsNumber`	Int	Number of child items
`addonId`	String	Add-on identifier
`deviceId`	String	Device identifier
`droneSerialNumber`	String	Drone serial number
`pilotId`	String	Pilot identifier
`pilotName`	String	Pilot name
`annotationCount`	Int	Number of annotations
`make`	String	Camera make
`model`	String	Camera model
`orientation`	Int	Image orientation
`software`	String	Software used
`camaperturevalue`	Float	Camera aperture value
`camfnumber`	Float	Camera f-number
`camfocallength`	Float	Camera focal length
`camfocallengthin35mmformat`	Int	Focal length in 35 mm equivalent
`camiso`	Int	Camera ISO
`camShutterSpeed`	String	Camera shutter speed
`camExposureBiasValue`	Float	Exposure bias value
`digitalZoom`	Float	Digital zoom level
`gpsalt`	Float	GPS altitude
`gpsaltref`	Int	GPS altitude reference
`gpslat`	Float	GPS latitude
`gpslatref`	String	GPS latitude reference (N/S)
`gpslng`	Float	GPS longitude
`gpslngref`	String	GPS longitude reference (E/W)
`baseAltitude`	Float	Base altitude
`exifimagewidth`	Int	EXIF image width
`exifimageheight`	Int	EXIF image height
`gimbalpitchdegree`	Float	Gimbal pitch degree
`gimbalyawdegree`	Float	Gimbal yaw degree
`gimbalrolldegree`	Float	Gimbal roll degree
`isAutofly`	Boolean	Whether captured via Autofly
`automationid`	String	Automation identifier
`createdate`	AWSTimestamp	File creation date
`modifydate`	AWSTimestamp	File modification date
`lastmodified`	AWSTimestamp	Last modified timestamp
`type`	String	File type
`width`	Int	Width in pixels
`height`	Int	Height in pixels
`bounds`	[[Float]]	Geo-bounds array of `[lat, lng]` pairs
`is360`	Boolean	Whether the media is 360°
`duration`	Float	Duration in seconds (video)
`isPanoramic`	Boolean	Whether the media is panoramic
`thermalData`	Object	Thermal imaging data (see Thermal Data)
`additionalProperties`	String	Additional custom properties (JSON)

Thermal Data

Field	Type	Description
`isThermal`	Boolean	Whether the file is thermal
`hasRadiometricData`	Boolean	Whether radiometric data exists
`minTemperature`	Float	Minimum temperature detected
`maxTemperature`	Float	Maximum temperature detected
`calibration`	Object	Calibration settings (see Thermal Calibration)
`tmapS3Path`	String	S3 path to the thermal map

Thermal Calibration

Field	Type	Description
`emissivity`	Float	Emissivity value
`reflectedTemperature`	Float	Reflected temperature
`atmosphericTemperature`	Float	Atmospheric temperature
`humidity`	Float	Humidity
`distance`	Float	Distance to subject
`transmissivity`	Float	Transmissivity value

Custom MimeTypes

Value	Description
`application/vnd.unleashlive.folder`	Folder
`application/vnd.unleashlive.folderAggregateArchive`	Aggregate archive folder
`application/vnd.unleashlive.folderAggregateResults`	Aggregate results folder
`application/vnd.unleashlive.model`	Model wrapper
`application/vnd.unleashlive.model.2d`	2D model
`application/vnd.unleashlive.model.3d`	3D model
`application/vnd.unleashlive.model.vr`	VR model
`application/vnd.unleashlive.model.pc`	Point Cloud model

Annotations Object

The annotations field is a stringified JSON object keyed by add-on ID.

Key	Value
`{addonId}`	Annotation object (see below)

Annotation

Field	Type	Description
`addonId`	String	`required` Add-on identifier
`labels`	Object	Label annotations (see Image Labels)
`sessionInfo`	Object	Session information (see Session Info)

Image Labels

A map of label objects keyed by label ID.

Key	Value
`{id}`	Label object (see below)

Label

Field	Type	Description
`shapeType`	String	`required` Shape type: `POLYGON`, `RECTANGLE`, or `POINT`
`category`	String	`required` Label category
`severity`	Number	Severity level
`comment`	String	Comment text
`color`	String	Display colour
`updatedAt`	Timestamp	`required` Last updated timestamp
`bbox`	Number[]	Bounding box coordinates
`area`	Number	Labelled area
`distance`	Number	Distance measurement
`isAI`	Boolean	Whether generated by AI
`isAccepted`	Boolean	Whether accepted by a reviewer
`isModified`	Boolean	Whether modified after creation

Session Info

Field	Type	Description
`title`	String	Display title
`value`	String or String[]	`required` Session value
`order`	String	Display order
`placeholder`	String	Placeholder text

Queries

Item references below use the LibraryUpdateInput input type, defined as:

input LibraryUpdateInput {
  id: String!
}

The inline-object syntax shown in the examples ({ id: "<ITEM_ID>" }) is equivalent to passing a LibraryUpdateInput value. Use the named type when parameterizing queries or mutations with GraphQL variables.

Get Item

Fetch a single media item by its ID.

query GetLibraryItem {
  get(item: { id: "<ITEM_ID>" }) {
    id
    teamId
    location
    type
    tags
    createdAt
    deviceId
    name
    parentId
    s3Path
    updatedAt
    mimeType
    annotations
    metadata {
      size
      childItemsNumber
      make
      model
      width
      height
      gpslat
      gpslng
      isPanoramic
      duration
    }
  }
}

Input Parameters

Parameter	Type	Description
`item`	`LibraryUpdateInput!`	`required` Reference to the item

Example Response

{
  "data": {
    "get": {
      "id": "ItemId1",
      "teamId": "teamId1",
      "location": "teamId1",
      "type": "F",
      "tags": "aiResultsNum:1",
      "createdAt": 1678802206809,
      "deviceId": null,
      "name": "Sample folder",
      "parentId": "teamId1",
      "s3Path": "12345/78910.mp4",
      "updatedAt": 1678976523362,
      "mimeType": "application/vnd.unleashlive.folder",
      "annotations": null,
      "metadata": {
        "size": 0,
        "childItemsNumber": 13,
        "make": null,
        "model": null,
        "width": null,
        "height": null,
        "gpslat": null,
        "gpslng": null,
        "isPanoramic": null,
        "duration": null
      }
    }
  }
}

For a full working example, see get.js.

List Items

Fetch all child items of a known parent folder. The location parameter is the hierarchy path of the parent, constructed by joining the parent’s location and id with /.

query list {
  list(sort: desc, location: "<TEAM_ID>/<FOLDER_ID>", limit: 48) {
    items {
      teamId
      location
      type
      tags
      createdAt
      deviceId
      id
      name
      parentId
      s3Path
      updatedAt
      mimeType
      metadata {
        isPanoramic
        duration
      }
    }
    nextToken {
      pk
      sk
      locationCreatedAt
      teamId
      teamIdType
      createdAt
      searchNameCreatedAt
      searchName
      deviceId
      type
    }
  }
}

Input Parameters

Parameter	Type	Description
`location`	String	Hierarchy path of the parent (e.g. `teamId1/folderId1`)
`parentId`	String	Filter by parent folder ID
`deviceId`	String	Filter by device ID
`name`	String	Filter by item name
`tags`	String	Filter by tags
`type`	String	Filter by item type (e.g. `I`, `V`, `M`)
`dateFrom`	String	Return items created at or after this date
`dateTo`	String	Return items created at or before this date
`sort`	Enum	Sort order: `asc` or `desc`
`limit`	Int	Maximum number of items to return
`nextToken`	LastEvaluatedKeyInput	Pagination token from a previous response

Pagination

If there are more items than the specified limit, the response includes a nextToken object. Pass this token to the next request to fetch the following page.

Example Response

{
  "data": {
    "list": {
      "items": [
        {
          "teamId": "teamId1",
          "location": "teamId1/folderId1",
          "type": "D",
          "tags": null,
          "createdAt": 1678976522491,
          "deviceId": "deviceId1",
          "id": "1",
          "name": "testDocument.json",
          "parentId": "folderId1",
          "s3Path": "1234/2b0d6d59-d221-4dc1-9cf4-78677a002127.json",
          "updatedAt": 1678976539957,
          "mimeType": "application/json",
          "metadata": {
            "isPanoramic": null,
            "duration": null
          }
        },
        {
          "teamId": "teamId1",
          "location": "teamId1/folderId1",
          "type": "V",
          "tags": null,
          "createdAt": 1678976459317,
          "deviceId": "deviceId1",
          "id": "2",
          "name": "testClip.mp4",
          "parentId": "folderId1",
          "s3Path": "1234/2453702b-8764-4f55-bd81-487f58ec556a.mp4",
          "updatedAt": 1678976491797,
          "mimeType": "video/mp4",
          "metadata": {
            "isPanoramic": null,
            "duration": 1202.003
          }
        }
      ],
      "nextToken": null
    }
  }
}

For a full working example, see list.js.

Mutations

Move Items

Move one or more items (including all sub-items) to a new parent folder.

mutation MoveItems {
  move(
    moveItems: [{ id: "<ITEM_ID>" }]
    to: { id: "<DESTINATION_FOLDER_ID>" }
  ) {
    id
    parentId
    location
  }
}

Input Parameters

Parameter	Type	Description
`moveItems`	`[LibraryUpdateInput!]`	`required` Array of item references to move
`to`	`LibraryUpdateInput!`	`required` Destination folder reference

Example Response

{
  "data": {
    "move": [
      {
        "id": "itemId1",
        "parentId": "itemId11",
        "location": "teamId1/itemId11"
      }
    ]
  }
}

For a full working example, see move.js.

Rename Item

Rename a single media item.

mutation RenameItems {
  rename(item: { id: "<ITEM_ID>" }, newName: "New name") {
    id
  }
}

Input Parameters

Parameter	Type	Description
`item`	`LibraryUpdateInput!`	`required` Reference to the item
`newName`	`String!`	`required` The new name for the item

Example Response

{
  "data": {
    "rename": {
      "id": "itemId1"
    }
  }
}

For a full working example, see rename.js.

Delete Items

Delete one or more items, including all sub-items.

mutation DeleteItems {
  delete(deleteItems: [{ id: "<ITEM_ID_1>" }, { id: "<ITEM_ID_2>" }]) {
    deleteItems {
      id
    }
    ownerId
  }
}

Input Parameters

Parameter	Type	Description
`deleteItems`	`[LibraryUpdateInput!]`	`required` Array of item references to delete

Example Response

{
  "data": {
    "delete": {
      "deleteItems": [{ "id": "itemId1" }, { "id": "itemId2" }],
      "ownerId": "userId1"
    }
  }
}

For a full working example, see delete.js.

File Operations

Upload

File uploads use the AWS S3 SDK directly, not the GraphQL endpoint. The file is uploaded to the S3 upload bucket with metadata that links it to a Media Drive location.

Upload Metadata

Key	Description
`location`	Hierarchy path for the upload (e.g. `teamId1/folderId1`)
`parentId`	Parent folder ID (deprecated — use `location`)
`name`	Display name for the media item
`deviceid`	Device ID to associate with the item

For a full working upload example, see upload.js.

Download

Files are downloaded from the Media Drive CDN using the item’s s3Path.

CDN Base URL

https://library.unleashlive.com

Construct the download URL by appending the s3Path to the CDN base URL:

https://library.unleashlive.com/<s3Path>

Steps

Query or list items to obtain the s3Path of the desired file.
Construct the full URL: https://library.unleashlive.com/{s3Path}.
Perform an HTTPS GET request to download the file.

For a full working download example, see download.js.