REST client reference

MINTClient is the synchronous Python client for the MINT platform REST API. Use it from external scripts, CI jobs, or notebooks; from inside a plugin process, prefer PlatformContext accessors which avoid the network round-trip.

Source: mint_sdk/client/client.py.

Construction

from mint_sdk import MINTClient

# 1. Explicit URL + token
with MINTClient(base_url="https://mint.example.org", token="eyJ...") as client:
    ...

# 2. Username + password — auto-logs in during construction
with MINTClient(base_url="https://mint.example.org",
                 username="alice", password="…") as client:
    me = client.whoami()

# 3. Env-aware (no arguments) — reads MINT_URL and MINT_TOKEN, falling back
#    to credentials stored by `mint auth login` at ~/.config/mint/credentials.json
with MINTClient() as client:
    ...

MINTClient is synchronous — uses plain with, not async with. The constructor signature:

MINTClient(
    base_url: str | None = None,
    token: str | None = None,
    username: str | None = None,
    password: str | None = None,
    timeout: float = 30.0,
)

When base_url is None, the resolution order is:

1. MINT_URL env var
2. Stored credentials at ~/.config/mint/credentials.json (written by mint auth login; honors XDG_CONFIG_HOME)
3. Otherwise raise MINTAPIError

When token is None, the same fallback chain runs for the JWT (env: MINT_TOKEN).

Convenience auth methods

Method	Returns	Purpose
client.login(username, password)	dict	Authenticate; store JWT in the client
client.logout()	None	Clear stored credentials
client.whoami()	dict	Return current user info

These are thin wrappers over client.auth.

Resource clients

MINTClient exposes typed sub-clients per resource. Each is a @cached_property that lazy-imports its module on first access:

Property	Type	Purpose
client.auth	AuthAPI	Login / logout / verify / refresh / whoami
client.experiments	ExperimentsAPI	Experiment CRUD, design data, analysis results, experiment types
client.projects	ProjectsAPI	List, get, create, update, delete, experiments, members
client.plugins	PluginsAPI	List loaded plugins
client.admin	AdminAPI	Admin diagnostics, users, roles, plugin-role assignments
client.updates	UpdatesAPI	Platform/plugin update checks, GitHub release installs

Source for resource methods: mint_sdk/client/resources/.

Not exposed

Earlier docs claimed client.users and client.artifacts — those don't exist. There is no MINTClient.from_env() factory; use the env-aware constructor (option 3 above).

Experiments

client.experiments.list() unwraps the platform response and returns a plain list[dict]:

with MINTClient() as client:
    experiments = client.experiments.list(
        status="completed",
        experiment_type="lcms_batch",
        project_id=12,
        search="TCA",
        mine=True,
        created_after="2026-05-01",
        created_before="2026-06-01",
        skip=0,
        limit=100,
        sort_by="created_at",
        sort_order="desc",
    )

CRUD methods mirror the REST API:

Method	Purpose
list(...)	Filter visible experiments by status, type, project, owner, date window, or search text
get(experiment_id)	Fetch one experiment detail record
create(name=..., experiment_type="custom", project_id=None, notes=None, tags=None)	Create an experiment; MINT assigns the type-scoped code
update(experiment_id, **fields)	Patch metadata such as name, status, type, project, notes, tags, or dates
delete(experiment_id)	Delete the experiment row
list_types()	List enabled experiment types
next_seq(experiment_type)	Preview the next code sequence for a type

Deletion is immediate in the current backend. Take a normal database backup before running bulk delete scripts.

Experiment data

Design data is one JSON payload per experiment. Analysis results are JSON entries keyed by plugin_id.

with MINTClient() as client:
    design = client.experiments.design_data.get(42)
    client.experiments.design_data.save(
        42,
        plugin_id="panel-designer",
        data={"wells": []},
        schema_version="1.0",
    )

    client.experiments.analysis.save(
        42,
        plugin_id="dose-response",
        result={"ic50": 0.42},
    )

Namespace	Methods
client.experiments.design_data	get, save, delete, tree, summary, export
client.experiments.analysis	list, get, save, delete

Backward-compatible flat methods still exist: get_data, save_data, delete_data, get_data_tree, get_data_summary, export_data, get_results, get_result, save_result, and delete_result.

Errors

The client raises MINTAPIError (and mint_sdk.exceptions subclasses where applicable) on non-2xx responses, parsed from the platform's structured error body:

from mint_sdk import MINTClient
from mint_sdk.client._exceptions import MINTAPIError

with MINTClient() as client:
    try:
        exp = client.experiments.get(99999)
    except MINTAPIError as e:
        print(f"failed: {e}")

Network / timeout errors raise httpx exceptions — wrap in your own retry logic if needed.

Token refresh

MINTClient wires a refresh callback at construction. When a request returns 401 with an expired token, the client attempts auth.refresh() once before re-raising. Long-running scripts get refresh for free; explicit triggers aren't needed.

For genuinely long jobs (CI runs that span days), prefer service-account tokens with longer TTL — generate from Admin → Users → Service accounts in the platform UI.

Pagination

The list methods return plain Python lists after unwrapping the platform response. For page-by-page pulls, pass skip and limit yourself:

with MINTClient() as client:
    all_experiments = []
    skip = 0
    while True:
        batch = client.experiments.list(status="completed", skip=skip, limit=200)
        if not batch:
            break
        all_experiments.extend(batch)
        skip += len(batch)

For very large result sets, prefer querying only what you need — full pulls hit memory limits and lock the platform's connection pool.

Notes

• MINTClient instances are not thread-safe. Use one per thread.
• Inside a plugin, prefer PlatformContext accessors over MINTClient — they share the platform's connection pool, avoid the network hop in shared mode, and short-circuit auth checks for the plugin's user.
• The credentials file (~/.config/mint/credentials.json, or $XDG_CONFIG_HOME/mint/credentials.json) is the user's responsibility to secure (chmod 600); mint auth login sets that automatically.

Related

• Concepts → PlatformContext — the in-process alternative
• CLI reference → mint auth — token management