> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minerva.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Minerva Python SDK

> One client for the Minerva Data API. Typed end-to-end. Input validation before any call hits the network.

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.

<Note>
  **A Minerva API key is required.** Set `MINERVA_API_KEY` in your environment
  or pass `api_key=` to the constructor. See [Authentication](/sdk/authentication)
  for where to find your key and how the SDK resolves credentials.
</Note>

<Note>
  **Early access (alpha).** The interface below is stable; we're hardening the
  edges ahead of the public release. Feedback welcome.
</Note>

## Why this SDK

<CardGroup cols={2}>
  <Card title="One client, one credential" icon="key">
    `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.
  </Card>

  <Card title="Typed end-to-end" icon="circle-check">
    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.
  </Card>

  <Card title="Validate before you spend" icon="shield-check">
    `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.
  </Card>

  <Card title="Tabular by default" icon="table">
    Any list-shaped result → `to_df()` / `to_csv()` / `to_dicts()` /
    `to_table()`. Nested fields flatten for you; missing extras error clearly.
  </Card>

  <Card title="Hardened" icon="lock">
    The `Minerva` instance rejects any attribute writes after construction —
    typos and accidental tinkering raise `AttributeError` instead of silently
    breaking subsequent calls.
  </Card>

  <Card title="Custom-endpoint escape hatch" icon="bolt">
    `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.
  </Card>
</CardGroup>

## Where to go next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/sdk/quickstart">
    Five-minute tour — install, set your key, run your first enrichment.
  </Card>

  <Card title="Authentication" icon="lock" href="/sdk/authentication">
    Just `MINERVA_API_KEY`. No token exchange. No session state.
  </Card>

  <Card title="Enrich" icon="user-plus" href="/sdk/guides/enrich">
    Full person profiles from a record stub. Up to 500 records per call.
  </Card>

  <Card title="Custom endpoints" icon="bolt" href="/sdk/guides/custom-endpoints">
    The `mc.api.call(...)` escape hatch for tailored / preview routes.
  </Card>
</CardGroup>

## 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`.