# 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`](https://dev.nominal.io/api/_downloads/ff93a6bc483c7c7992031f55fa833724/nominal.registry.v2.json)

## Endpoints

### Create image

POST `/registry/v2/images`

Register a new container image from a previously uploaded tarball and attach it to the referenced containerized extractor. The client should first upload the tarball via the existing UploadService multipart flow, then call this endpoint with the object key to create the image record and start the push. Alternatively, set source_image_rid instead of object_path to register a new (extractor, tag) version that reuses an existing READY image’s stored binary — for metadata-only changes that don’t need a tarball re-upload.

Body

`workspaceRid` string required
:   Workspace that owns the image. Must match the extractor’s workspace.

`tag` string required
:   User-supplied tag (e.g. “latest”, “v1”). Unique within (workspace, extractor).

`objectPath` string
:   Full object-storage path (“s3://bucket/key”) of an uploaded tarball (UploadService multipart flow) in the configured upload bucket; mutually exclusive with source_image_rid.

`extractorRid` string required
:   The containerized extractor this image is built for. Must exist in the same workspace.

`inputs` array of [`FileExtractionInput`](https://dev.nominal.io/api/rest/registry-service.md#fileextractioninput)
:   The input files this extractor requires, mapped to environment variables that store the path to each file. At least one input must be declared. At least 1 item.

    Fields of `FileExtractionInput`

    `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`](https://dev.nominal.io/api/rest/registry-service.md#filefilter)
    :   Optionally filter files for file selection.

        Fields of `FileFilter`

        `suffix` [`FileSuffix`](https://dev.nominal.io/api/rest/registry-service.md#filesuffix)
        :   ​

            Fields of `FileSuffix`

            `suffix` string required
            :   ​

    `required` boolean
    :   Whether the input file is required for the extractor to run.

`parameters` array of [`FileExtractionParameter`](https://dev.nominal.io/api/rest/registry-service.md#fileextractionparameter)
:   Parameters the extractor accepts.

    Fields of `FileExtractionParameter`

    `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.

`fileOutputFormat` [`FileOutputFormat`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#timestampmetadata) required
:   Metadata about the intermediate parquet this extractor will produce. Required so the image carries a complete execution contract: ingest needs timestamp metadata from the image or the request, and an image without a default silently depends on every caller supplying it. Callers may still override it per ingest request.

    Fields of `TimestampMetadata`

    `seriesName` string required
    :   Name of the series within the output whose values are used as the row timestamp.

    `timestampType` [`TimestampType`](https://dev.nominal.io/api/rest/registry-service.md#timestamptype) required
    :   How the values in `series_name` should be interpreted as timestamps.

        Fields of `TimestampType`

        one of `relative`, `absolute` required
        :   ​

            **relative**

            `relative` [`RelativeTimestamp`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#absolutetimestamp)
            :   ​

                Fields of `AbsoluteTimestamp`

                one of `iso8601`, `epochOfTimeUnit`, `customFormat` required
                :   ​

                    **iso8601**

                    `iso8601` [`Iso8601Timestamp`](https://dev.nominal.io/api/rest/registry-service.md#iso8601timestamp)
                    :   ​

                    **epochOfTimeUnit**

                    `epochOfTimeUnit` [`EpochTimestamp`](https://dev.nominal.io/api/rest/registry-service.md#epochtimestamp)
                    :   ​

                        Fields of `EpochTimestamp`

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

                    **customFormat**

                    `customFormat` [`CustomTimestamp`](https://dev.nominal.io/api/rest/registry-service.md#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.

`sourceImageRid` string
:   Existing READY image of the same extractor whose stored binary the new version reuses (no tarball re-upload); mutually exclusive with object_path. At least 1 character.

`exitCodeMappings` array of [`ExitCodeMapping`](https://dev.nominal.io/api/rest/registry-service.md#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 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.

`resources` [`ContainerResources`](https://dev.nominal.io/api/rest/registry-service.md#containerresources)
:   Compute resources the 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.

Response

`image` [`ContainerImage`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#filefilter)
        :   Optionally filter files for file selection.

            Fields of `FileFilter`

            `suffix` [`FileSuffix`](https://dev.nominal.io/api/rest/registry-service.md#filesuffix)
            :   ​

                Fields of `FileSuffix`

                `suffix` string
                :   ​

        `required` boolean
        :   Whether the input file is required for the extractor to run.

    `parameters` array of [`FileExtractionParameter`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#timestamptype)
        :   How the values in `series_name` should be interpreted as timestamps.

            Fields of `TimestampType`

            one of `relative`, `absolute`
            :   ​

                **relative**

                `relative` [`RelativeTimestamp`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#absolutetimestamp)
                :   ​

                    Fields of `AbsoluteTimestamp`

                    one of `iso8601`, `epochOfTimeUnit`, `customFormat`
                    :   ​

                        **iso8601**

                        `iso8601` [`Iso8601Timestamp`](https://dev.nominal.io/api/rest/registry-service.md#iso8601timestamp)
                        :   ​

                        **epochOfTimeUnit**

                        `epochOfTimeUnit` [`EpochTimestamp`](https://dev.nominal.io/api/rest/registry-service.md#epochtimestamp)
                        :   ​

                            Fields of `EpochTimestamp`

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

                        **customFormat**

                        `customFormat` [`CustomTimestamp`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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**

```shell
curl -X POST "https://api.gov.nominal.io/api/registry/v2/images" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "workspaceRid": "<workspace rid>",
  "tag": "<tag>",
  "extractorRid": "<extractor rid>",
  "defaultTimestampMetadata": {
    "seriesName": "<series name>",
    "timestampType": {
      "relative": {
        "timeUnit": "<time unit>",
        "offset": "2026-01-01T00:00:00Z"
      }
    }
  }
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/registry/v2/images",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "workspaceRid": "<workspace rid>",
        "tag": "<tag>",
        "extractorRid": "<extractor rid>",
        "defaultTimestampMetadata": {
            "seriesName": "<series name>",
            "timestampType": {
                "relative": {
                    "timeUnit": "<time unit>",
                    "offset": "2026-01-01T00:00:00Z",
                },
            },
        },
    },
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/registry/v2/images",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "workspaceRid": "<workspace rid>",
        "tag": "<tag>",
        "extractorRid": "<extractor rid>",
        "defaultTimestampMetadata": {
            "seriesName": "<series name>",
            "timestampType": {
                "relative": {
                    "timeUnit": "<time unit>",
                    "offset": "2026-01-01T00:00:00Z",
                },
            },
        },
    },
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/registry/v2/images",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "workspaceRid": "<workspace rid>",
                "tag": "<tag>",
                "extractorRid": "<extractor rid>",
                "defaultTimestampMetadata": {
                    "seriesName": "<series name>",
                    "timestampType": {
                        "relative": {
                            "timeUnit": "<time unit>",
                            "offset": "2026-01-01T00:00:00Z",
                        },
                    },
                },
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "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
    }
  }
}
```

### Search images

POST `/registry/v2/images/search`

List container images in a workspace, optionally filtered by tag / status.

Body

`workspaceRid` string required
:   ​

`filter` [`SearchFilter`](https://dev.nominal.io/api/rest/registry-service.md#searchfilter)
:   Optional composable filter. Omit to list all images in the workspace.

    Fields of `SearchFilter`

    one of `tag`, `status`, `and`, `extractor` required
    :   ​

        **tag**

        `tag` [`TagFilter`](https://dev.nominal.io/api/rest/registry-service.md#tagfilter)
        :   ​

            Fields of `TagFilter`

            `tag` string required
            :   ​

        **status**

        `status` [`StatusFilter`](https://dev.nominal.io/api/rest/registry-service.md#statusfilter)
        :   ​

            Fields of `StatusFilter`

            `status` [`ContainerImageStatus`](https://dev.nominal.io/api/rest/registry-service.md#containerimagestatus) required
            :   ​

                Values of `ContainerImageStatus`

                `CONTAINER_IMAGE_STATUS_UNSPECIFIED`
                :   ​

                `CONTAINER_IMAGE_STATUS_PENDING`
                :   ​

                `CONTAINER_IMAGE_STATUS_READY`
                :   ​

                `CONTAINER_IMAGE_STATUS_FAILED`
                :   ​

        **and**

        `and` [`AndFilter`](https://dev.nominal.io/api/rest/registry-service.md#andfilter)
        :   ​

            Fields of `AndFilter`

            `clauses` array of [`SearchFilter`](https://dev.nominal.io/api/rest/registry-service.md#searchfilter)
            :   ​

        **extractor**

        `extractor` [`ExtractorFilter`](https://dev.nominal.io/api/rest/registry-service.md#extractorfilter)
        :   ​

            Fields of `ExtractorFilter`

            `extractorRid` string required
            :   ​

`pageSize` integer
:   From 1 to 1,000.

`nextPageToken` string
:   ​

Response

`images` array of [`ContainerImage`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#filefilter)
        :   Optionally filter files for file selection.

            Fields of `FileFilter`

            `suffix` [`FileSuffix`](https://dev.nominal.io/api/rest/registry-service.md#filesuffix)
            :   ​

                Fields of `FileSuffix`

                `suffix` string
                :   ​

        `required` boolean
        :   Whether the input file is required for the extractor to run.

    `parameters` array of [`FileExtractionParameter`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#timestamptype)
        :   How the values in `series_name` should be interpreted as timestamps.

            Fields of `TimestampType`

            one of `relative`, `absolute`
            :   ​

                **relative**

                `relative` [`RelativeTimestamp`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#absolutetimestamp)
                :   ​

                    Fields of `AbsoluteTimestamp`

                    one of `iso8601`, `epochOfTimeUnit`, `customFormat`
                    :   ​

                        **iso8601**

                        `iso8601` [`Iso8601Timestamp`](https://dev.nominal.io/api/rest/registry-service.md#iso8601timestamp)
                        :   ​

                        **epochOfTimeUnit**

                        `epochOfTimeUnit` [`EpochTimestamp`](https://dev.nominal.io/api/rest/registry-service.md#epochtimestamp)
                        :   ​

                            Fields of `EpochTimestamp`

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

                        **customFormat**

                        `customFormat` [`CustomTimestamp`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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.

`nextPageToken` string
:   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/registry/v2/images/search" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "workspaceRid": "<workspace rid>"
}'
```

