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.

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.