MedScope API for Python

Official Python client for the MedScope API.

Use this package if you want to send documents easily to MedScope from Python without building HTTP requests, headers, file uploads, or error handling yourself.

Python 3.10 or newer is required.

The client sends requests to:

https://api.medscope.info

Install

From PyPI:

pip install medscope-api

From this repository:

pip install ./code

If you are already inside the code directory:

pip install .

Set Your API Key

You can pass the API key directly:

from medscope import MedScope

client = MedScope(api_key="your_medscope_api_key")

For applications that make multiple requests, use the client as a context manager so pooled network connections are closed deterministically:

from medscope import MedScope

with MedScope(api_key="your_medscope_api_key") as client:
    result = client.extract("your_doctors_letter.pdf")

Or set it once as an environment variable:

export MEDSCOPE_API_KEY="your_medscope_api_key"

Then create the client without passing the key:

from medscope import MedScope

client = MedScope()

Test The API Server Connection

from medscope import MedScope

client = MedScope()

print(client.health())

Extract Data From A PDF

from medscope import MedScope

client = MedScope(api_key="your_medscope_api_key")

result = client.extract(
    "your_doctors_letter.pdf",
)

print(result)

extract(...) accepts a file path (str or PathLike), PDF bytes, or an open binary file object.

Options

You can enable optional API features with flags:

from medscope import MedScope

client = MedScope(
    api_key="your_medscope_api_key",
    flags={
        "include_fhir": True,
        "include_raw_text": False,
    },
)

result = client.extract(
    "your_doctors_letter.pdf",
)

You can also pass flags for a single request:

result = client.extract(
    "your_doctors_letter.pdf",
    flags={"include_fhir": True},
)

Request-level flags override client-level flags.

Unknown flags are allowed and sent as query parameters. This lets the API support new flags without requiring an immediate client update.

Client Configuration

The default request timeout is 120 seconds. You can configure it globally or for a single request:

client = MedScope(api_key="your_medscope_api_key", timeout=180)
result = client.extract("your_doctors_letter.pdf", timeout=240)

For local development or staging, pass a different API URL:

client = MedScope(
    api_key="your_medscope_api_key",
    base_url="https://staging-api.example.com",
)

Exclude Data Blocks

Use exclude to remove specific entity blocks from the returned structured_data and quality sections:

result = client.extract(
    "your_doctors_letter.pdf",
    exclude=["medication", "allergies"],
)

You can also pass a comma-separated string:

result = client.extract(
    "your_doctors_letter.pdf",
    exclude="medication,allergies",
)

Available Methods

client.health()
client.extract("your_doctors_letter.pdf")

Errors

The client raises MedScopeAuthenticationError if no API key is configured for a protected request.

The client raises MedScopeAPIError if the API returns an error response or an unexpected response.

MedScopeAPIError.status_code contains the HTTP status when one was received, and MedScopeAPIError.response contains the parsed error response. These fields may contain sensitive medical information and should not be logged without appropriate redaction.

from medscope import MedScope, MedScopeAPIError, MedScopeAuthenticationError

client = MedScope(api_key="your_medscope_api_key")

try:
    result = client.extract("your_doctors_letter.pdf")
except MedScopeAuthenticationError:
    print("Missing API key")
except MedScopeAPIError as error:
    print(error)

Development

Use this only if you want to work on the client library itself:

pip install -e ".[dev]"
pytest