imednet

Unofficial Python SDK for the iMednet clinical trials API.

Full documentation: https://fderuiter.github.io/imednet-python-sdk/

This package simplifies integration with the iMednet REST API for clinical trial management. It provides typed endpoint wrappers, helper workflows and a CLI so researchers and developers can automate data extraction and submission without reimplementing HTTP logic.

Features

Simple, consistent interface for API calls
Automatic pagination across endpoints
Pydantic models for requests and responses
Workflow helpers for data extraction and mapping
Pandas and CSV utilities
Optional in-memory caching of study metadata
Structured JSON logging and OpenTelemetry tracing
Async client and command line interface

Architecture

The SDK is organized around a core HTTP client layer, endpoint wrappers that model the iMednet API, workflow helpers that combine multiple endpoint calls, and a CLI built on top of those pieces.

graph TD
    CLI[CLI] --> |invokes| Workflows
    Workflows --> |coordinate| Endpoints
    Endpoints --> |use| Client["(HTTP Client)"]
    Client --> |requests| API

Installation

# PyPI release
pip install imednet
# Dev version
pip install git+https://github.com/fderuiter/imednet-python-sdk.git@main

Quick Start

Synchronous Example

from imednet import ImednetSDK, load_config
from imednet.utils import configure_json_logging

configure_json_logging()
cfg = load_config()
sdk = ImednetSDK(
    api_key=cfg.api_key,
    security_key=cfg.security_key,
    base_url=cfg.base_url,
)
print(sdk.studies.list())

Asynchronous Example

import asyncio
from imednet import AsyncImednetSDK, load_config
from imednet.utils import configure_json_logging


async def main() -> None:
    configure_json_logging()
    cfg = load_config()
    async with AsyncImednetSDK(
        api_key=cfg.api_key,
        security_key=cfg.security_key,
        base_url=cfg.base_url,
    ) as sdk:
        print(await sdk.studies.async_list())


asyncio.run(main())

See docs/async_quick_start.rst for more details.

Configuration

The SDK and CLI read credentials from environment variables such as IMEDNET_API_KEY and IMEDNET_SECURITY_KEY. See configuration for the complete list, optional settings, and .env support. Use imednet.config.load_config() to access these values in your code.

CLI Usage

The package installs an imednet command with subcommands for studies, sites, subjects, records, jobs, queries and more. Use imednet --help to explore all options.

Example of exporting a subset of variables:

imednet export sql MY_STUDY table sqlite:///data.db --vars AGE,SEX --forms 10,20

When the connection string uses SQLite, the command splits the output into one table per form to avoid the 2000 column limit. Pass --single-table to disable this behaviour. See docs/cli.rst for full examples.

Documentation & Resources

API Documentation: Full documentation is available at https://fderuiter.github.io/imednet-python-sdk/.
Official iMednet API Docs: https://portal.prod.imednetapi.com/.
Postman Collection: Download imednet.postman_collection.json and import it into Postman to explore and test the API endpoints.

Development & Contributing

Tech Stack

Python 3.10–3.12
requests, httpx, pydantic, typer, tenacity, python-dotenv

Project Structure

.
├── docs/       - Sphinx documentation
├── examples/   - Usage samples
├── imednet/    - SDK package
├── scripts/    - Helper scripts
└── tests/      - Unit and integration tests

Testing & Development

./scripts/setup.sh  # once
poetry run ruff check --fix .
poetry run black --check .
poetry run isort --check --profile black .
poetry run mypy imednet
poetry run pytest -q

After running tests, validate documentation builds cleanly (no warnings):

make docs

See docs/AGENTS.md for full documentation guidelines.

Smoke-test workflow

The optional smoke.yml action runs the tests/live suite. It relies on repository secrets APIKEY and SECURITYKEY and sets IMEDNET_RUN_E2E. Use the workflow to confirm real API access on demand or via its nightly schedule. INFO-level log messages stream to the terminal during these runs, making it easier to debug failures.

Building & Publishing

python -m build
python -m twine upload dist/*

Pushing a Git tag like v0.1.4 triggers the GitHub Actions workflow that builds and publishes the package to PyPI.

Versioning & Changelog

This project follows Semantic Versioning. See CHANGELOG.md for release history.

Contributing

Contributions are welcome! See the contributing guide and CONTRIBUTING.md for full details.

License

This project is licensed under the MIT license. See LICENSE for details.

Acknowledgements

Built with open source libraries including requests, httpx, pydantic and typer.