corva-api-client

Python SDK for working with Corva HTTP and data APIs.

This repository packages shared client logic for Corva integrations, scripts, jobs, and internal applications. It provides a configured HTTP client, environment-driven settings, dataset helpers, and generated resource clients for a broad set of Corva API endpoints.

What it provides

• CorvaConfig for environment-based configuration
• CorvaClient for authenticated HTTP access
• resource clients exposed on CorvaClient such as assets, apps, datasets, projects, wells, and data
• helpers for dataset fetch, aggregate, and pagination workflows
• request-building utilities for data API queries

Installation

For local development in this repository:

uv sync

To use this package from another local repository during development:

uv add --editable /path/to/corva-api-client

Published distribution name:

uv add corva-api-client

Python import path:

import corva_api_client

Quick Start

from corva_api_client import CorvaClient, CorvaConfig

config = CorvaConfig.from_env()
client = CorvaClient(config)

asset = client.get_asset(68833811)

records = client.paginate_dataset(
    dataset="wits.summary-1ft",
    asset_id=68833811,
    query={"timestamp": {"$gte": 1776164400, "$lt": 1776250800}},
    fields=["timestamp", "asset_id"],
    page_size=1000,
)

client.close()

Direct resource access is also available:

from corva_api_client import CorvaClient, CorvaConfig

client = CorvaClient(CorvaConfig.from_env())
companies = client.companies.list()
apps = client.apps.search(type="drilling")
client.close()

Asset field selection

Asset searches use a compact fieldset by default to avoid returning every asset attribute and relationship:

assets = client.assets.search()
# fields=asset.name,asset.asset_type,asset.status

Use the exported field enums to discover and select additional data. A relationship must be selected along with any fields needed from its related record:

from corva_api_client.resources import AssetField, AssetRelationship, CompanyField

assets = client.assets.search(
    fields=[
        AssetField.NAME,
        AssetField.COUNTRY,
        AssetRelationship.COMPANY,
        CompanyField.NAME,
    ]
)

The client also accepts comma-separated strings and arbitrary field names for forward compatibility. Pass fields="*" or fields="all" only when every supported attribute and relationship is required, because those options can produce substantially larger responses. Pass fields=None to omit the parameter and use the API's default fieldset.

Well searches also accept typed sparse fields. The SDK retains its existing fields="*" well-search default for compatibility; select the compact fieldset explicitly for discovery workflows:

from corva_api_client.resources import DEFAULT_WELL_FIELDS, WellField

wells = client.wells.search(fields=DEFAULT_WELL_FIELDS)
# fields=well.asset_id,well.name,well.status,well.state
wells = client.wells.search(fields=[WellField.NAME, WellField.IDENTIFIER])

WellField exposes unconditional well attributes. Relationship and conditional fields are not advertised by this enum. Raw field strings remain supported. Empty field sequences raise ValueError to avoid accidentally requesting the server's broader defaults; None explicitly selects the server default.

When the Rails asset serializers or relationship whitelist change, compare this SDK's field enums with a local corva-api checkout:

just check-asset-fields /path/to/corva-api

Configuration

CorvaConfig.from_env() reads these environment variables:

• CORVA_API_KEY
• CORVA_ENVIRONMENT
  • production, qa, or staging
• CORVA_AUTH_KIND
  • api_key or jwt
• CORVA_API_URL
  • optional override for the main API base URL
• CORVA_DATA_API_URL
  • optional override for the data API base URL
• CORVA_APP_KEY
  • optional override, defaults to corva-api-client

Development

Common repository tasks are exposed through just and run through uv:

just
just format
just lint
just typecheck
just test
just check
just build
just check-dist

Equivalent direct commands are:

uv run ruff format src tests
uv run ruff check src tests
uv run ty check
uv run pytest
uv build

Notes

• The package requires Python 3.11 or newer.
• CorvaClient raises RuntimeError if no API key is configured.
• The data resource serializer supports BSON-native values such as ObjectId, Decimal128, and Int64 when creating or replacing dataset records.