Containerized extractor service#

Manages containerized extractors backed by self-hosted images in the internal registry.

OpenAPI file: nominal.ingest.v2.json

Endpoints#

Create containerized extractor#

POST /extractors/v2

Create a new extractor in a workspace. Container images are attached separately via RegistryService.CreateImage.

Body

workspaceRid string required
name string required
description string
properties map of string to string: Free-form name/value pairs to associate with the new extractor. Uses the resource metadata limits above. At most 64 entries.
labels array of string: Labels to apply to the new extractor. Uses the resource metadata limits above. At most 64 items. Each item: 1 to 255 characters.

Response

extractor ContainerizedExtractor

Fields of ContainerizedExtractor

rid string

Unique resource identifier for this extractor.

workspaceRid string

Workspace that owns this extractor.

name string

User-supplied name. Need not be unique within a workspace.

description string

Free-form description shown in the UI.

createdAt string (date-time)

Timestamp at which this extractor was first registered.

isArchived boolean

True once the extractor has been archived. Archived extractors are hidden from default search results and reject new ingests; flip back to false on UpdateContainerizedExtractor to restore.

activeContainerImage ContainerImage

The container image currently selected to run this extractor. Unset until the first image for this extractor reaches READY status; ingest requests that arrive before then will fail. The schema fields (inputs, parameters, output_file_format, default_timestamp_metadata) live on this nested image.

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 registry.v2.TimestampMetadata

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

Fields of registry.v2.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.

origin ExtractorOrigin

Provenance: CUSTOMER for workspace-authored extractors (the default), FIRST_PARTY for Nominal-published extractors installed from the catalog. Read-only: native-extractor rows are created and upgraded by catalog reconciliation, never through the public write APIs.

Values of ExtractorOrigin

EXTRACTOR_ORIGIN_UNSPECIFIED
EXTRACTOR_ORIGIN_CUSTOMER
EXTRACTOR_ORIGIN_FIRST_PARTY

catalogId string

Stable catalog identifier (e.g. “ardupilot-dataflash”). Set only when origin is FIRST_PARTY. The version currently active is carried by the installation record and by the active container image’s tag, not duplicated here.

properties map of string to string

Free-form name/value pairs associated with this extractor. At most 64 pairs; names are 1-255 chars and values are up to 1024 chars. At most 64 entries.

labels array of string

Labels applied to this extractor, filterable through SearchContainerizedExtractors. At most 64 labels of 1-255 chars each. At most 64 items. Each item: 1 to 255 characters.

Request

curl

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

requests

import requests

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

httpx

import httpx

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

aiohttp

import asyncio

import aiohttp


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


asyncio.run(main())

Response: 200

{
  "extractor": {
    "rid": "<rid>",
    "workspaceRid": "<workspace rid>",
    "name": "<name>",
    "description": "<description>",
    "createdAt": "2026-01-01T00:00:00Z",
    "isArchived": true,
    "activeContainerImage": {
      "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
      }
    },
    "origin": "EXTRACTOR_ORIGIN_CUSTOMER",
    "catalogId": "<catalog id>",
    "properties": {
      "<key>": "<value>"
    },
    "labels": [
      "<labels>"
    ]
  }
}

Search containerized extractors#

POST /extractors/v2/search

Search extractors within a workspace, with cursor-based pagination.

Body

workspaceRid string required
includeArchived boolean: When true, archived extractors are also returned.
pageSize integer required: From 1 to 1,000.
nextPageToken string
fileExtension string: When set, restricts results to extractors whose active container image is READY and declares at least one FileExtractionInput whose file_filters include this suffix. Example values: “csv”, “parquet”, “mcap” — no leading dot, case-sensitive against FileSuffix.suffix. 1 to 32 characters.
properties map of string to string: When non-empty, restricts results to extractors whose properties contain every one of these name/value pairs (exact match, AND semantics). Uses the resource metadata limits above. At most 64 entries.
labels array of string: When non-empty, restricts results to extractors carrying all of these labels (exact match, AND semantics). Uses the resource metadata limits above. At most 64 items. Each item: 1 to 255 characters.

Response

extractors array of ContainerizedExtractor

Fields of ContainerizedExtractor

rid string

Unique resource identifier for this extractor.

workspaceRid string

Workspace that owns this extractor.

name string

User-supplied name. Need not be unique within a workspace.

description string

Free-form description shown in the UI.

createdAt string (date-time)

Timestamp at which this extractor was first registered.

isArchived boolean

True once the extractor has been archived. Archived extractors are hidden from default search results and reject new ingests; flip back to false on UpdateContainerizedExtractor to restore.

activeContainerImage 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 registry.v2.TimestampMetadata

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

Fields of registry.v2.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.

