Video file service#

The video service manages individual video files and their metadata.

OpenAPI file: VideoFileService.json

Endpoints#

Delete#

DELETE /video-files/v1/video-files/{videoFileRid}

Deprecated: Legacy VideoFile-entity API. Videos are now channels on datasets and their files are Catalog dataset files; delete the file with IngestService#deleteFile.

Permanently deletes a video file and all associated segments from the database. This operation cannot be undone.

Path parameters

videoFileRid string (RID) required

Response

No content (HTTP 204).

Request

curl

curl -X DELETE "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.delete(
    "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()

httpx

import httpx

response = httpx.delete(
    "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.delete(
            "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()


asyncio.run(main())

Response: 204

No content.

Archive#

PUT /video-files/v1/video-files/{videoFileRid}/archive

Deprecated: Archives a video file, which excludes it from search and hides it from being visible in the UI, but does not permanently delete it. Archived video files can be unarchived. This endpoints is deprecated and will be removed on February 1st, 2026. Use delete endpoint instead for permanent removal.

Path parameters

videoFileRid string (RID) required

Response

No content (HTTP 204).

Request

curl

curl -X PUT "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/archive" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.put(
    "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/archive",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()

httpx

import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/archive",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/archive",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()


asyncio.run(main())

Response: 204

No content.

Unarchive#

PUT /video-files/v1/video-files/{videoFileRid}/unarchive

Deprecated: Unarchive a previously archived video file, exposing it to the UI and search. Unarchiving functionality will be removed on February 1st, 2026.

Path parameters

videoFileRid string (RID) required

Response

No content (HTTP 204).

Request

curl

curl -X PUT "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/unarchive" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.put(
    "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/unarchive",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()

httpx

import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/unarchive",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/unarchive",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()


asyncio.run(main())

Response: 204

No content.

Get ingest status#

GET /video-files/v1/video-files/{videoFileRid}/ingest-status

Deprecated: Legacy VideoFile-entity API. Videos are now channels on datasets and their files are Catalog dataset files; ingest status is tracked on the Catalog dataset file (CatalogService#getDatasetFile).

Get the latest ingest status for a given video file by RID.

Path parameters

videoFileRid string (RID) required

Response

ingestStatus VideoFileIngestStatus

success

Set type to "success".

success SuccessIngestStatus

error

Set type to "error".

error IngestError

Fields of IngestError

errorType string
message string
errorInstanceId string

inProgress

Set type to "inProgress".

inProgress Empty

Request

curl

curl "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/ingest-status" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/ingest-status",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/ingest-status",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/ingest-status",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "ingestStatus": {
    "type": "success",
    "success": {}
  }
}

Batch get ingest status#

POST /video-files/v1/videos/batch-get-ingest-status

Get the latest ingest status for a set of given video files by RID.

Body

The body is an array of string (RID).

Response

The body is a map of VideoFileRid to VideoFileIngestStatus.

success

Set type to "success".

success SuccessIngestStatus

error

Set type to "error".

error IngestError

Fields of IngestError

errorType string
message string
errorInstanceId string

inProgress

Set type to "inProgress".

inProgress Empty

Request

curl

curl -X POST "https://api.gov.nominal.io/api/video-files/v1/videos/batch-get-ingest-status" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '[
  "<video file rid>"
]'

requests

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/video-files/v1/videos/batch-get-ingest-status",
    headers={"Authorization": "Bearer <api key>"},
    json=["<video file rid>"],
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/video-files/v1/videos/batch-get-ingest-status",
    headers={"Authorization": "Bearer <api key>"},
    json=["<video file rid>"],
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/video-files/v1/videos/batch-get-ingest-status",
            headers={"Authorization": "Bearer <api key>"},
            json=["<video file rid>"],
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "<key>": {
    "type": "success",
    "success": {}
  }
}

Update ingest status#

PUT /video-files/v1/videos/{videoFileRid}/ingest-status

Deprecated: Legacy VideoFile-entity API. Videos are now channels on datasets and their files are Catalog dataset files; ingest status is tracked on the Catalog dataset file.

Update the latest ingest status for a given video file by RID.

Path parameters

videoFileRid string (RID) required

Body

video string (RID) required

ingestStatus VideoFileIngestStatus required

success

Set type to "success".

