Registry service (gRPC)#

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.

Endpoints#

Create image#

gRPC /nominal.registry.v2.RegistryService/CreateImage

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.

Request: CreateImageRequest

workspace_rid 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).

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

extractor_rid string required

The containerized extractor this image is built for. Must exist in the same workspace.

inputs array of 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
environment_variable 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.

file_filters array of FileFilter

Optionally filter files for file selection.

Fields of FileFilter
suffix FileSuffix

​

Fields of FileSuffix
suffix string required

​

required boolean

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

parameters array of FileExtractionParameter

Parameters the extractor accepts.

Fields of FileExtractionParameter
environment_variable 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.

file_output_format 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

​

default_timestamp_metadata 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
series_name string required

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

timestamp_type TimestampType required

How the values in series_name should be interpreted as timestamps.

Fields of TimestampType
one of relative, absolute required

​

relative RelativeTimestamp

​

Fields of RelativeTimestamp
time_unit 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 AbsoluteTimestamp

​

Fields of AbsoluteTimestamp
one of iso8601, epoch_of_time_unit, custom_format required

​

iso8601 Iso8601Timestamp

​

epoch_of_time_unit EpochTimestamp

​

Fields of EpochTimestamp
time_unit string

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

custom_format CustomTimestamp

​

Fields of CustomTimestamp
format string

The format string should be in the format of the DateTimeFormatter class in Java.

default_year integer

Default year is accepted as an optional field for cases like IRIG time format. Will be overridden by year in time format.

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

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

exit_code_mappings array of ExitCodeMapping

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

Fields of ExitCodeMapping
exit_code 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

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

Fields of ContainerResources
cpu_cores integer (int64)

CPU cores requested for the container. From 1 to 32.

memory_gib integer (int64)

Memory in GiB, applied as both the request and the limit. From 1 to 128.

disk_gib integer (int64)

Size in GiB of each of the ephemeral input and output volumes. From 1 to 512.

Response: CreateImageResponse

image ContainerImage

​

Fields of ContainerImage
rid string

​

tag string

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

size_bytes integer (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

​

created_at string (date-time)

When the image record was created.

extractor_rid 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
environment_variable 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.

file_filters 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
environment_variable 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.

file_output_format 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

​

default_timestamp_metadata TimestampMetadata

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

Fields of TimestampMetadata
series_name string

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

timestamp_type TimestampType

How the values in series_name should be interpreted as timestamps.

Fields of TimestampType
one of relative, absolute

​

relative RelativeTimestamp

​

Fields of RelativeTimestamp
time_unit 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 AbsoluteTimestamp

​

Fields of AbsoluteTimestamp
one of iso8601, epoch_of_time_unit, custom_format

​

iso8601 Iso8601Timestamp

​

epoch_of_time_unit EpochTimestamp

​

Fields of EpochTimestamp
time_unit string

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

custom_format CustomTimestamp

​

Fields of CustomTimestamp
format string

The format string should be in the format of the DateTimeFormatter class in Java.

default_year integer

Default year is accepted as an optional field for cases like IRIG time format. Will be overridden by year in time format.

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

exit_code_mappings array of ExitCodeMapping

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

Fields of ExitCodeMapping
exit_code 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
cpu_cores integer (int64)

CPU cores requested for the container. From 1 to 32.

memory_gib integer (int64)

Memory in GiB, applied as both the request and the limit. From 1 to 128.

disk_gib integer (int64)

Size in GiB of each of the ephemeral input and output volumes. From 1 to 512.

Request

from datetime import datetime, timezone

import grpc
from nominal.protos.registry.v2 import registry_pb2, registry_pb2_grpc

channel = grpc.secure_channel("api.gov.nominal.io:443", grpc.ssl_channel_credentials())
registry_service = registry_pb2_grpc.RegistryServiceStub(channel)
auth = [("authorization", "Bearer <api key>")]

request = registry_pb2.CreateImageRequest(
    workspace_rid="<workspace rid>",
    tag="<tag>",
    extractor_rid="<extractor rid>",
    default_timestamp_metadata={
        "series_name": "<series name>",
        "timestamp_type": {
            "relative": {
                "time_unit": "<time unit>",
                "offset": datetime(2026, 1, 1, tzinfo=timezone.utc),
            },
        },
    },
)
response = registry_service.CreateImage(request, metadata=auth)
print(response)

package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"
	"time"

	registryv2 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/registry/v2"
	typestime "github.com/nominal-io/nominal-api-protos-go/nominal/protos/types/time"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
	"google.golang.org/protobuf/types/known/timestamppb"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	registryService := registryv2.NewRegistryServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &registryv2.CreateImageRequest{
		WorkspaceRid: "<workspace rid>",
		Tag:          "<tag>",
		ExtractorRid: "<extractor rid>",
		DefaultTimestampMetadata: &registryv2.TimestampMetadata{
			SeriesName: "<series name>",
			TimestampType: &typestime.TimestampType{
				Option: &typestime.TimestampType_Relative{Relative: &typestime.RelativeTimestamp{
					TimeUnit: "<time unit>",
					Offset:   timestamppb.New(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)),
				}},
			},
		},
	}
	response, err := registryService.CreateImage(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "image": {
    "rid": "<rid>",
    "tag": "<tag>",
    "size_bytes": 1,
    "status": "CONTAINER_IMAGE_STATUS_PENDING",
    "created_at": "2026-01-01T00:00:00Z",
    "extractor_rid": "<extractor rid>",
    "inputs": [
      {
        "environment_variable": "<environment variable>",
        "name": "<name>",
        "description": "<description>",
        "file_filters": [
          {
            "suffix": {
              "suffix": "<suffix>"
            }
          }
        ],
        "required": true
      }
    ],
    "parameters": [
      {
        "environment_variable": "<environment variable>",
        "name": "<name>",
        "description": "<description>",
        "required": true
      }
    ],
    "file_output_format": "FILE_OUTPUT_FORMAT_PARQUET",
    "default_timestamp_metadata": {
      "series_name": "<series name>",
      "timestamp_type": {
        "relative": {
          "time_unit": "<time unit>",
          "offset": "2026-01-01T00:00:00Z"
        }
      }
    },
    "exit_code_mappings": [
      {
        "exit_code": 1,
        "code": "<code>",
        "message": "<message>",
        "retryable": true
      }
    ],
    "resources": {
      "cpu_cores": 1,
      "memory_gib": 1,
      "disk_gib": 1
    }
  }
}

