MedScopeBack
Python 3.10+

MedScope API for Python

The official Python client for sending clinical documents to MedScope without manually building HTTP requests, headers, file uploads or error handling.

bash
pip install medscope-api
View package on PyPI

Quickstart

Install the client from PyPI and extract your first PDF:

python
from medscope import MedScope

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

print(result)

The client sends requests to https://api.medscope.info. Using it as a context manager closes pooled network connections deterministically.

Authentication

Pass your API key directly when creating the client:

python
from medscope import MedScope

client = MedScope(api_key="your_medscope_api_key")

Alternatively, set it once as an environment variable:

bash
export MEDSCOPE_API_KEY="your_medscope_api_key"
python
from medscope import MedScope

client = MedScope()

You can test the API server connection without authentication:

python
print(client.health())

Extract data from a PDF

python
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.

Exclude data blocks

Remove selected entity blocks from the returned structured_data and quality sections:

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

A comma-separated string such as exclude="medication,allergies" is also supported.

Options and flags

Enable optional API features globally on the client:

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

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

Or pass flags for a single request:

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

Request-level flags override client-level flags. Unknown flags are sent as query parameters, so new API flags work without an immediate client update.

Client configuration

The default request timeout is 120 seconds. Configure it for the client or for a single request:

python
client = MedScope(
    api_key="your_medscope_api_key",
    timeout=180,
)

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

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

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

Available methods

client.health()

Checks whether the API server is available.

client.extract(file)

Uploads a PDF and returns the structured extraction result.

Error handling

MedScopeAuthenticationError is raised if no API key is configured for a protected request. MedScopeAPIError is raised for API error responses or unexpected responses.

python
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)
MedScopeAPIError.status_code contains the HTTP status, and MedScopeAPIError.response contains the parsed response. These fields may contain sensitive medical information and should not be logged without appropriate redaction.