Skip to main content
The official Python SDK for the Minerva Data API. Identity resolution, person enrichment, LinkedIn lookup, email validation, country inference, and usage tallies — all from one client, with typed responses and validation built in.
A Minerva API key is required. Set MINERVA_API_KEY in your environment or pass api_key= to the constructor. See Authentication for where to find your key and how the SDK resolves credentials.
Early access (alpha). The interface below is stable; we’re hardening the edges ahead of the public release. Feedback welcome.

​
Why this SDK

One client, one credential

Minerva(api_key=...) is the only entry point. Your x-api-key goes on every request. No tokens, no sessions, no rotation logic to manage.

Typed end-to-end

Every response is a typed pydantic object with IDE autocomplete. Missing fields fail at type-check, not at runtime. Forward-compatible — new fields the API adds won’t break older clients.

Validate before you spend

dry_run=True validates input locally and tells you exactly what’s wrong — before anything hits the network. Same checks the server runs, available offline.

Tabular by default

Any list-shaped result → to_df() / to_csv() / to_dicts() / to_table(). Nested fields flatten for you; missing extras error clearly.

Hardened

The Minerva instance rejects any attribute writes after construction — typos and accidental tinkering raise AttributeError instead of silently breaking subsequent calls.

Custom-endpoint escape hatch

mc.api.call(method, path, …) for client-specific routes that don’t have a typed wrapper yet. Same auth + error mapping; raw JSON in/out.

​
Where to go next

Quickstart

Five-minute tour — install, set your key, run your first enrichment.

Authentication

Just MINERVA_API_KEY. No token exchange. No session state.

Enrich

Full person profiles from a record stub. Up to 500 records per call.

Custom endpoints

The mc.api.call(...) escape hatch for tailored / preview routes.

​
Get help fast

  • python -m minerva — banner, version, and a cheat-sheet of the public API.
  • help(Minerva) in a REPL or Minerva? in Jupyter — full class + method docstrings.
  • Reach support with the api_request_id carried on every MinervaAPIError.