Registry service#

The sole registry wire surface (the legacy v1 RegistryService has been removed). The read endpoints (GetImage / DeleteImage / SearchImages) delegate to shared RegistryService Java service methods — only CreateImage has a v2-specific service path (different OCI key, different DB fields). See file-level comment.

OpenAPI file: nominal.registry.v2.json

Endpoints#

Get image#

GET /registry/v2/images/{rid}

Get the current state of a container image.

Path parameters

rid string required

Query parameters

workspaceRid string required

Response

image ContainerImage

Fields of ContainerImage

rid string

tag string

User-supplied tag, unique within (workspace, extractor).

sizeBytes string (int64)

Size of the stored image in bytes once the image reaches READY.

status ContainerImageStatus

Current lifecycle status (PENDING while pushing, READY after a successful push, FAILED otherwise).

Values of ContainerImageStatus

CONTAINER_IMAGE_STATUS_UNSPECIFIED
CONTAINER_IMAGE_STATUS_PENDING
CONTAINER_IMAGE_STATUS_READY
CONTAINER_IMAGE_STATUS_FAILED

createdAt string (date-time)

When the image record was created.

extractorRid string

The containerized extractor this image is built for.

inputs array of FileExtractionInput

The input files this extractor requires, mapped to environment variables that store the path to each file.

Fields of FileExtractionInput

environmentVariable string

The environment variable that stores the path to the input file.

name string

Name of the input file which users will be prompted with.

description string

Description of the input file which users will be prompted with.

fileFilters array of FileFilter

Optionally filter files for file selection.

Fields of FileFilter

suffix FileSuffix

Fields of FileSuffix

suffix string

required boolean

Whether the input file is required for the extractor to run.

parameters array of FileExtractionParameter

Parameters the extractor accepts.

Fields of FileExtractionParameter

environmentVariable string: The environment variable that stores the argument.
name string: Name of the parameter which users will be prompted with.
description string: Description of the parameter which users will be prompted with.
required boolean: Whether the parameter is required for the extractor to run.

fileOutputFormat FileOutputFormat

Format of the output file produced by the extractor.

Values of FileOutputFormat

FILE_OUTPUT_FORMAT_UNSPECIFIED
FILE_OUTPUT_FORMAT_PARQUET
FILE_OUTPUT_FORMAT_CSV
FILE_OUTPUT_FORMAT_PARQUET_TAR
FILE_OUTPUT_FORMAT_AVRO_STREAM
FILE_OUTPUT_FORMAT_JSON_L
FILE_OUTPUT_FORMAT_MANIFEST

defaultTimestampMetadata TimestampMetadata

Metadata about the intermediate parquet this extractor will produce. If not set, timestamp metadata must be provided at ingest time.

Fields of TimestampMetadata

seriesName string

Name of the series within the output whose values are used as the row timestamp.

timestampType TimestampType

How the values in series_name should be interpreted as timestamps.

Fields of TimestampType

one of relative, absolute

relative

relative RelativeTimestamp

Fields of RelativeTimestamp

timeUnit string: Unit in which relative offsets are expressed. Aliases the classic REST TimeUnit alias.
offset string (date-time): Starting timestamp to use when indexing the file.

absolute

absolute AbsoluteTimestamp

Fields of AbsoluteTimestamp

one of iso8601, epochOfTimeUnit, customFormat

iso8601

iso8601 Iso8601Timestamp

epochOfTimeUnit

epochOfTimeUnit EpochTimestamp

Fields of EpochTimestamp

timeUnit string: Unit in which epoch values are expressed (e.g. SECONDS, MILLISECONDS).

customFormat

customFormat CustomTimestamp

Fields of CustomTimestamp

format string: The format string should be in the format of the DateTimeFormatter class in Java.
defaultYear integer: Default year is accepted as an optional field for cases like IRIG time format. Will be overridden by year in time format.
defaultDayOfYear integer: Default day of year is accepted as an optional field for cases like IRIG time format. Will be overridden by day of year in time format. From 1 to 366.

exitCodeMappings array of ExitCodeMapping

Fallback exit-code-to-error mappings for extractors that cannot emit a structured /dev/termination-log document.

Fields of ExitCodeMapping

exitCode integer: The container process exit code this mapping applies to.
code string: Machine-readable error code. Extractor-defined codes must fall outside the reserved platform namespace.
message string: Human-readable error message.
retryable boolean: Whether the platform may retry the ingest for this failure.

resources ContainerResources