origin ExtractorOrigin

Values of ExtractorOrigin

EXTRACTOR_ORIGIN_UNSPECIFIED
EXTRACTOR_ORIGIN_CUSTOMER
EXTRACTOR_ORIGIN_FIRST_PARTY

catalogId string

properties map of string to string

Free-form name/value pairs associated with this extractor. At most 64 pairs; names are 1-255 chars and values are up to 1024 chars. At most 64 entries.

labels array of string

Labels applied to this extractor, filterable through SearchContainerizedExtractors. At most 64 labels of 1-255 chars each. At most 64 items. Each item: 1 to 255 characters.

nextPageToken string

Request

curl

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

requests

import requests

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

httpx

import httpx

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

aiohttp

import asyncio

import aiohttp


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


asyncio.run(main())

Response: 200

{
  "extractors": [
    {
      "rid": "<rid>",
      "workspaceRid": "<workspace rid>",
      "name": "<name>",
      "description": "<description>",
      "createdAt": "2026-01-01T00:00:00Z",
      "isArchived": true,
      "activeContainerImage": {
        "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
        }
      },
      "origin": "EXTRACTOR_ORIGIN_CUSTOMER",
      "catalogId": "<catalog id>",
      "properties": {
        "<key>": "<value>"
      },
      "labels": [
        "<labels>"
      ]
    }
  ],
  "nextPageToken": "<next page token>"
}

Get containerized extractor#

GET /extractors/v2/{rid}

Fetch a single extractor by RID.

Path parameters

rid string required

Query parameters

workspaceRid string required

Response

extractor ContainerizedExtractor

Fields of ContainerizedExtractor

rid string

Unique resource identifier for this extractor.

workspaceRid string

Workspace that owns this extractor.

name string

User-supplied name. Need not be unique within a workspace.

description string

Free-form description shown in the UI.

createdAt string (date-time)

Timestamp at which this extractor was first registered.

isArchived boolean

True once the extractor has been archived. Archived extractors are hidden from default search results and reject new ingests; flip back to false on UpdateContainerizedExtractor to restore.

activeContainerImage 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 registry.v2.TimestampMetadata

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

Fields of registry.v2.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.

origin ExtractorOrigin

Values of ExtractorOrigin

EXTRACTOR_ORIGIN_UNSPECIFIED
EXTRACTOR_ORIGIN_CUSTOMER
EXTRACTOR_ORIGIN_FIRST_PARTY

catalogId string

properties map of string to string

Free-form name/value pairs associated with this extractor. At most 64 pairs; names are 1-255 chars and values are up to 1024 chars. At most 64 entries.

labels array of string

Labels applied to this extractor, filterable through SearchContainerizedExtractors. At most 64 labels of 1-255 chars each. At most 64 items. Each item: 1 to 255 characters.

Request

curl

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

requests

import requests

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


asyncio.run(main())

Response: 200

{
  "extractor": {
    "rid": "<rid>",
    "workspaceRid": "<workspace rid>",
    "name": "<name>",
    "description": "<description>",
    "createdAt": "2026-01-01T00:00:00Z",
    "isArchived": true,
    "activeContainerImage": {
      "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
      }
    },
    "origin": "EXTRACTOR_ORIGIN_CUSTOMER",
    "catalogId": "<catalog id>",
    "properties": {
      "<key>": "<value>"
    },
    "labels": [
      "<labels>"
    ]
  }
}

Update containerized extractor#

PATCH /extractors/v2/{rid}

Partial update of an existing extractor. Use the is_archived field to archive / unarchive.

Path parameters

rid string required

Body

workspaceRid string required

name string

description string

isArchived boolean

Set to true to archive, false to unarchive. Leave unset to leave archive state unchanged.

activeContainerImageRid string

RID of the container image to set as the active one for this extractor. Must reference a ContainerImage that is owned by the same workspace, was built for this extractor, and has reached READY status. Leave unset to leave the active image unchanged.

properties PropertyUpdateWrapper

Absent metadata is unchanged; present collections replace it, including empty collections. Uses the resource metadata limits above. properties must contain at most 64 pairs, with names of 1-255 characters and values up to 1024 characters.

Fields of PropertyUpdateWrapper

properties map of string to string

labels LabelUpdateWrapper

Uses the resource metadata limits above. labels must contain at most 64 entries of 1-255 characters each.

Fields of LabelUpdateWrapper

labels array of string

Response

extractor ContainerizedExtractor

Fields of ContainerizedExtractor

rid string

Unique resource identifier for this extractor.

workspaceRid string

Workspace that owns this extractor.

name string

User-supplied name. Need not be unique within a workspace.

description string

Free-form description shown in the UI.

createdAt string (date-time)

Timestamp at which this extractor was first registered.