success SuccessIngestStatus

error

Set type to "error".

error IngestError

Fields of IngestError

errorType string required
message string required
errorInstanceId string

inProgress

Set type to "inProgress".

inProgress Empty

Response

No content (HTTP 204).

Request

curl

curl -X PUT "https://api.gov.nominal.io/api/video-files/v1/videos/<video file rid>/ingest-status" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "video": "<video rid>",
  "ingestStatus": {
    "type": "success",
    "success": {}
  }
}'

requests

import requests

response = requests.put(
    "https://api.gov.nominal.io/api/video-files/v1/videos/<video file rid>/ingest-status",
    headers={"Authorization": "Bearer <api key>"},
    json={"video": "<video rid>", "ingestStatus": {"type": "success", "success": {}}},
)
response.raise_for_status()

httpx

import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/video-files/v1/videos/<video file rid>/ingest-status",
    headers={"Authorization": "Bearer <api key>"},
    json={"video": "<video rid>", "ingestStatus": {"type": "success", "success": {}}},
)
response.raise_for_status()

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/video-files/v1/videos/<video file rid>/ingest-status",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "video": "<video rid>",
                "ingestStatus": {"type": "success", "success": {}},
            },
        ) as response:
            response.raise_for_status()


asyncio.run(main())

Response: 204

No content.

Get segment summaries#

GET /video-files/v1/video-files/{videoFileRid}/segment-summaries

Returns the min and max absolute and media timestamps for each segment in a video file. To be used during frame-timestamp mapping when playing back videos.

Path parameters

videoFileRid string (RID) required

Response

The body is an array of SegmentSummary.

Fields of SegmentSummary

minAbsoluteTimestamp Timestamp

Fields of Timestamp

seconds integer (int64)
nanos integer (int64)

maxAbsoluteTimestamp Timestamp

minMediaTimestamp number

maxMediaTimestamp number

Request

curl

curl "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/segment-summaries" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/segment-summaries",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/segment-summaries",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/segment-summaries",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

[
  {
    "minAbsoluteTimestamp": {
      "seconds": 1,
      "nanos": 1
    },
    "maxAbsoluteTimestamp": {
      "seconds": 1,
      "nanos": 1
    },
    "minMediaTimestamp": 1,
    "maxMediaTimestamp": 1
  }
]

Get playlist#

GET /video-files/v1/video-files/{videoFileRid}/playlist

Generate an HLS playlist for a video file with the given RID to enable playback. The HLS playlist will contain links to all of the video segments in the video in sequential order.

Path parameters

videoFileRid string (RID) required

Response: application/octet-stream

The body is the raw bytes.

A successful response.

Request

curl

curl "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/playlist" \
  -H "Authorization: Bearer <api key>" \
  --output "<file>"

requests

from pathlib import Path

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/playlist",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
Path("<file>").write_bytes(response.content)

httpx

from pathlib import Path

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/playlist",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
Path("<file>").write_bytes(response.content)

aiohttp

import asyncio
from pathlib import Path

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/video-files/v1/video-files/<video file rid>/playlist",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            Path("<file>").write_bytes(await response.read())


asyncio.run(main())

Response: 200

The raw bytes.

Errors#

Errors shows how these errors are sent.

Each error’s errorName is Video: followed by its name below.

Status	Name	Notes
400	`InvalidFileShiftScaleRequest`	Attempting to shift or scale the timestamps of a video with a timestamp manifest.
400	`InvalidVideoFileBatchUpdateRequest`	Attempting to batch update video files with an invalid request shape.
400	`VideoFileIngestNotComplete`	Attempting to access per-file segment information before video segmentation has finished.
404	`VideoFileNotFound`	Accessing a video file by RID that does not exist or that you do not have permission to access.

Types#

Empty#

An empty JSON object, {}.

Handle#

Set type to the name of one of the other fields, and set only that field.

s3 string

IngestError#

errorType string required
message string required
errorInstanceId string

McapChannelLocator#

Locator for a channel in an mcap file. Channel name is not guaranteed to be unique, so channel ID should be used for mcap files with duplicate channel names.

Set type to the name of one of the other fields, and set only that field.

topic string
id integer

McapTimestampManifest#

Timestamps are derived from the mcap file containing the video frames.

mcapChannelLocator McapChannelLocator required

