# Containerized extractor service

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

OpenAPI file: [`nominal.ingest.v2.json`](https://dev.nominal.io/api/_downloads/064305915dc637b34369651e3e33dd72/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`](https://dev.nominal.io/api/rest/containerized-extractor-service.md#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`](https://dev.nominal.io/api/rest/containerized-extractor-service.md#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`](https://dev.nominal.io/api/rest/containerized-extractor-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/containerized-extractor-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/containerized-extractor-service.md#filefilter)
            :   Optionally filter files for file selection.

                Fields of `FileFilter`

                `suffix` [`FileSuffix`](https://dev.nominal.io/api/rest/containerized-extractor-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/containerized-extractor-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/containerized-extractor-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` [`registry.v2.TimestampMetadata`](https://dev.nominal.io/api/rest/containerized-extractor-service.md#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`](https://dev.nominal.io/api/rest/containerized-extractor-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/containerized-extractor-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/containerized-extractor-service.md#absolutetimestamp)
                    :   ​

                        Fields of `AbsoluteTimestamp`

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

                            **iso8601**

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

                            **epochOfTimeUnit**

                            `epochOfTimeUnit` [`EpochTimestamp`](https://dev.nominal.io/api/rest/containerized-extractor-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/containerized-extractor-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/containerized-extractor-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/containerized-extractor-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.

    `origin` [`ExtractorOrigin`](https://dev.nominal.io/api/rest/containerized-extractor-service.md#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**

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

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

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

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

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

                Fields of `FileFilter`

                `suffix` [`FileSuffix`](https://dev.nominal.io/api/rest/containerized-extractor-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/containerized-extractor-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/containerized-extractor-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` [`registry.v2.TimestampMetadata`](https://dev.nominal.io/api/rest/containerized-extractor-service.md#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`](https://dev.nominal.io/api/rest/containerized-extractor-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/containerized-extractor-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/containerized-extractor-service.md#absolutetimestamp)
                    :   ​

                        Fields of `AbsoluteTimestamp`

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

                            **iso8601**

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

                            **epochOfTimeUnit**

                            `epochOfTimeUnit` [`EpochTimestamp`](https://dev.nominal.io/api/rest/containerized-extractor-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/containerized-extractor-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/containerized-extractor-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/containerized-extractor-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.

    `origin` [`ExtractorOrigin`](https://dev.nominal.io/api/rest/containerized-extractor-service.md#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.

`nextPageToken` string
:   ​

Request

**curl**

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

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

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

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

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

                Fields of `FileFilter`

                `suffix` [`FileSuffix`](https://dev.nominal.io/api/rest/containerized-extractor-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/containerized-extractor-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/containerized-extractor-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` [`registry.v2.TimestampMetadata`](https://dev.nominal.io/api/rest/containerized-extractor-service.md#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`](https://dev.nominal.io/api/rest/containerized-extractor-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/containerized-extractor-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/containerized-extractor-service.md#absolutetimestamp)
                    :   ​

                        Fields of `AbsoluteTimestamp`

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

                            **iso8601**

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

                            **epochOfTimeUnit**

                            `epochOfTimeUnit` [`EpochTimestamp`](https://dev.nominal.io/api/rest/containerized-extractor-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/containerized-extractor-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/containerized-extractor-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/containerized-extractor-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.

    `origin` [`ExtractorOrigin`](https://dev.nominal.io/api/rest/containerized-extractor-service.md#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**

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

**requests**

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

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

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

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

                Fields of `FileFilter`

                `suffix` [`FileSuffix`](https://dev.nominal.io/api/rest/containerized-extractor-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/containerized-extractor-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/containerized-extractor-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` [`registry.v2.TimestampMetadata`](https://dev.nominal.io/api/rest/containerized-extractor-service.md#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`](https://dev.nominal.io/api/rest/containerized-extractor-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/containerized-extractor-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/containerized-extractor-service.md#absolutetimestamp)
                    :   ​

                        Fields of `AbsoluteTimestamp`

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

                            **iso8601**

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

                            **epochOfTimeUnit**

                            `epochOfTimeUnit` [`EpochTimestamp`](https://dev.nominal.io/api/rest/containerized-extractor-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/containerized-extractor-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/containerized-extractor-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/containerized-extractor-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.

    `origin` [`ExtractorOrigin`](https://dev.nominal.io/api/rest/containerized-extractor-service.md#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**

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

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

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

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

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

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

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

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

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

```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/containerized-extractor-service.md#iso8601timestamp)
    :   ​

    **epochOfTimeUnit**

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

    **customFormat**

    `customFormat` [`CustomTimestamp`](https://dev.nominal.io/api/rest/containerized-extractor-service.md#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`](https://dev.nominal.io/api/rest/containerized-extractor-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/containerized-extractor-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/containerized-extractor-service.md#fileextractionparameter)
:   Parameters the extractor accepts.

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

`defaultTimestampMetadata` [`registry.v2.TimestampMetadata`](https://dev.nominal.io/api/rest/containerized-extractor-service.md#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`](https://dev.nominal.io/api/rest/containerized-extractor-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/containerized-extractor-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`
:   ​

### 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`](https://dev.nominal.io/api/rest/containerized-extractor-service.md#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`](https://dev.nominal.io/api/rest/containerized-extractor-service.md#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`](https://dev.nominal.io/api/rest/containerized-extractor-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/containerized-extractor-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, `{}`.

### 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`](https://dev.nominal.io/api/rest/containerized-extractor-service.md#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`](https://dev.nominal.io/api/rest/containerized-extractor-service.md#relativetimestamp)
    :   ​

    **absolute**

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

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