Delete image#

gRPC /nominal.registry.v2.RegistryService/DeleteImage

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

Request: DeleteImageRequest

rid string required

​

workspace_rid string required

​

Response: DeleteImageResponse

A message with no fields.

Request

import grpc
from nominal.protos.registry.v2 import registry_pb2, registry_pb2_grpc

channel = grpc.secure_channel("api.gov.nominal.io:443", grpc.ssl_channel_credentials())
registry_service = registry_pb2_grpc.RegistryServiceStub(channel)
auth = [("authorization", "Bearer <api key>")]

request = registry_pb2.DeleteImageRequest(rid="<rid>", workspace_rid="<workspace rid>")
response = registry_service.DeleteImage(request, metadata=auth)
print(response)

package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	registryv2 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/registry/v2"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	registryService := registryv2.NewRegistryServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &registryv2.DeleteImageRequest{
		Rid:          "<rid>",
		WorkspaceRid: "<workspace rid>",
	}
	response, err := registryService.DeleteImage(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{}

Get image#

gRPC /nominal.registry.v2.RegistryService/GetImage

Get the current state of a container image.

Request: GetImageRequest

rid string required

​

workspace_rid string required

​

Response: GetImageResponse

image ContainerImage

​

Fields of ContainerImage
rid string

​

tag string

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

size_bytes integer (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

​

created_at string (date-time)

When the image record was created.

extractor_rid 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
environment_variable 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.

file_filters 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
environment_variable 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.

file_output_format 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

​

default_timestamp_metadata TimestampMetadata

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

Fields of TimestampMetadata
series_name string

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

timestamp_type TimestampType

How the values in series_name should be interpreted as timestamps.

Fields of TimestampType
one of relative, absolute

​

relative RelativeTimestamp

​

Fields of RelativeTimestamp
time_unit 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 AbsoluteTimestamp

​

Fields of AbsoluteTimestamp
one of iso8601, epoch_of_time_unit, custom_format

​

iso8601 Iso8601Timestamp

​

epoch_of_time_unit EpochTimestamp

​

Fields of EpochTimestamp
time_unit string

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

custom_format CustomTimestamp

​

Fields of CustomTimestamp
format string

The format string should be in the format of the DateTimeFormatter class in Java.

default_year integer

Default year is accepted as an optional field for cases like IRIG time format. Will be overridden by year in time format.

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

exit_code_mappings array of ExitCodeMapping

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

Fields of ExitCodeMapping
exit_code 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
cpu_cores integer (int64)

CPU cores requested for the container. From 1 to 32.

memory_gib integer (int64)

Memory in GiB, applied as both the request and the limit. From 1 to 128.

disk_gib integer (int64)

Size in GiB of each of the ephemeral input and output volumes. From 1 to 512.

Request

import grpc
from nominal.protos.registry.v2 import registry_pb2, registry_pb2_grpc

channel = grpc.secure_channel("api.gov.nominal.io:443", grpc.ssl_channel_credentials())
registry_service = registry_pb2_grpc.RegistryServiceStub(channel)
auth = [("authorization", "Bearer <api key>")]

request = registry_pb2.GetImageRequest(rid="<rid>", workspace_rid="<workspace rid>")
response = registry_service.GetImage(request, metadata=auth)
print(response)

package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	registryv2 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/registry/v2"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	registryService := registryv2.NewRegistryServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &registryv2.GetImageRequest{
		Rid:          "<rid>",
		WorkspaceRid: "<workspace rid>",
	}
	response, err := registryService.GetImage(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "image": {
    "rid": "<rid>",
    "tag": "<tag>",
    "size_bytes": 1,
    "status": "CONTAINER_IMAGE_STATUS_PENDING",
    "created_at": "2026-01-01T00:00:00Z",
    "extractor_rid": "<extractor rid>",
    "inputs": [
      {
        "environment_variable": "<environment variable>",
        "name": "<name>",
        "description": "<description>",
        "file_filters": [
          {
            "suffix": {
              "suffix": "<suffix>"
            }
          }
        ],
        "required": true
      }
    ],
    "parameters": [
      {
        "environment_variable": "<environment variable>",
        "name": "<name>",
        "description": "<description>",
        "required": true
      }
    ],
    "file_output_format": "FILE_OUTPUT_FORMAT_PARQUET",
    "default_timestamp_metadata": {
      "series_name": "<series name>",
      "timestamp_type": {
        "relative": {
          "time_unit": "<time unit>",
          "offset": "2026-01-01T00:00:00Z"
        }
      }
    },
    "exit_code_mappings": [
      {
        "exit_code": 1,
        "code": "<code>",
        "message": "<message>",
        "retryable": true
      }
    ],
    "resources": {
      "cpu_cores": 1,
      "memory_gib": 1,
      "disk_gib": 1
    }
  }
}

Search images#

gRPC /nominal.registry.v2.RegistryService/SearchImages

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

Request: SearchImagesRequest

workspace_rid string required

​

filter SearchFilter

Optional composable filter. Omit to list all images in the workspace.

Fields of SearchFilter
one of tag, status, and, extractor required

​

tag TagFilter

​

Fields of TagFilter
tag string required

​

status StatusFilter

​

Fields of StatusFilter
status ContainerImageStatus required

​

Values of ContainerImageStatus
CONTAINER_IMAGE_STATUS_UNSPECIFIED

​

CONTAINER_IMAGE_STATUS_PENDING

​

CONTAINER_IMAGE_STATUS_READY

​

CONTAINER_IMAGE_STATUS_FAILED

​

and AndFilter

​

Fields of AndFilter
clauses array of SearchFilter

​

extractor ExtractorFilter

​

Fields of ExtractorFilter
extractor_rid string required

​

page_size integer

From 1 to 1,000.

next_page_token string

​

Response: SearchImagesResponse

images array of ContainerImage

​

Fields of ContainerImage
rid string

​

tag string

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

size_bytes integer (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

​

created_at string (date-time)

When the image record was created.

extractor_rid 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
environment_variable 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.

file_filters 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
environment_variable 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.

file_output_format 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

​

default_timestamp_metadata TimestampMetadata

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

Fields of TimestampMetadata
series_name string

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

timestamp_type TimestampType

How the values in series_name should be interpreted as timestamps.

Fields of TimestampType
one of relative, absolute

​

relative RelativeTimestamp

​

Fields of RelativeTimestamp
time_unit 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 AbsoluteTimestamp

​

Fields of AbsoluteTimestamp
one of iso8601, epoch_of_time_unit, custom_format

​

iso8601 Iso8601Timestamp

​

epoch_of_time_unit EpochTimestamp

​

Fields of EpochTimestamp
time_unit string

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

custom_format CustomTimestamp

​

Fields of CustomTimestamp
format string

The format string should be in the format of the DateTimeFormatter class in Java.

default_year integer

Default year is accepted as an optional field for cases like IRIG time format. Will be overridden by year in time format.

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

exit_code_mappings array of ExitCodeMapping

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

Fields of ExitCodeMapping
exit_code 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
cpu_cores integer (int64)

CPU cores requested for the container. From 1 to 32.

memory_gib integer (int64)

Memory in GiB, applied as both the request and the limit. From 1 to 128.

disk_gib integer (int64)

Size in GiB of each of the ephemeral input and output volumes. From 1 to 512.

next_page_token string

​

Request

import grpc
from nominal.protos.registry.v2 import registry_pb2, registry_pb2_grpc

channel = grpc.secure_channel("api.gov.nominal.io:443", grpc.ssl_channel_credentials())
registry_service = registry_pb2_grpc.RegistryServiceStub(channel)
auth = [("authorization", "Bearer <api key>")]

request = registry_pb2.SearchImagesRequest(workspace_rid="<workspace rid>")
response = registry_service.SearchImages(request, metadata=auth)
print(response)

package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	registryv2 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/registry/v2"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	registryService := registryv2.NewRegistryServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &registryv2.SearchImagesRequest{
		WorkspaceRid: "<workspace rid>",
	}
	response, err := registryService.SearchImages(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "images": [
    {
      "rid": "<rid>",
      "tag": "<tag>",
      "size_bytes": 1,
      "status": "CONTAINER_IMAGE_STATUS_PENDING",
      "created_at": "2026-01-01T00:00:00Z",
      "extractor_rid": "<extractor rid>",
      "inputs": [
        {
          "environment_variable": "<environment variable>",
          "name": "<name>",
          "description": "<description>",
          "file_filters": [
            {
              "suffix": {
                "suffix": "<suffix>"
              }
            }
          ],
          "required": true
        }
      ],
      "parameters": [
        {
          "environment_variable": "<environment variable>",
          "name": "<name>",
          "description": "<description>",
          "required": true
        }
      ],
      "file_output_format": "FILE_OUTPUT_FORMAT_PARQUET",
      "default_timestamp_metadata": {
        "series_name": "<series name>",
        "timestamp_type": {
          "relative": {
            "time_unit": "<time unit>",
            "offset": "2026-01-01T00:00:00Z"
          }
        }
      },
      "exit_code_mappings": [
        {
          "exit_code": 1,
          "code": "<code>",
          "message": "<message>",
          "retryable": true
        }
      ],
      "resources": {
        "cpu_cores": 1,
        "memory_gib": 1,
        "disk_gib": 1
      }
    }
  ],
  "next_page_token": "<next page token>"
}

Types#

AbsoluteTimestamp#

Absolute timestamp parser variants.

Set exactly one of the fields below.

one of iso8601, epoch_of_time_unit, custom_format required

​

iso8601 Iso8601Timestamp

​

epoch_of_time_unit EpochTimestamp

​

custom_format 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).

size_bytes integer (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).

created_at string (date-time)

When the image record was created.

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

file_output_format FileOutputFormat

Format of the output file produced by the extractor.

default_timestamp_metadata TimestampMetadata

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

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

cpu_cores integer (int64)

CPU cores requested for the container. From 1 to 32.

memory_gib integer (int64)

Memory in GiB, applied as both the request and the limit. From 1 to 128.

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

default_year integer

Default year is accepted as an optional field for cases like IRIG time format. Will be overridden by year in time format.

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

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

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

extractor_rid string required

​

FileExtractionInput#

Defines an input file to be provided to the extractor.

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

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

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

A message with no fields.

RelativeTimestamp#

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

time_unit 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 TagFilter

​

status StatusFilter

​

and AndFilter

​

extractor ExtractorFilter

​

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.

series_name string required

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

timestamp_type 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 RelativeTimestamp

​

absolute AbsoluteTimestamp

​

Page design based on Scalar, MIT License.