Quickstart

Install

pip install minerva-sdk

Python 3.11+ (tested through 3.14).

Set your API key

export MINERVA_API_KEY=mk_live_...

The SDK reads MINERVA_API_KEY from the environment by default. You can also pass it as a constructor arg (handy in tests / notebooks):

mc = Minerva(api_key="mk_live_...")

Resolve, enrich

from minerva import Minerva

mc = Minerva()

# Resolve — match records to a Minerva PID (lighter / cheaper than enrich)
match = mc.api.resolve([
    {"record_id": "1", "first_name": "Jane", "last_name": "Doe",
     "emails": ["jane.doe@example.com"]}
])
for r in match.results:
    print(r.record_id, r.is_match, r.minerva_pid, r.match_score)

# Enrich — full person profiles (up to 500 records per call)
people = mc.api.enrich([
    {"record_id": "1", "linkedin_url": "https://www.linkedin.com/in/example"}
])
people.to_df()          # straight to a pandas DataFrame (needs [pandas])
people.to_csv("out.csv")

Explore from the terminal

python -m minerva         # banner + cheat-sheet of every namespace
python -m minerva --help  # argparse help with usage epilog

From a REPL:

>>> from minerva import Minerva
>>> help(Minerva)               # full class docstring
>>> help(Minerva.api)           # the data-API namespace

What you get

`mc.api`

resolve · enrich · get_li_contact_info · validate_emails · infer_record_country · call

`mc.usage`

tallies() — your per-endpoint API usage

`mc.status`

health() — unauthenticated liveness probe

`mc.io`

enrich_from_sheet / _excel — run the Data API directly off spreadsheets

Validate before you call

Every input-bearing method accepts dry_run=True — validates input locally and returns the exact request that would be sent, without spending a credit:

req = mc.api.enrich(records, dry_run=True)
# -> EnrichRequest (nothing sent); inspect req.model_dump()

See Validation & dry_run for the full pattern.

Getting started

Endpoints

Power features

Reference

What you get

`mc.api`

`mc.usage`

`mc.status`

`mc.io`

Validate before you call

​What you get

`mc.api`

`mc.usage`

`mc.status`

`mc.io`

​Validate before you call

What you get

Validate before you call