**requests**

```python
import requests

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

**httpx**

```python
import httpx

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

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/registry/v2/images/search",
            headers={"Authorization": "Bearer <api key>"},
            json={"workspaceRid": "<workspace rid>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "images": [
    {
      "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
      }
    }
  ],
  "nextPageToken": "<next page token>"
}
```

### 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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#filefilter)
        :   Optionally filter files for file selection.

            Fields of `FileFilter`

            `suffix` [`FileSuffix`](https://dev.nominal.io/api/rest/registry-service.md#filesuffix)
            :   ​

                Fields of `FileSuffix`

                `suffix` string
                :   ​

        `required` boolean
        :   Whether the input file is required for the extractor to run.

    `parameters` array of [`FileExtractionParameter`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#timestamptype)
        :   How the values in `series_name` should be interpreted as timestamps.

            Fields of `TimestampType`

            one of `relative`, `absolute`
            :   ​

                **relative**

                `relative` [`RelativeTimestamp`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#absolutetimestamp)
                :   ​

                    Fields of `AbsoluteTimestamp`

                    one of `iso8601`, `epochOfTimeUnit`, `customFormat`
                    :   ​

                        **iso8601**

                        `iso8601` [`Iso8601Timestamp`](https://dev.nominal.io/api/rest/registry-service.md#iso8601timestamp)
                        :   ​

                        **epochOfTimeUnit**

                        `epochOfTimeUnit` [`EpochTimestamp`](https://dev.nominal.io/api/rest/registry-service.md#epochtimestamp)
                        :   ​

                            Fields of `EpochTimestamp`

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

                        **customFormat**

                        `customFormat` [`CustomTimestamp`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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**

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

**requests**

```python
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**

