---
title: "Create a media row"
method: POST
path: "/media"
tags: ["Media"]
---

# Create a media row

`POST /media`

Creates a mission_media row and returns it along with a short-lived
presigned S3 upload URL the caller uses to PUT the actual object.

## Headers

- `Idempotency-Key` string, uuid

## Request body

- CreateMediaRequest
  - `missionId` string, uuid, required
  - `vehicleId` string, uuid, required
  - `mediaType` 'image' | 'video', required
  - `capturedAt` number, required — Unix-ms timestamp when the media was captured.
  - `sizeBytes` integer, required — Size of the S3 object in bytes (used by the zip endpoint's progress UI).
  - `geoLocation` GeoLocation
    - `lat` number, required
    - `lng` number, required
    - `altitude` number

## Response `201`

Created

- object
  - `data` object, required
    - `id` string, uuid, required
    - `organizationId` string, uuid, required
    - `missionId` string, uuid, required
    - `vehicleId` string, uuid, required — Reference to the vehicle (e.g. drone) that captured this media
    - `siteId` string, uuid
    - `mediaType` 'image' | 'video', required
    - `captureType` 'rgb' | 'thermal', nullable, required — Spectral modality of the frame, served directly from mission_media.capture_type (the single source of truth). null means the modality is unknown (not yet classified); it is never coerced to rgb.
    - `url` string, required — Opaque asset URL
    - `thumbnailUrl` string, required
    - `capturedAt` number, required
    - `captureDevice` string — Camera/sensor used for capture (e.g. "Zenmuse H30T Wide")
    - `orientation` GimbalOrientation
      - `yaw` number, required — Gimbal yaw in degrees
      - `pitch` number, required — Gimbal pitch in degrees
      - `roll` number, required — Gimbal roll in degrees
    - `focalLength` number — Focal length in mm
    - `digitalZoom` number — Digital zoom ratio (1.0 = no zoom)
    - `fov` number — Diagonal field of view in degrees
    - `resolution` Resolution
      - `width` integer, required
      - `height` integer, required
    - `geoLocation` GeoLocation, required
      - `lat` number, required
      - `lng` number, required
      - `altitude` number
    - `duration` number — Video length in seconds
    - `geoPath` GeoPathPoint[] — Video flight path; null for images
      - `timestampSec` number, required
      - `lat` number, required
      - `lng` number, required
      - `altitude` number
    - `deletedAt` number, nullable, required
    - `createdAt` number, required
    - `updatedAt` number, required
    - `commentCount` integer — Count of comments attached to this media row.
    - `thermalRange` object, nullable — Compact Fahrenheit min/max thermal scale for lightbox overlays, derived from mission_media.metadata thermal stats. This is DATA, not a modality classifier (see captureType). null when the frame has no thermal stats, so the overlay simply hides.
      - `minTempF` number, nullable
      - `maxTempF` number, nullable
    - `thermalDisplayRamp` string[], nullable — Measured per-image display ramp: ordered hex color stops (cold->hot, e.g. ["#151515", ..., "#f7f7f7"]) recovered by correlating the frame's temperature grid with its rendered pixels. The client renders these stops directly as the thermal scale-bar gradient (top=hot), so the bar matches the frame's actual pixels for any palette — including Skydio's per-image isotherm overlay, which a palette name cannot describe. This is a DISPLAY fact, distinct from captureType (spectral modality) and thermalRange (temperature data). null when the frame has no measured ramp, so the overlay hides.
    - `uploadUrl` string, required — Presigned PUT URL valid for a short window.
  - `transactionId` string, uuid, required

## Other responses

- `400` — Bad request or validation error
- `401` — Authentication required
- `403` — Insufficient permissions
- `429` — Rate limit exceeded
- `500` — Internal server error

---

[API](https://skmtc.net/voltairlabs/apis/voltair-api.md) · [All operations](https://skmtc.net/voltairlabs/apis/voltair-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voltairlabs/voltair-api/revisions/be08f4f706f5/schema)