NoTimestampManifest#

these values will not be updated after ingest time, to allow for resetting. The updated values are stored implicitly through the segment timestamps.

startingTimestamp Timestamp required: Specifies the original starting timestamp of the video.
scaleParameter ScaleParameter: A field that specifies that the frame rate of the video does not match the frame rate of the camera | i.e. a slowed down or sped up video. Can specify either the camera frame rate or the absolute end time.

ScaleParameter#

Set type to the name of one of the other fields, and set only that field.

trueFrameRate number
endingTimestamp Timestamp
scaleFactor number: the scale factor can be used to calculate whether media duration differs from a video’s | real duration, and if so, the true frame rate of the camera. The video time will thus be scaled | by the ratio of the real duration to media duration, or media frame rate to true frame rate.

SegmentSummary#

Bounding timestamps for the frames within a segment. For non-frame-mapped videos, the min and max media timestamps will be empty.

minAbsoluteTimestamp Timestamp required
maxAbsoluteTimestamp Timestamp required
minMediaTimestamp number required
maxMediaTimestamp number required

SuccessIngestStatus#

An empty JSON object, {}.

Timestamp#

Deprecated for new APIs. Use google.protobuf.Timestamp for absolute instants in proto APIs.

This legacy nanosecond precision timestamp type is represented by an epoch time in seconds and a nanosecond offset. The nanosecond offset is from the start of the epoch second, so must be less than 1 billion.

seconds integer (int64) required
nanos integer (int64) required

UpdateVideoFileRequest#

Request to update metadata for a given video file.

title string
description string
startingTimestamp Timestamp
scaleParameter ScaleParameter
segmentedFilesSize integer (int64): The total size of all the post-processed segments corresponding to this video file in bytes.

VideoFile#

Representation of a single user-provided video file.

rid string (RID) required
videoRid string (RID) required
title string required
description string
createdBy string (RID) required
createdAt string (date-time) required
originMetadata VideoFileOriginMetadata required
segmentMetadata VideoFileSegmentsMetadata

VideoFileIngestStatus#

Set type to the name of one of the other fields, and set only that field.

success SuccessIngestStatus
error IngestError
inProgress Empty

VideoFileOriginMetadata#

Metadata about the origin of the video file. This includes the original source of the video file and additional timestamp metadata used to time-sync the video file.

source Handle required
timestampManifest VideoFileTimestampManifest required

VideoFileSegmentsMetadata#

High-level metadata about the segments comprising a video file post-segmentation.

rid string (RID) required
numFrames integer required
numSegments integer required
scaleFactor number required
minAbsoluteTimestamp Timestamp required
maxAbsoluteTimestamp Timestamp required
mediaDurationSeconds number required
mediaFrameRate number required

VideoFileTimestampManifest#

A video file’s timestamp manifest specifies how to determine absolute timestamps for each frame. In an MCAP file, this data is embedded within the source file. Alternatively, the manifest may be provided as an external sidecar file. If no manifest is available, the timestamps are calculated by applying a starting offset to the presentation timestamp of each frame.

Set type to the name of one of the other fields, and set only that field.

mcap McapTimestampManifest
s3path string
s3paths array of string: Multiple sidecar manifest files whose per-frame timestamps are concatenated in list order. Used when a video’s frame timestamps are recorded across several files.
noManifest NoTimestampManifest

VideoFileUpdate#

Metadata update for a single video file in a batch update.

videoFileRid string (RID) required
request UpdateVideoFileRequest required

Page design based on Scalar, MIT License.

Video file service#

Endpoints#

Create#

Get#

Update#

Delete#

Batch get#

List files in video#

List files in video paginated#

Batch update#

Archive#

Unarchive#

Get ingest status#

Batch get ingest status#

Update ingest status#

Get segment summaries#

Get playlist#

Errors#

Types#

Empty#

Handle#

IngestError#

McapChannelLocator#

McapTimestampManifest#

NoTimestampManifest#

ScaleParameter#

SegmentSummary#

SuccessIngestStatus#

Timestamp#

UpdateVideoFileRequest#

VideoFile#

VideoFileIngestStatus#

VideoFileOriginMetadata#

VideoFileSegmentsMetadata#

VideoFileTimestampManifest#

VideoFileUpdate#