isArchived boolean

True once the extractor has been archived. Archived extractors are hidden from default search results and reject new ingests; flip back to false on UpdateContainerizedExtractor to restore.

activeContainerImage 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 registry.v2.TimestampMetadata

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

Fields of registry.v2.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.

origin ExtractorOrigin

Values of ExtractorOrigin

EXTRACTOR_ORIGIN_UNSPECIFIED
EXTRACTOR_ORIGIN_CUSTOMER
EXTRACTOR_ORIGIN_FIRST_PARTY

catalogId string

properties map of string to string

Free-form name/value pairs associated with this extractor. At most 64 pairs; names are 1-255 chars and values are up to 1024 chars. At most 64 entries.

labels array of string

Labels applied to this extractor, filterable through SearchContainerizedExtractors. At most 64 labels of 1-255 chars each. At most 64 items. Each item: 1 to 255 characters.

Request

curl

curl -X PATCH "https://api.gov.nominal.io/api/extractors/v2/<rid>" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "workspaceRid": "<workspace rid>"
}'

requests

import requests

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

httpx

import httpx

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

aiohttp

import asyncio

import aiohttp


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


asyncio.run(main())

Response: 200

{
  "extractor": {
    "rid": "<rid>",
    "workspaceRid": "<workspace rid>",
    "name": "<name>",
    "description": "<description>",
    "createdAt": "2026-01-01T00:00:00Z",
    "isArchived": true,
    "activeContainerImage": {
      "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
      }
    },
    "origin": "EXTRACTOR_ORIGIN_CUSTOMER",
    "catalogId": "<catalog id>",
    "properties": {
      "<key>": "<value>"
    },
    "labels": [
      "<labels>"
    ]
  }
}

Archive containerized extractor#

POST /extractors/v2/{rid}/archive

Archive an extractor so it is hidden from default search results and rejects new ingests.

Path parameters

rid string required

Body

workspaceRid string required

Response

An empty JSON object, {}.

Request

curl

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

requests

import requests

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

httpx

import httpx

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

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/extractors/v2/<rid>/archive",
            headers={"Authorization": "Bearer <api key>"},
            json={"workspaceRid": "<workspace rid>"},
        ) 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

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 registry.v2.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

ContainerizedExtractor#

A containerized extractor that processes input files using a self-hosted container image.

Schema fields (inputs, parameters, output format, timestamp metadata) live on the underlying ContainerImage rows; clients should read them off active_container_image. The extractor itself carries only identity, workspace ownership, user metadata (labels/properties), and lifecycle state.

rid string required: Unique resource identifier for this extractor.
workspaceRid string required: Workspace that owns this extractor.
name string: User-supplied name. Need not be unique within a workspace.
description string: Free-form description shown in the UI.
createdAt string (date-time): Timestamp at which this extractor was first registered.
isArchived boolean: True once the extractor has been archived. Archived extractors are hidden from default search results and reject new ingests; flip back to false on UpdateContainerizedExtractor to restore.
activeContainerImage ContainerImage: The container image currently selected to run this extractor. Unset until the first image for this extractor reaches READY status; ingest requests that arrive before then will fail. The schema fields (inputs, parameters, output_file_format, default_timestamp_metadata) live on this nested image.
origin ExtractorOrigin: Provenance: CUSTOMER for workspace-authored extractors (the default), FIRST_PARTY for Nominal-published extractors installed from the catalog. Read-only: native-extractor rows are created and upgraded by catalog reconciliation, never through the public write APIs.
catalogId string: Stable catalog identifier (e.g. “ardupilot-dataflash”). Set only when origin is FIRST_PARTY. The version currently active is carried by the installation record and by the active container image’s tag, not duplicated here.
properties map of string to string: Free-form name/value pairs associated with this extractor. At most 64 pairs; names are 1-255 chars and values are up to 1024 chars. At most 64 entries.
labels array of string: Labels applied to this extractor, filterable through SearchContainerizedExtractors. At most 64 labels of 1-255 chars each. At most 64 items. Each item: 1 to 255 characters.

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.

ExtractorOrigin#

Provenance of a containerized extractor: authored by a customer workspace, or published by Nominal through the native extractor catalog and materialized into the workspace by catalog reconciliation.

EXTRACTOR_ORIGIN_UNSPECIFIED
EXTRACTOR_ORIGIN_CUSTOMER
EXTRACTOR_ORIGIN_FIRST_PARTY

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, {}.

LabelUpdateWrapper#

Wrapper classes to allow for optional fields on update requests

labels array of string

PropertyUpdateWrapper#

properties map of string to string

registry.v2.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.

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.

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

absolute

absolute AbsoluteTimestamp

Page design based on Scalar, MIT License.