Compute resources this image’s extractor container runs with. Unset fields fall back to the deployment-wide defaults.

Fields of ContainerResources

cpuCores integer (int64): CPU cores requested for the container. From 1 to 32.
memoryGib integer (int64): Memory in GiB, applied as both the request and the limit. From 1 to 128.
diskGib integer (int64): Size in GiB of each of the ephemeral input and output volumes. From 1 to 512.

Request

curl

curl "https://api.gov.nominal.io/api/registry/v2/images/<rid>?workspaceRid=<workspace rid>" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/registry/v2/images/<rid>?workspaceRid=<workspace rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/registry/v2/images/<rid>?workspaceRid=<workspace rid>",
    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/registry/v2/images/<rid>?workspaceRid=<workspace rid>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "image": {
    "rid": "<rid>",
    "tag": "<tag>",
    "sizeBytes": "1",
    "status": "CONTAINER_IMAGE_STATUS_PENDING",
    "createdAt": "2026-01-01T00:00:00Z",
    "extractorRid": "<extractor rid>",
    "inputs": [
      {
        "environmentVariable": "<environment variable>",
        "name": "<name>",
        "description": "<description>",
        "fileFilters": [
          {
            "suffix": {
              "suffix": "<suffix>"
            }
          }
        ],
        "required": true
      }
    ],
    "parameters": [
      {
        "environmentVariable": "<environment variable>",
        "name": "<name>",
        "description": "<description>",
        "required": true
      }
    ],
    "fileOutputFormat": "FILE_OUTPUT_FORMAT_PARQUET",
    "defaultTimestampMetadata": {
      "seriesName": "<series name>",
      "timestampType": {
        "relative": {
          "timeUnit": "<time unit>",
          "offset": "2026-01-01T00:00:00Z"
        }
      }
    },
    "exitCodeMappings": [
      {
        "exitCode": 1,
        "code": "<code>",
        "message": "<message>",
        "retryable": true
      }
    ],
    "resources": {
      "cpuCores": 1,
      "memoryGib": 1,
      "diskGib": 1
    }
  }
}

Delete image#

DELETE /registry/v2/images/{rid}

Delete a container image. Fails if any containerized extractor references it.

Path parameters

rid string required

Query parameters

workspaceRid string required

Response

An empty JSON object, {}.

Request

curl