```python
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**

```python
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`

```json
{
  "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**

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

**requests**

```python
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**

```python
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**

```python
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`

```json
{}
```

## Types

### AbsoluteTimestamp

Absolute timestamp parser variants.

Set exactly one of the fields below.

one of `iso8601`, `epochOfTimeUnit`, `customFormat` required
:   ​

    **iso8601**

    `iso8601` [`Iso8601Timestamp`](https://dev.nominal.io/api/rest/registry-service.md#iso8601timestamp)
    :   ​

    **epochOfTimeUnit**

    `epochOfTimeUnit` [`EpochTimestamp`](https://dev.nominal.io/api/rest/registry-service.md#epochtimestamp)
    :   ​

    **customFormat**

    `customFormat` [`CustomTimestamp`](https://dev.nominal.io/api/rest/registry-service.md#customtimestamp)
    :   ​

### AndFilter

`clauses` array of [`SearchFilter`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#fileextractioninput)
:   The input files this extractor requires, mapped to environment variables that store the path to each file.

`parameters` array of [`FileExtractionParameter`](https://dev.nominal.io/api/rest/registry-service.md#fileextractionparameter)
:   Parameters the extractor accepts.

`fileOutputFormat` [`FileOutputFormat`](https://dev.nominal.io/api/rest/registry-service.md#fileoutputformat)
:   Format of the output file produced by the extractor.

`defaultTimestampMetadata` [`TimestampMetadata`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#exitcodemapping)
:   Fallback exit-code-to-error mappings for extractors that cannot emit a structured /dev/termination-log document.

`resources` [`ContainerResources`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#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.

### SearchFilter

Set exactly one of the fields below.

one of `tag`, `status`, `and`, `extractor` required
:   ​

    **tag**

    `tag` [`TagFilter`](https://dev.nominal.io/api/rest/registry-service.md#tagfilter)
    :   ​

    **status**

    `status` [`StatusFilter`](https://dev.nominal.io/api/rest/registry-service.md#statusfilter)
    :   ​

    **and**

    `and` [`AndFilter`](https://dev.nominal.io/api/rest/registry-service.md#andfilter)
    :   ​

    **extractor**

    `extractor` [`ExtractorFilter`](https://dev.nominal.io/api/rest/registry-service.md#extractorfilter)
    :   ​

### StatusFilter

`status` [`ContainerImageStatus`](https://dev.nominal.io/api/rest/registry-service.md#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`](https://dev.nominal.io/api/rest/registry-service.md#timestamptype) required
:   How the values in `series_name` should be interpreted as timestamps.

### TimestampType

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

Set exactly one of the fields below.

one of `relative`, `absolute` required
:   ​

    **relative**

    `relative` [`RelativeTimestamp`](https://dev.nominal.io/api/rest/registry-service.md#relativetimestamp)
    :   ​

    **absolute**

    `absolute` [`AbsoluteTimestamp`](https://dev.nominal.io/api/rest/registry-service.md#absolutetimestamp)
    :   ​

Page design based on [Scalar](https://scalar.com), MIT License.