curl -X DELETE "https://api.gov.nominal.io/api/registry/v2/images/<rid>?workspaceRid=<workspace rid>" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.delete(
    "https://api.gov.nominal.io/api/registry/v2/images/<rid>?workspaceRid=<workspace rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.delete(
    "https://api.gov.nominal.io/api/registry/v2/images/<rid>?workspaceRid=<workspace rid>",
    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.delete(
            "https://api.gov.nominal.io/api/registry/v2/images/<rid>?workspaceRid=<workspace rid>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{}

Types#

AbsoluteTimestamp#

Absolute timestamp parser variants.

Set exactly one of the fields below.

one of iso8601, epochOfTimeUnit, customFormat required

iso8601

iso8601 Iso8601Timestamp

epochOfTimeUnit

epochOfTimeUnit EpochTimestamp

customFormat

customFormat CustomTimestamp

AndFilter#

clauses array of SearchFilter

ContainerImage#

Container image registered through the V2 (extractor-linked) registry flow. V2 images carry no user-supplied name — extractor identity replaces it as the stable handle.

rid string required
tag string: User-supplied tag, unique within (workspace, extractor).
sizeBytes string (int64): Size of the stored image in bytes once the image reaches READY.
status ContainerImageStatus: Current lifecycle status (PENDING while pushing, READY after a successful push, FAILED otherwise).
createdAt string (date-time): When the image record was created.
extractorRid string: The containerized extractor this image is built for.
inputs array of FileExtractionInput: The input files this extractor requires, mapped to environment variables that store the path to each file.
parameters array of FileExtractionParameter: Parameters the extractor accepts.
fileOutputFormat FileOutputFormat: Format of the output file produced by the extractor.
defaultTimestampMetadata TimestampMetadata: Metadata about the intermediate parquet this extractor will produce. If not set, timestamp metadata must be provided at ingest time.
exitCodeMappings array of ExitCodeMapping: Fallback exit-code-to-error mappings for extractors that cannot emit a structured /dev/termination-log document.
resources ContainerResources: Compute resources this image’s extractor container runs with. Unset fields fall back to the deployment-wide defaults.

ContainerImageStatus#

CONTAINER_IMAGE_STATUS_UNSPECIFIED
CONTAINER_IMAGE_STATUS_PENDING
CONTAINER_IMAGE_STATUS_READY
CONTAINER_IMAGE_STATUS_FAILED

ContainerResources#

Compute resources granted to the container this image runs. Every field is optional; an unset field falls back to the deployment-wide default configured on combined-service. The upper bounds are a platform ceiling, not a guarantee the cluster can satisfy the request — an unschedulable pod fails the ingest with EXTRACTOR_UNSCHEDULABLE. RegistryService re-checks them server-side, because the first-party catalog flow calls CreateImage in-process and never reaches protovalidate.

cpuCores integer (int64): CPU cores requested for the container. From 1 to 32.
memoryGib integer (int64): Memory in GiB, applied as both the request and the limit. From 1 to 128.
diskGib integer (int64): Size in GiB of each of the ephemeral input and output volumes. From 1 to 512.

CustomTimestamp#

Absolute timestamps parsed with a user-supplied format string.

format string: The format string should be in the format of the DateTimeFormatter class in Java.
defaultYear integer: Default year is accepted as an optional field for cases like IRIG time format. Will be overridden by year in time format.
defaultDayOfYear integer: Default day of year is accepted as an optional field for cases like IRIG time format. Will be overridden by day of year in time format. From 1 to 366.

EpochTimestamp#

Absolute timestamps expressed as an integer count of some time unit since the Unix epoch.

timeUnit string: Unit in which epoch values are expressed (e.g. SECONDS, MILLISECONDS).

ExitCodeMapping#

Maps a container exit code to a structured error, for extractors that cannot emit a structured /dev/termination-log document. Applied as a fallback error tier at ingest time.

exitCode integer: The container process exit code this mapping applies to.
code string required: Machine-readable error code. Extractor-defined codes must fall outside the reserved platform namespace.
message string required: Human-readable error message.
retryable boolean: Whether the platform may retry the ingest for this failure.

ExtractorFilter#

Selects images registered against a specific containerized extractor. Combine with a TagFilter (via AndFilter) to fetch a single (extractor, tag) image.

extractorRid string required

FileExtractionInput#

Defines an input file to be provided to the extractor.

environmentVariable string required: The environment variable that stores the path to the input file.
name string required: Name of the input file which users will be prompted with.
description string: Description of the input file which users will be prompted with.
fileFilters array of FileFilter: Optionally filter files for file selection.
required boolean: Whether the input file is required for the extractor to run.

FileExtractionParameter#

Defines an input parameter to be provided to the extractor.

environmentVariable string required: The environment variable that stores the argument.
name string required: Name of the parameter which users will be prompted with.
description string: Description of the parameter which users will be prompted with.
required boolean: Whether the parameter is required for the extractor to run.

FileFilter#

Optional filter applied during file selection for a file input.

suffix FileSuffix

FileOutputFormat#

Output file format emitted by the extractor. Currently PARQUET, CSV, and PARQUET_TAR are the primary supported formats.

FILE_OUTPUT_FORMAT_UNSPECIFIED
FILE_OUTPUT_FORMAT_PARQUET
FILE_OUTPUT_FORMAT_CSV
FILE_OUTPUT_FORMAT_PARQUET_TAR
FILE_OUTPUT_FORMAT_AVRO_STREAM
FILE_OUTPUT_FORMAT_JSON_L
FILE_OUTPUT_FORMAT_MANIFEST

FileSuffix#

The expected suffix of the file. For example, “parquet”, “json”, “csv”, etc.

suffix string required

Iso8601Timestamp#

Absolute timestamps serialized in ISO-8601 form. No additional parser configuration is needed.

An empty JSON object, {}.

RelativeTimestamp#

Relative timestamp parser: interprets each row’s timestamp as an offset from a fixed origin.

timeUnit string: Unit in which relative offsets are expressed. Aliases the classic REST TimeUnit alias.
offset string (date-time): Starting timestamp to use when indexing the file.

StatusFilter#

status ContainerImageStatus required

TagFilter#

V2 search filter types. V2 deliberately omits NameFilter (v2 images have no user-supplied name) in favour of ExtractorFilter, which selects images by the containerized extractor they belong to.

tag string required

TimestampMetadata#

Describes how to derive a row timestamp from the extracted output.

seriesName string required: Name of the series within the output whose values are used as the row timestamp.
timestampType TimestampType required: How the values in series_name should be interpreted as timestamps.

TimestampType#

Selects between relative-offset and absolute-timestamp parsing strategies.