Reference

Agent

client.agent.create(...) -> AgentResponse

📝 Description

Creates a new PhenoAgent with specified configuration

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.create(
    name="Medical Assistant",
    description="An AI assistant for medical information processing",
    prompts=[
        "prompt_123"
    ],
    tags=[
        "medical",
        "fhir"
    ],
    provider="7002b0b4-8d09-445a-bf65-0fafdaf26c35",
)

⚙️ Parameters

request: AgentCreateRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agent.list(...) -> ListResponse

📝 Description

Retrieves a list of PhenoAgents belonging to the authenticated user

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.list(
    tags="tags",
)

⚙️ Parameters

tags: typing.Optional[str] — Filter by tags

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agent.get(...) -> AgentResponse

📝 Description

Retrieves a specific agent by its ID

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.get(
    id="id",
)

⚙️ Parameters

id: str — Agent ID

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agent.update(...) -> AgentResponse

📝 Description

Updates an existing agent's configuration

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.update(
    id="id",
    name="Medical Assistant",
    description="Updated description for the medical assistant",
    prompts=[
        "prompt_123"
    ],
    tags=[
        "medical",
        "fhir",
        "updated"
    ],
    provider="7002b0b4-8d09-445a-bf65-0fafdaf26c35",
)

⚙️ Parameters

id: str — Agent ID

request: AgentCreateRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agent.delete(...) -> DeleteResponse

📝 Description

Deletes an existing agent

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.delete(
    id="id",
)

⚙️ Parameters

id: str — Agent ID

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agent.patch(...) -> AgentResponse

📝 Description

Patches an existing agent's configuration

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.agent import JsonPatchOperation

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.patch(
    id="id",
    request=[
        JsonPatchOperation(
            op="replace",
            path="/description",
            value="patched description",
        ),
        JsonPatchOperation(
            op="add",
            path="/tags/-",
            value="updated",
        )
    ],
)

⚙️ Parameters

id: str — Agent ID

request: JsonPatch

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Chat

client.agent.chat.send(...) -> AgentChatResponse

📝 Description

Send a message to an agent and receive a JSON response.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.chat.send(
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    message="What is the patient\'s current condition?",
    session_id="session-abc123",
    agent_id="agent-123",
)

⚙️ Parameters

message: str — The message to send to the agent

agent_id: str — The ID of the agent to chat with

phenoml_on_behalf_of: typing.Optional[str]

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity. Must be in the format: Patient/{uuid} or Practitioner/{uuid}

phenoml_fhir_provider: typing.Optional[str]

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}. Multiple FHIR provider integrations can be provided as comma-separated values.

context: typing.Optional[str] — Optional context for the conversation

session_id: typing.Optional[str] — Optional session ID for conversation continuity. Only one request may be active for a session at a time; overlapping turns for the same session return 409 Conflict.

enhanced_reasoning: typing.Optional[bool] — Enable enhanced reasoning capabilities. Increases latency but improves response quality and reliability.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agent.chat.stream(...) -> typing.Iterator[bytes]

📝 Description

Send a message to an agent and receive the response as a Server-Sent Events (SSE) stream. Events include message_start, content_delta, tool_use, tool_result, message_end, and error.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.chat.stream(
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    message="What is the patient\'s current condition?",
    session_id="session-abc123",
    agent_id="agent-123",
)

⚙️ Parameters

message: str — The message to send to the agent

agent_id: str — The ID of the agent to chat with

phenoml_on_behalf_of: typing.Optional[str]

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity. Must be in the format: Patient/{uuid} or Practitioner/{uuid}

phenoml_fhir_provider: typing.Optional[str]

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}. Multiple FHIR provider integrations can be provided as comma-separated values.

context: typing.Optional[str] — Optional context for the conversation

enhanced_reasoning: typing.Optional[bool] — Enable enhanced reasoning capabilities. Increases latency but improves response quality and reliability.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agent.chat.list_messages(...) -> ListMessagesResponse

📝 Description

Retrieves a list of chat messages for a given chat session

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.chat.list_messages(
    chat_session_id="chat_session_id",
    num_messages=1,
    role="user",
    order="asc",
)

⚙️ Parameters

chat_session_id: str — Chat session ID

num_messages: typing.Optional[int] — Number of messages to return

role: typing.Optional[ListMessagesRequestRole]

Filter by one or more message roles. Multiple roles can be specified as a comma-separated string. If not specified, messages with all roles are returned.

Available roles:

user - Messages from the user
assistant - Text responses from the AI assistant
model - Function/tool call requests from the model
function - Function/tool call results

order: typing.Optional[ListMessagesRequestOrder] — Order of messages

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Agent Prompts

client.agent.prompts.create(...) -> AgentPromptsResponse

📝 Description

Creates a new agent prompt

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.prompts.create(
    name="Medical Assistant System Prompt",
    description="System prompt for medical assistant agent",
    content="You are a helpful medical assistant specialized in FHIR data processing.",
    is_default=False,
    tags=[
        "medical",
        "system"
    ],
)

⚙️ Parameters

name: str — Prompt name

content: str — Prompt content

description: typing.Optional[str] — Prompt description

is_default: typing.Optional[bool] — Whether this is a default prompt

tags: typing.Optional[typing.List[str]] — Tags for categorizing the prompt

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agent.prompts.list() -> PromptsListResponse

📝 Description

Retrieves a list of agent prompts belonging to the authenticated user

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.prompts.list()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agent.prompts.get(...) -> AgentPromptsResponse

📝 Description

Retrieves a specific prompt by its ID

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.prompts.get(
    id="id",
)

⚙️ Parameters

id: str — Prompt ID

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agent.prompts.update(...) -> AgentPromptsResponse

📝 Description

Updates an existing prompt

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.prompts.update(
    id="id",
    name="Medical Assistant System Prompt",
    description="Updated system prompt",
    content="You are a helpful medical assistant. Always cite ICD-10 codes when discussing diagnoses.",
    is_default=False,
    tags=[
        "medical",
        "system",
        "updated"
    ],
)

⚙️ Parameters

id: str — Prompt ID

name: typing.Optional[str] — Prompt name

description: typing.Optional[str] — Prompt description

content: typing.Optional[str] — Prompt content

is_default: typing.Optional[bool] — Whether this is a default prompt

tags: typing.Optional[typing.List[str]] — Tags for categorizing the prompt

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agent.prompts.delete(...) -> PromptsDeleteResponse

📝 Description

Deletes a prompt

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.prompts.delete(
    id="id",
)

⚙️ Parameters

id: str — Prompt ID

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agent.prompts.patch(...) -> AgentPromptsResponse

📝 Description

Patches an existing prompt

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.agent import JsonPatchOperation

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.prompts.patch(
    id="id",
    request=[
        JsonPatchOperation(
            op="replace",
            path="/content",
            value="Updated prompt content.",
        )
    ],
)

⚙️ Parameters

id: str — Agent Prompt ID

request: JsonPatch

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Authtoken

client.authtoken.get_token(...) -> TokenResponse

📝 Description

OAuth 2.0 client credentials token endpoint (RFC 6749 §4.4). Accepts client_id and client_secret in the request body (JSON or form-encoded) or via Basic Auth header (RFC 6749 §2.3.1), and returns an access token with expiration information.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.authtoken.get_token(
    client_id="your_client_id",
    client_secret="your_client_secret",
)

⚙️ Parameters

grant_type: typing.Optional[str] — Must be "client_credentials" if provided

client_id: typing.Optional[str] — The client ID (credential username)

client_secret: typing.Optional[str] — The client secret (credential password)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Cohort

client.cohort.analyze(...) -> CohortResponse

📝 Description

Converts natural language text into structured FHIR search queries for patient cohort analysis

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.cohort.analyze(
    text="female patients over 65 with diabetes but not hypertension",
)

⚙️ Parameters

text: str — Natural language text describing patient cohort criteria

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Code Systems

client.construe.code_systems.upload(...) -> UploadResponse

📝 Description

Upload a custom medical code system with codes and descriptions for use in code extraction. Requires a paid plan. Returns 202 immediately; embedding generation runs asynchronously. Poll GET /construe/codes/systems/{codesystem}?version={version} to check when status transitions from "processing" to "ready" or "failed".

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.construe import CodeResponse

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.code_systems.upload(
    name="CUSTOM_CODES",
    version="1.0",
    format="json",
    codes=[
        CodeResponse(
            code="X001",
            description="Example custom code 1",
        ),
        CodeResponse(
            code="X002",
            description="Example custom code 2",
        )
    ],
)

⚙️ Parameters

name: str

Name of the code system. Names are case-insensitive and stored uppercase. Builtin system names (e.g. ICD-10-CM, SNOMED_CT_US_LITE, LOINC, CPT, etc.) are reserved and cannot be used for custom uploads; attempts return HTTP 403 Forbidden.

version: str — Version of the code system

format: UploadRequestFormat — Upload format

revision: typing.Optional[float] — Optional revision number

file: typing.Optional[str]

The file contents as a base64-encoded string. For CSV format, this is the CSV file contents. For JSON format, this is a base64-encoded JSON array; prefer using 'codes' instead.

code_col: typing.Optional[str] — Column name containing codes (required for CSV format)

desc_col: typing.Optional[str] — Column name containing descriptions (required for CSV format)

defn_col: typing.Optional[str] — Optional column name containing long definitions (for CSV format)

codes: typing.Optional[typing.List[CodeResponse]]

The codes to upload as a JSON array (JSON format only). This is the preferred way to upload JSON codes, as it avoids unnecessary base64 encoding. If both 'codes' and 'file' are provided, 'codes' takes precedence.

replace: typing.Optional[bool]

If true, replaces an existing code system with the same name and version. Builtin systems cannot be replaced; attempts to do so return HTTP 403 Forbidden. When false (default), uploading a duplicate returns 409 Conflict.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.construe.code_systems.list() -> ListCodeSystemsResponse

📝 Description

Returns the terminology server's catalog of available code systems, including both built-in standard terminologies and custom uploaded systems.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.code_systems.list()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.construe.code_systems.find(...) -> GetCodeSystemDetailResponse

📝 Description

Returns full metadata for a single code system, including timestamps and builtin status.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.code_systems.find(
    codesystem="ICD-10-CM",
    version="2025",
)

⚙️ Parameters

codesystem: str — Code system name (e.g., "ICD-10-CM", "SNOMED_CT_US_LITE")

version: typing.Optional[str] — Specific version of the code system. Required if multiple versions exist.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.construe.code_systems.delete(...) -> DeleteCodeSystemResponse

📝 Description

Deletes a custom (non-builtin) code system and all its codes. Builtin systems cannot be deleted. Only available on dedicated instances. Large systems may take up to a minute to delete.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.code_systems.delete(
    codesystem="CUSTOM_CODES",
    version="version",
)

⚙️ Parameters

codesystem: str — Code system name

version: typing.Optional[str] — Specific version of the code system. Required if multiple versions exist.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.construe.code_systems.export(...) -> ExportCodeSystemResponse

📝 Description

Exports a custom (non-builtin) code system as a JSON file compatible with the upload format. The exported file can be re-uploaded directly via POST /construe/upload with format "json". Only available on dedicated instances. Builtin systems cannot be exported.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.code_systems.export(
    codesystem="CUSTOM_CODES",
    version="version",
)

⚙️ Parameters

codesystem: str — Code system name

version: typing.Optional[str] — Specific version of the code system. Required if multiple versions exist.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Construe

client.construe.submit_feedback(...) -> FeedbackResponse

📝 Description

Submits user feedback on results from the Construe extraction endpoint. Feedback includes the full extraction result received and the result the user expected.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.construe import ExtractCodesResult, ExtractRequestSystem, ExtractedCodeResult

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.submit_feedback(
    text="Patient has type 2 diabetes with hyperglycemia",
    received_result=ExtractCodesResult(
        system=ExtractRequestSystem(
            name="ICD-10-CM",
            version="2025",
        ),
        codes=[
            ExtractedCodeResult(
                code="E11.9",
                description="Type 2 diabetes mellitus without complications",
                valid=True,
            )
        ],
    ),
    expected_result=ExtractCodesResult(
        system=ExtractRequestSystem(
            name="ICD-10-CM",
            version="2025",
        ),
        codes=[
            ExtractedCodeResult(
                code="E11.65",
                description="Type 2 diabetes mellitus with hyperglycemia",
                valid=True,
            )
        ],
    ),
    detail="Expected code E11.65 because the text mentions hyperglycemia",
)

⚙️ Parameters

text: str — The natural language text that was used for code extraction

received_result: ExtractCodesResult

expected_result: ExtractCodesResult

detail: typing.Optional[str] — Optional details explaining the feedback

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Codes

client.construe.codes.extract(...) -> ExtractCodesResult

📝 Description

Converts natural language text into structured medical codes.

Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.construe import ExtractRequestSystem

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.codes.extract(
    text="Patient is a 14-year-old female, previously healthy, who is here for evaluation of abnormal renal ultrasound with atrophic right kidney.",
    system=ExtractRequestSystem(
        name="ICD-10-CM",
        version="2025",
    ),
)

⚙️ Parameters

text: str — Natural language text to extract codes from

system: typing.Optional[ExtractRequestSystem]

config: typing.Optional[ExtractRequestConfig]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.construe.codes.list(...) -> ListCodesResponse

📝 Description

Returns a paginated list of all codes in the specified code system from the terminology server.

Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.codes.list(
    codesystem="ICD-10-CM",
    version="2025",
    cursor="cursor",
    limit=1,
)

⚙️ Parameters

codesystem: str — Code system name (e.g., "ICD-10-CM", "SNOMED_CT_US_LITE")

version: typing.Optional[str] — Specific version of the code system. Required if multiple versions exist.

cursor: typing.Optional[str] — Pagination cursor from previous response

limit: typing.Optional[int] — Maximum number of codes to return (default 20)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.construe.codes.lookup(...) -> GetCodeResponse

📝 Description

Looks up a specific code in the terminology server and returns its details.

Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.codes.lookup(
    codesystem="ICD-10-CM",
    code_id="E1165",
    version="version",
)

⚙️ Parameters

codesystem: str — Code system name

code_id: str

The code identifier. ICD-10-CM codes are stored without their cosmetic dot (use "E1165", not "E11.65").

version: typing.Optional[str] — Specific version of the code system

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.construe.codes.search_semantic(...) -> SemanticSearchResponse

📝 Description

Performs semantic similarity search using vector embeddings.

Availability: This endpoint works for both built-in and custom code systems.

When to use: Best for natural language queries where you want to find conceptually related codes, even when different terminology is used. The search understands meaning, not just keywords.

Examples:

Query "trouble breathing at night" finds codes like "Sleep apnea", "Orthopnea", "Nocturnal dyspnea" — semantically related but no exact keyword matches
Query "heart problems" finds "Myocardial infarction", "Cardiac arrest", "Arrhythmia"

Trade-offs: Slower than text search (requires embedding generation), but finds conceptually similar results that keyword search would miss.

See also: /search/text for faster keyword-based lookup with typo tolerance.

Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.codes.search_semantic(
    codesystem="ICD-10-CM",
    text="patient has trouble breathing at night and wakes up gasping",
    version="version",
    limit=1,
)

⚙️ Parameters

codesystem: str — Code system name

text: str — Natural language text to find semantically similar codes for

version: typing.Optional[str] — Specific version of the code system

limit: typing.Optional[int] — Maximum number of results (default 10, max 50)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.construe.codes.search_text(...) -> TextSearchResponse

📝 Description

Performs fast full-text search over code IDs and descriptions.

Availability: This endpoint is only available for built-in code systems. Custom code systems uploaded via /construe/upload are not indexed for full-text search and will return empty results. Use /search/semantic to search custom code systems.

When to use: Best for autocomplete UIs, code lookup, or when users know part of the code ID or specific keywords. Fast response times suitable for typeahead interfaces.

Features:

Substring matching on code IDs (e.g., "11.65" finds "E11.65")
Typo tolerance on descriptions (not on code IDs)
Fast response times (~10-50ms)

Examples:

Query "E11" finds all codes starting with E11 (diabetes codes)
Query "diabtes" (typo) still finds "diabetes" codes

Trade-offs: Faster than semantic search, but only matches keywords/substrings. Won't find conceptually related codes with different terminology.

See also: /search/semantic for finding conceptually similar codes.

Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.codes.search_text(
    codesystem="ICD-10-CM",
    q="E11.65",
    version="version",
    limit=1,
)

⚙️ Parameters

codesystem: str — Code system name

q: str — Search query (searches code IDs and descriptions)

version: typing.Optional[str] — Specific version of the code system

limit: typing.Optional[int] — Maximum number of results (default 20, max 100)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Fhir

client.fhir.search(...) -> typing.Any

📝 Description

Retrieves FHIR resources from the specified provider. Supports both individual resource retrieval (e.g. Patient/123 via the path) and search operations.

FHIR search parameters are passed through to the upstream server verbatim as native query-string parameters; this proxy does not model, validate, or transform them. Append standard FHIR search parameters directly to the request URL. Supported parameters include:

Resource-specific search parameters (e.g. name for Patient, status for Observation)
Common search parameters (_id, _lastUpdated, _tag, _profile, _security, _text, _content, _filter)
Result parameters (_count, _offset, _sort, _include, _revinclude, _summary, _elements)
Search prefixes for dates, numbers, and quantities (eq, ne, gt, ge, lt, le, sa, eb, ap)

Examples:

Patient?name=John%20Doe&_count=10&_sort=family
Observation?patient=Patient/123&date=ge2023-01-01&category=vital-signs&_sort=-date

When using a generated SDK, supply these via the client's request-level query-parameter option (the SDK escape hatch) rather than a typed argument.

The request is proxied to the configured FHIR server with appropriate authentication headers.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir.search(
    fhir_provider_id="550e8400-e29b-41d4-a716-446655440000",
    fhir_path="Patient",
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
)

⚙️ Parameters

fhir_provider_id: str

The ID of the FHIR provider to use. Can be either:

A UUID representing the provider ID
A provider name (legacy support - will just use the most recently updated provider with this name)

fhir_path: str

The FHIR resource path to operate on. This follows FHIR RESTful API conventions. Examples:

"Patient" (for resource type operations)
"Patient/123" (for specific resource operations)
"Patient/123/_history" (for history operations)

phenoml_on_behalf_of: typing.Optional[str]

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity. Must be in the format: Patient/{uuid} or Practitioner/{uuid}

phenoml_fhir_provider: typing.Optional[str]

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}. Multiple FHIR provider integrations can be provided as comma-separated values.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.fhir.create(...) -> typing.Any

📝 Description

Creates a new FHIR resource on the specified provider. The request body should contain a valid FHIR resource in JSON format.

The request is proxied to the configured FHIR server with appropriate authentication headers.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir.create(
    fhir_provider_id="550e8400-e29b-41d4-a716-446655440000",
    fhir_path="Patient",
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    request={"resourceType": "Patient"},
)

⚙️ Parameters

fhir_provider_id: str

The ID of the FHIR provider to use. Can be either:

A UUID representing the provider ID
A provider name (legacy support - will just use the most recently updated provider with this name)

fhir_path: str

The FHIR resource path to operate on. This follows FHIR RESTful API conventions. Examples:

"Patient" (for resource type operations)
"Patient/123" (for specific resource operations)
"Patient/123/_history" (for history operations)

request: typing.Any

phenoml_on_behalf_of: typing.Optional[str]

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity. Must be in the format: Patient/{uuid} or Practitioner/{uuid}

phenoml_fhir_provider: typing.Optional[str]

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}. Multiple FHIR provider integrations can be provided as comma-separated values.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.fhir.upsert(...) -> typing.Any

📝 Description

Creates or updates a FHIR resource on the specified provider. If the resource exists, it will be updated; otherwise, it will be created.

The request is proxied to the configured FHIR server with appropriate authentication headers.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir.upsert(
    fhir_provider_id="550e8400-e29b-41d4-a716-446655440000",
    fhir_path="Patient",
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    request={"resourceType": "Patient", "id": "123"},
)

⚙️ Parameters

fhir_provider_id: str

The ID of the FHIR provider to use. Can be either:

A UUID representing the provider ID
A provider name (legacy support - will just use the most recently updated provider with this name)

fhir_path: str

The FHIR resource path to operate on. This follows FHIR RESTful API conventions. Examples:

"Patient" (for resource type operations)
"Patient/123" (for specific resource operations)
"Patient/123/_history" (for history operations)

request: typing.Any

phenoml_on_behalf_of: typing.Optional[str]

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity. Must be in the format: Patient/{uuid} or Practitioner/{uuid}

phenoml_fhir_provider: typing.Optional[str]

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}. Multiple FHIR provider integrations can be provided as comma-separated values.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.fhir.delete(...) -> typing.Any

📝 Description

Deletes a FHIR resource from the specified provider.

The request is proxied to the configured FHIR server with appropriate authentication headers.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir.delete(
    fhir_provider_id="550e8400-e29b-41d4-a716-446655440000",
    fhir_path="Patient",
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
)

⚙️ Parameters

fhir_provider_id: str

The ID of the FHIR provider to use. Can be either:

A UUID representing the provider ID
A provider name (legacy support - will just use the most recently updated provider with this name)

fhir_path: str

The FHIR resource path to operate on. This follows FHIR RESTful API conventions. Examples:

"Patient" (for resource type operations)
"Patient/123" (for specific resource operations)
"Patient/123/_history" (for history operations)

phenoml_on_behalf_of: typing.Optional[str]

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity. Must be in the format: Patient/{uuid} or Practitioner/{uuid}

phenoml_fhir_provider: typing.Optional[str]

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}. Multiple FHIR provider integrations can be provided as comma-separated values.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.fhir.patch(...) -> typing.Any

📝 Description

Partially updates a FHIR resource on the specified provider.

Two body formats are supported, selected by request content type:

application/json-patch+json — an array of JSON Patch operations as defined in RFC 6902. Each operation specifies:
- op: The operation type (add, remove, replace, move, copy, test)
- path: JSON Pointer to the target location in the resource
- value: The value to use (required for add, replace, and test operations)
application/fhir+json — a partial FHIR resource for merge-patch semantics.

Note: This proxy currently forwards the request body to the upstream FHIR server with Content-Type: application/fhir+json regardless of the declared request content type. JSON Patch (RFC 6902) therefore only succeeds against upstream servers that accept patch arrays under application/fhir+json; servers that strictly enforce patch media types may reject or misinterpret it. Support for either format ultimately depends on the upstream FHIR server.

The request is proxied to the configured FHIR server with appropriate authentication headers.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.fhir import PatchRequestBodyItem

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir.patch(
    fhir_provider_id="550e8400-e29b-41d4-a716-446655440000",
    fhir_path="Patient",
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    request=[
        PatchRequestBodyItem(
            op="replace",
            path="/name/0/family",
            value="NewFamilyName",
        )
    ],
)

⚙️ Parameters

fhir_provider_id: str

The ID of the FHIR provider to use. Can be either:

A UUID representing the provider ID
A provider name (legacy support - will just use the most recently updated provider with this name)

fhir_path: str

The FHIR resource path to operate on. This follows FHIR RESTful API conventions. Examples:

"Patient" (for resource type operations)
"Patient/123" (for specific resource operations)
"Patient/123/_history" (for history operations)

request: typing.List[PatchRequestBodyItem] — Array of JSON Patch operations following RFC 6902

phenoml_on_behalf_of: typing.Optional[str]

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity. Must be in the format: Patient/{uuid} or Practitioner/{uuid}

phenoml_fhir_provider: typing.Optional[str]

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}. Multiple FHIR provider integrations can be provided as comma-separated values.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.fhir.execute_bundle(...) -> typing.Any

📝 Description

Executes a FHIR Bundle transaction or batch operation on the specified provider. This allows multiple FHIR resources to be processed in a single request.

The request body should contain a valid FHIR Bundle resource with transaction or batch type.

The request is proxied to the configured FHIR server with appropriate authentication headers.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir.execute_bundle(
    fhir_provider_id="550e8400-e29b-41d4-a716-446655440000",
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    request={"resourceType": "Bundle", "type": "transaction", "entry": [{"request": {"method": "POST", "url": "Patient"}, "resource": {"resourceType": "Patient", "name": [{"family": "Doe", "given": ["John"]}]}}, {"request": {"method": "POST", "url": "Observation"}, "resource": {"resourceType": "Observation", "status": "final", "subject": {"reference": "Patient/123"}}}]},
)

⚙️ Parameters

fhir_provider_id: str

The ID of the FHIR provider to use. Can be either:

A UUID representing the provider ID
A provider name (legacy support - will just use the most recently updated provider with this name)

request: typing.Any

phenoml_on_behalf_of: typing.Optional[str]

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity. Must be in the format: Patient/{uuid} or Practitioner/{uuid}

phenoml_fhir_provider: typing.Optional[str]

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}. Multiple FHIR provider integrations can be provided as comma-separated values.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Fhir2Omop

client.fhir2omop.create(...) -> CreateOmopResponse

📝 Description

Maps a FHIR R4 resource or Bundle into OMOP Common Data Model v5.4 rows (person, visit_occurrence, condition_occurrence, drug_exposure, procedure_occurrence, measurement, observation).

Resource support is intentionally limited to the OMOP tables returned by this endpoint:

Patient -> person
Encounter -> visit_occurrence
Condition -> condition_occurrence
Procedure -> procedure_occurrence
MedicationRequest, MedicationStatement, and MedicationAdministration -> drug_exposure
Immunization -> drug_exposure
Observation with a numeric valueQuantity, valueInteger, or numeric-looking valueString (for example "<2") -> measurement
non-numeric Observation -> observation
AllergyIntolerance -> observation

Medication is supported only as reference data for medication resources; it is not emitted as its own row because OMOP CDM has no Medication table. Other reference/admin resources such as Practitioner, Organization, Location, Coverage, and Claim, and clinical workflow/document resources such as DiagnosticReport, ServiceRequest, CarePlan, DocumentReference, Composition, Specimen, and DeviceUseStatement, are currently accepted in a Bundle but are not shaped into OMOP rows. Unsupported resource types are ignored rather than listed under dropped; dropped is reserved for supported resource types that were missing the subject/patient, code, or medication reference data needed to produce a valid row.

Each resource's primary clinical coding is resolved to a standard OMOP concept_id. Alongside the OMOP rows grouped by table (tables), the response carries mappings (how each source coding resolved, linked back to the row it produced), dropped (resources that could not be shaped into a row), vocab_version (the OMOP vocabulary release codes were resolved against), and a small summary of the resolution outcomes.

A concept_id of 0 is reported, not omitted (OMOP "no matching concept" semantics): it covers both a coding with no standard match (UNMAPPED) and an unverified suggestion for a text-only resource (UNCHECKED). Only the primary clinical coding is resolved, so gender/race/ethnicity/visit/value/unit concept_ids are always 0; the one populated non-resolved concept is measurement operator_concept_id, set from a value comparator (<, <=, >, >=) rather than the resolver. Each *_source_value carries the verbatim FHIR coding (system#code), and *_type_concept_id is set to 32817 (EHR).

Medication codes are resolved whether they appear inline (medicationCodeableConcept) or via a medicationReference to a contained, relative (Type/id), or bundle-entry (urn:uuid) Medication resource. Resources that cannot be shaped into a row — a medication with no usable code, resolvable reference, or display, or any clinical resource whose subject/patient reference cannot be tied to a person — are reported under dropped rather than emitted as blank rows. The bundle must contain at least one Patient resource.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir2omop.create(
    fhir_resources={
        "resourceType": "Bundle",
        "type": "collection",
        "entry": [{"resource": {"resourceType": "Patient", "id": "patient-1", "gender": "female", "birthDate": "1985-07-22"}}, {"resource": {"resourceType": "Condition", "id": "condition-1", "subject": {"reference": "Patient/patient-1"}, "code": {"coding": [{"system": "http://snomed.info/sct", "code": "44054006", "display": "Type 2 diabetes mellitus"}]}, "onsetDateTime": "2024-01-15"}}, {"resource": {"resourceType": "MedicationRequest", "id": "medreq-1", "status": "active", "subject": {"reference": "Patient/patient-1"}, "medicationReference": {"reference": "#med0"}, "authoredOn": "2024-01-16", "contained": [{"resourceType": "Medication", "id": "med0", "code": {"coding": [{"system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "860975", "display": "metformin hydrochloride 500 MG"}]}}]}}]
    },
)

⚙️ Parameters

fhir_resources: typing.Dict[str, typing.Any]

FHIR resources (single resource or Bundle). Must contain at least one Patient resource. Supported row-producing resources are Patient, Encounter, Condition, Procedure, MedicationRequest, MedicationStatement, MedicationAdministration, Immunization, Observation, and AllergyIntolerance. Standalone Medication resources are consumed by medication references rather than mapped to their own table. Other resource types are accepted but ignored.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

FhirProvider

client.fhir_provider.create(...) -> FhirProviderResponse

📝 Description

Creates a new FHIR provider configuration with authentication credentials.

Note: The "sandbox" provider type cannot be created via this API - it is managed internally.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.fhir_provider import FhirProviderCreateRequestAuth_ClientSecret

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir_provider.create(
    name="Epic Sandbox",
    description="Epic sandbox environment for testing",
    provider="epic",
    base_url="https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4",
    auth=FhirProviderCreateRequestAuth_ClientSecret(
        client_id="your-client-id",
        client_secret="your-client-secret",
    ),
)

⚙️ Parameters

name: str — Display name for the FHIR provider

provider: Provider

base_url: str — Base URL of the FHIR server

auth: FhirProviderCreateRequestAuth

description: typing.Optional[str] — Optional description of the FHIR provider

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.fhir_provider.list() -> FhirProviderListResponse

📝 Description

Retrieves a list of all active FHIR providers for the authenticated user.

On shared instances, only sandbox providers are returned. Sandbox providers return FhirProviderSandboxInfo.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir_provider.list()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.fhir_provider.get(...) -> FhirProviderResponse

📝 Description

Retrieves a specific FHIR provider configuration by its ID.

Sandbox providers return FhirProviderSandboxInfo. On shared instances, only sandbox providers can be accessed.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir_provider.get(
    fhir_provider_id="fhir_provider_id",
)

⚙️ Parameters

fhir_provider_id: str — ID of the FHIR provider to retrieve

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.fhir_provider.delete(...) -> DeleteResponse

📝 Description

Deletes a FHIR provider.

Note: Sandbox providers cannot be deleted.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir_provider.delete(
    fhir_provider_id="fhir_provider_id",
)

⚙️ Parameters

fhir_provider_id: str — ID of the FHIR provider to delete

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Auth Config

client.fhir_provider.auth_config.add(...) -> FhirProviderResponse

📝 Description

Adds a new authentication configuration to an existing FHIR provider. This enables key rotation and multiple auth configurations per provider.

Note: Sandbox providers cannot be modified.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.fhir_provider import FhirProviderAddAuthConfigRequest_ClientSecret

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir_provider.auth_config.add(
    fhir_provider_id="1716d214-de93-43a4-aa6b-a878d864e2ad",
    request=FhirProviderAddAuthConfigRequest_ClientSecret(
        client_id="your-client-id",
        client_secret="your-client-secret",
    ),
)

⚙️ Parameters

fhir_provider_id: str — ID of the FHIR provider to add auth config to

request: FhirProviderAddAuthConfigRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.fhir_provider.auth_config.set_active(...) -> FhirProviderResponse

📝 Description

Sets which authentication configuration should be active for a FHIR provider. Only one auth config can be active at a time.

If the specified auth config is already active, the request succeeds without making any changes and returns a message indicating the config is already active.

Note: Sandbox providers cannot be modified.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir_provider.auth_config.set_active(
    fhir_provider_id="1716d214-de93-43a4-aa6b-a878d864e2ad",
    auth_config_id="auth-config-456",
)

⚙️ Parameters

fhir_provider_id: str — ID of the FHIR provider

auth_config_id: str — ID of the auth configuration to set as active

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.fhir_provider.auth_config.remove(...) -> RemoveResponse

📝 Description

Removes an authentication configuration from a FHIR provider. Cannot remove the currently active auth configuration.

Note: Sandbox providers cannot be modified.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir_provider.auth_config.remove(
    fhir_provider_id="1716d214-de93-43a4-aa6b-a878d864e2ad",
    auth_config_id="auth-config-456",
)

⚙️ Parameters

fhir_provider_id: str — ID of the FHIR provider

auth_config_id: str — ID of the auth configuration to remove

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Lang2Fhir

client.lang2fhir.create(...) -> FhirResource

📝 Description

Converts natural language text into a structured FHIR resource.

Patient identifier handling. When generating a patient (or patient-canvas) resource, US Core requires Patient.identifier (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with system: "urn:phenoml:lang2fhir-generated-id" and a UUID value so the resource remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir.create(
    version="R4",
    resource="condition-encounter-diagnosis",
    text="Patient has severe persistent asthma with acute exacerbation",
)

⚙️ Parameters

version: str — FHIR version to use

resource: CreateRequestResource — Type of FHIR resource to create. Use 'auto' for automatic resource type detection, or specify a supported US Core profile. Recommended to use the supported US Core Profiles for validated results but you can also use any custom profile you've uploaded (if you're a develop or launch customer)

text: str — Natural language text to convert

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.lang2fhir.create_multi(...) -> CreateMultiResponse

📝 Description

Analyzes natural language text and extracts multiple FHIR resources, returning them as a transaction Bundle. Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types from the text. Resources are linked with proper references (e.g., Conditions reference the Patient).

Patient identifier handling. US Core requires Patient.identifier (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with system: "urn:phenoml:lang2fhir-generated-id" and a UUID value so the bundle remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir.create_multi(
    text="John Smith, 45-year-old male, diagnosed with Type 2 Diabetes. Prescribed Metformin 500mg twice daily. Blood pressure 140/90.",
    version="R4",
)

⚙️ Parameters

text: str — Natural language text containing multiple clinical concepts to extract

version: typing.Optional[str] — FHIR version to use

provider: typing.Optional[str] — Optional FHIR provider name for provider-specific profiles

implementation_guide: typing.Optional[str] — Custom Implementation Guide name. When specified, profiles from this IG are included alongside US Core profiles during resource detection. US Core is always the base layer; custom IG profiles are additive.

detection_effort: typing.Optional[CreateMultiRequestDetectionEffort] — Detection effort. 'standard' runs detection once, 'deep' runs detection multiple times for higher recall.

validation_method: typing.Optional[CreateMultiRequestValidationMethod] — FHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.lang2fhir.search(...) -> SearchResponse

📝 Description

Converts natural language text into FHIR search parameters. Automatically identifies the appropriate FHIR resource type and generates valid search query parameters.

Supported resource types include: AllergyIntolerance, Appointment, CarePlan, CareTeam, Condition, Coverage, Device, DiagnosticReport, DocumentReference, Encounter, Goal, Immunization, Location, Medication, MedicationRequest, Observation, Organization, Patient, PlanDefinition, Practitioner, PractitionerRole, Procedure, Provenance, Questionnaire, QuestionnaireResponse, RelatedPerson, Schedule, ServiceRequest, Slot, and Specimen.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir.search(
    text="Appointments between March 2-9, 2025",
)

⚙️ Parameters

text: str

Natural language text to convert into FHIR search parameters. The system will automatically identify the appropriate resource type and generate valid search parameters.

Examples:

"Appointments between March 2-9, 2025" → Appointment search with date range
"Patients with diabetes" → Condition search with code parameter
"Active medication requests for metformin" → MedicationRequest search
"Lab results for creatinine" → DiagnosticReport search
"Dr. Smith's schedule" → Practitioner or Schedule search

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.lang2fhir.upload_profile(...) -> UploadProfileResponse

📝 Description

Upload a custom FHIR StructureDefinition profile for use with the lang2fhir service.

All metadata is derived from the StructureDefinition JSON itself. The lowercase id field from the StructureDefinition is used as the profile's unique identifier and lookup key. To use the uploaded profile with /lang2fhir/create, pass this id as the resource parameter.

Uploads will be rejected if:

A built-in US Core or R4 base profile already exists with the same id
A custom profile with the same id has already been uploaded
A custom profile with the same url has already been uploaded

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir.upload_profile(
    profile="eyJyZXNvdXJjZVR5cGUiOiJTdHJ1Y3R1cmVEZWZpbml0aW9uIiwiaWQiOiJjdXN0b20tcGF0aWVudCIsInVybCI6Imh0dHA6Ly9waGVub21sLmNvbS9maGlyL1N0cnVjdHVyZURlZmluaXRpb24vY3VzdG9tLXBhdGllbnQiLCJuYW1lIjoiQ3VzdG9tUGF0aWVudCIsInN0YXR1cyI6ImFjdGl2ZSIsImZoaXJWZXJzaW9uIjoiNC4wLjEiLCJraW5kIjoicmVzb3VyY2UiLCJhYnN0cmFjdCI6ZmFsc2UsInR5cGUiOiJQYXRpZW50IiwiYmFzZURlZmluaXRpb24iOiJodHRwOi8vaGw3Lm9yZy9maGlyL1N0cnVjdHVyZURlZmluaXRpb24vUGF0aWVudCIsImRlcml2YXRpb24iOiJjb25zdHJhaW50Iiwic25hcHNob3QiOnsiZWxlbWVudCI6W3siaWQiOiJQYXRpZW50IiwicGF0aCI6IlBhdGllbnQiLCJtaW4iOjAsIm1heCI6IioifSx7ImlkIjoiUGF0aWVudC5uYW1lIiwicGF0aCI6IlBhdGllbnQubmFtZSIsIm1pbiI6MSwibWF4IjoiKiJ9XX19Cg==",
    implementation_guide="acme-cardiology",
    profile_context="When clinical text describes cardiology-specific findings, prefer this profile over the generic US Core Condition.",
)

⚙️ Parameters

profile: str — Base64 encoded JSON string of a FHIR StructureDefinition. The profile must include id, url, type, and a snapshot with elements. All metadata (version, resource type, identifier) is derived from the StructureDefinition itself. The lowercase id from the StructureDefinition becomes the profile's lookup key.

implementation_guide: typing.Optional[str] — Implementation Guide name to group this profile under. Defaults to "custom" if omitted. Cannot be "us_core" (reserved). Use this to organize custom profiles into named IGs that can be referenced when calling create/multi or document/multi endpoints.

profile_context: typing.Optional[str] — Natural language context that helps the LLM select the right profiles from this implementation guide during resource detection. For example, "When the text mentions phenotypic features or abnormalities, prefer the hpo-observation profile over Condition." This is stored as IG-level metadata and injected into the LLM prompt. Max 2000 characters. Providing this field on any upload will update the context for the entire IG (last write wins).

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.lang2fhir.document(...) -> FhirResource

📝 Description

Extracts text from a document (PDF or image) and converts it into a structured FHIR resource.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir.document(
    version="R4",
    resource="questionnaire",
    content="JVBERi0xLjQKJeLjz9MK...(base64-encoded PDF or image bytes)",
)

⚙️ Parameters

version: str — FHIR version to use

resource: str — Type of FHIR resource to create. Accepts any FHIR resource type or US Core profile name.

content: str

Base64 encoded file content. Supported file types: PDF (application/pdf), PNG (image/png), JPEG (image/jpeg). File type is auto-detected from content magic bytes.

config: typing.Optional[DocumentConfig]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.lang2fhir.document_multi(...) -> DocumentMultiResponse

📝 Description

Extracts text from a document (PDF or image) and converts it into multiple FHIR resources, returned as a transaction Bundle. Combines document text extraction with multi-resource detection. Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types. Resources are linked with proper references (e.g., Conditions reference the Patient).

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir.document_multi(
    version="R4",
    content="JVBERi0xLjQKJeLjz9MK...(base64-encoded PDF or image bytes)",
    provider="medplum",
)

⚙️ Parameters

version: str — FHIR version to use

content: str

Base64 encoded file content. Supported file types: PDF (application/pdf), PNG (image/png), JPEG (image/jpeg). File type is auto-detected from content magic bytes.

provider: typing.Optional[str] — Optional FHIR provider name for provider-specific profiles

detection_effort: typing.Optional[DocumentMultiRequestDetectionEffort] — Detection effort. 'standard' runs detection once, 'deep' runs detection multiple times for higher recall.

validation_method: typing.Optional[DocumentMultiRequestValidationMethod] — FHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips.

config: typing.Optional[DocumentConfig]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Templates

client.summary.templates.list() -> ListResponse

📝 Description

Retrieves all summary templates for the authenticated user

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.summary.templates.list()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.summary.templates.create(...) -> CreateSummaryTemplateResponse

📝 Description

Creates a summary template from an example using LLM function calling

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.summary.templates.create(
    name="Discharge Summary",
    example_summary="Patient John Doe, age 45, was admitted on 2024-01-10 with Type 2 Diabetes. Discharged on 2024-01-15 with Metformin 500mg BID.",
    target_resources=[
        "Patient",
        "Condition",
        "MedicationRequest"
    ],
    mode="narrative",
)

⚙️ Parameters

name: str — Name of the template

example_summary: str — Example summary note to generate template from

target_resources: typing.List[str] — List of target FHIR resources

mode: str — Template mode (stored with the template)

description: typing.Optional[str] — Description of the template

example_fhir_data: typing.Optional[typing.Dict[str, typing.Any]] — Optional example FHIR data that corresponds to the example summary

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.summary.templates.get(...) -> GetResponse

📝 Description

Retrieves a specific summary template

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.summary.templates.get(
    id="id",
)

⚙️ Parameters

id: str — Template ID

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.summary.templates.update(...) -> UpdateResponse

📝 Description

Updates an existing summary template

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.summary.templates.update(
    id="id",
    name="Discharge Summary",
    template="Patient {{Patient.name[0].text}} was discharged on {{Encounter[0].period.end}} with {{MedicationRequest[0].medicationCodeableConcept.coding[0].display}} {{MedicationRequest[0].dosageInstruction[0].text}}.",
    target_resources=[
        "Patient",
        "Encounter",
        "MedicationRequest"
    ],
    mode="narrative",
)

⚙️ Parameters

id: str — Template ID

name: str

template: str — Updated template with placeholders

target_resources: typing.List[str]

mode: str — Template mode

description: typing.Optional[str]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.summary.templates.delete(...) -> DeleteResponse

📝 Description

Deletes a summary template

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.summary.templates.delete(
    id="id",
)

⚙️ Parameters

id: str — Template ID

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Summary

client.summary.create(...) -> CreateSummaryResponse

📝 Description

Creates a summary from FHIR resources using one of three modes:

narrative: Uses a template to substitute FHIR data into placeholders (requires template_id)
flatten: Flattens FHIR resources into a searchable format for RAG/search (no template needed)
ips: Generates an International Patient Summary (IPS) narrative per ISO 27269/HL7 FHIR IPS IG. Requires a Bundle with exactly one Patient resource (returns 400 error if no Patient or multiple Patients are present). Automatically filters resources to those referencing the patient and generates sections for allergies, medications, problems, immunizations, procedures, and vital signs.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.summary.create(
    mode="narrative",
    template_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    fhir_resources={
        "resourceType": "Bundle",
        "type": "collection",
        "entry": [{"resource": {"resourceType": "Patient", "name": [{"given": ["John"], "family": "Doe"}], "gender": "male", "birthDate": "1979-03-15"}}, {"resource": {"resourceType": "Condition", "code": {"text": "Type 2 Diabetes Mellitus"}, "onsetDateTime": "2024-01-15"}}]
    },
)

⚙️ Parameters

fhir_resources: typing.Dict[str, typing.Any]

FHIR resources (single resource or Bundle). For IPS mode, must be a Bundle containing exactly one Patient resource with at least one identifier (id, fullUrl, or identifier field). Returns an error if no Patient is found, if multiple Patients are present, or if the Patient has no identifiers. Resources are automatically filtered to only include those referencing the patient.

mode: typing.Optional[CreateSummaryRequestMode]

Summary generation mode:

narrative: Substitute FHIR data into a template (requires template_id)
flatten: Flatten FHIR resources for RAG/search (no template needed)
ips: Generate International Patient Summary (IPS) narrative per ISO 27269/HL7 FHIR IPS IG

template_id: typing.Optional[str] — ID of the template to use (required for narrative mode)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Tools

client.tools.create_fhir_resource(...) -> Lang2FhirAndCreateResponse

📝 Description

Converts natural language to FHIR resource and optionally stores it in a FHIR server

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.create_fhir_resource(
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    resource="condition-encounter-diagnosis",
    text="Patient has severe persistent asthma with acute exacerbation",
    provider="550e8400-e29b-41d4-a716-446655440000",
)

⚙️ Parameters

resource: Lang2FhirAndCreateRequestResource — Type of FHIR resource to create. Use 'auto' for automatic resource type detection, or specify a supported US Core profile.

text: str — Natural language text to convert to FHIR resource

phenoml_on_behalf_of: typing.Optional[str]

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity. Must be in the format: Patient/{uuid} or Practitioner/{uuid}

phenoml_fhir_provider: typing.Optional[str]

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}. Multiple FHIR provider integrations can be provided as comma-separated values.

provider: typing.Optional[str] — FHIR provider ID - must be a valid UUID from existing FHIR providers. also supports provider by name (e.g. medplum)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.create_fhir_resources_multi(...) -> Lang2FhirAndCreateMultiResponse

📝 Description

Extracts multiple FHIR resources from natural language text and stores them in a FHIR server. Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types. Resources are linked with proper references and submitted as a transaction bundle. For FHIR servers that don't auto-resolve urn:uuid references, this endpoint will automatically resolve them via PUT requests after the initial bundle creation.

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.create_fhir_resources_multi(
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    text="John Smith, 45-year-old male, diagnosed with Type 2 Diabetes. Prescribed Metformin 500mg twice daily.",
    version="R4",
    provider="medplum",
)

⚙️ Parameters

text: str — Natural language text containing multiple clinical concepts to extract

provider: str — FHIR provider ID or name

phenoml_on_behalf_of: typing.Optional[str]

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity. Must be in the format: Patient/{uuid} or Practitioner/{uuid}

phenoml_fhir_provider: typing.Optional[str]

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}. Multiple FHIR provider integrations can be provided as comma-separated values.

version: typing.Optional[str] — FHIR version to use

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.search_fhir_resources(...) -> Lang2FhirAndSearchResponse

📝 Description

Converts natural language to FHIR search parameters and executes search in FHIR server

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.search_fhir_resources(
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    text="Find all appointments for patient John Doe next week",
    count=10,
    provider="550e8400-e29b-41d4-a716-446655440000",
)

⚙️ Parameters

text: str — Natural language text to convert to FHIR search parameters

phenoml_on_behalf_of: typing.Optional[str]

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity. Must be in the format: Patient/{uuid} or Practitioner/{uuid}

phenoml_fhir_provider: typing.Optional[str]

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}. Multiple FHIR provider integrations can be provided as comma-separated values.

patient_id: typing.Optional[str] — Patient ID to filter results

count: typing.Optional[int] — Maximum number of results to return

provider: typing.Optional[str] — FHIR provider ID - must be a valid UUID from existing FHIR providers. also supports provider by name (e.g. medplum)

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.analyze_cohort(...) -> CohortResponse

📝 Description

Uses LLM to extract search concepts from natural language and builds patient cohorts with inclusion/exclusion criteria

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.analyze_cohort(
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    text="female patients over 20 with diabetes but not hypertension",
    provider="550e8400-e29b-41d4-a716-446655440000",
)

⚙️ Parameters

text: str — Natural language text describing the patient cohort criteria

provider: str — FHIR provider ID - must be a valid UUID from existing FHIR providers. also supports provider by name (e.g. medplum)

phenoml_on_behalf_of: typing.Optional[str]

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity. Must be in the format: Patient/{uuid} or Practitioner/{uuid}

phenoml_fhir_provider: typing.Optional[str]

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}. Multiple FHIR provider integrations can be provided as comma-separated values.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

MCP Servers

client.tools.mcp_servers.create(...) -> McpServerResponse

📝 Description

Creates a new MCP server

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.mcp_servers.create(
    name="My MCP Server",
    mcp_server_url="https://mcp.example.com",
)

⚙️ Parameters

name: str — Name of the MCP server

mcp_server_url: str — URL of the MCP server

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.mcp_servers.list() -> McpServerResponse

📝 Description

Lists all MCP servers for a specific user

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.mcp_servers.list()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.mcp_servers.get(...) -> McpServerResponse

📝 Description

Gets a MCP server by ID

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.mcp_servers.get(
    mcp_server_id="mcp_server_id",
)

⚙️ Parameters

mcp_server_id: str — ID of the MCP server to retrieve

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.mcp_servers.delete(...) -> McpServerResponse

📝 Description

Deletes a MCP server by ID

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.mcp_servers.delete(
    mcp_server_id="mcp_server_id",
)

⚙️ Parameters

mcp_server_id: str — ID of the MCP server to delete

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Tools McpTools

client.tools.mcp_tools.list(...) -> McpServerToolResponse

📝 Description

Lists all MCP server tools for a specific MCP server

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.mcp_tools.list(
    mcp_server_id="mcp_server_id",
)

⚙️ Parameters

mcp_server_id: str — ID of the MCP server to list tools for

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.mcp_tools.get(...) -> McpServerToolResponse

📝 Description

Gets a MCP server tool by ID

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.mcp_tools.get(
    mcp_server_tool_id="mcp_server_tool_id",
)

⚙️ Parameters

mcp_server_tool_id: str — ID of the MCP server tool to retrieve

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.mcp_tools.delete(...) -> McpServerToolResponse

📝 Description

Deletes a MCP server tool by ID

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.mcp_tools.delete(
    mcp_server_tool_id="mcp_server_tool_id",
)

⚙️ Parameters

mcp_server_tool_id: str — ID of the MCP server tool to delete

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Voice

client.voice.voice.transcribe(...) -> TranscribeResponse

📝 Description

Transcribes an uploaded audio recording and returns the transcript. Send the raw audio bytes as the request body; the audio format is detected automatically (WAV, FLAC, MP3, OGG/WebM Opus).

Supports up to ~5 minutes of audio per request. This limit is on audio duration regardless of file size or format, so a compressed recording within the size limit can still be rejected for being too long. Pair the transcript with a downstream text step (e.g. POST /lang2fhir/create) to turn it into a FHIR resource.

🔌 Usage

client.voice.voice.transcribe(...)

⚙️ Parameters

request: typing.Union[bytes, typing.Iterator[bytes], typing.AsyncIterator[bytes]] — Raw audio bytes (WAV, FLAC, MP3, or OGG/WebM Opus).

language: typing.Optional[typing.Union[str, typing.Sequence[str]]] — BCP-47 language tag, repeatable for up to 4 candidate languages. Defaults to en-US.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Workflows

client.workflows.list(...) -> ListWorkflowsResponse

📝 Description

Retrieves all workflow definitions for the authenticated user

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.workflows.list(
    verbose=True,
)

⚙️ Parameters

verbose: typing.Optional[bool] — If true, includes full workflow implementation details in workflow_details field

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.workflows.create(...) -> CreateWorkflowResponse

📝 Description

Creates a new workflow definition with graph generation from workflow instructions

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.workflows.create(
    verbose=True,
    name="Patient Data Mapping Workflow",
    workflow_instructions="Given diagnosis data, find the patient and create a condition record linked to their encounter",
    sample_data={
        "patient_last_name": "Rippin",
        "patient_first_name": "Clay",
        "diagnosis_code": "I10",
        "encounter_date": "2024-01-15"
    },
    fhir_provider_id="550e8400-e29b-41d4-a716-446655440000",
)

⚙️ Parameters

name: str — Human-readable name for the workflow

workflow_instructions: str — Natural language instructions that define the workflow logic

sample_data: typing.Dict[str, typing.Any] — Sample data to use for workflow graph generation

fhir_provider_id: CreateWorkflowRequestFhirProviderId — FHIR provider ID(s) - must be valid UUID(s) from existing FHIR providers

verbose: typing.Optional[bool] — If true, includes full workflow implementation details in workflow_details field

dynamic_generation: typing.Optional[bool] — Enable dynamic lang2fhir calls instead of pre-populated templates

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.workflows.get(...) -> GetResponse

📝 Description

Retrieves a workflow definition by its ID

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.workflows.get(
    id="id",
    verbose=True,
)

⚙️ Parameters

id: str — ID of the workflow to retrieve

verbose: typing.Optional[bool] — If true, includes full workflow implementation details in workflow_details field

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.workflows.update(...) -> UpdateResponse

📝 Description

Updates an existing workflow definition

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.workflows.update(
    id="id",
    verbose=True,
    name="Patient Data Mapping Workflow (v2)",
    workflow_instructions="Given diagnosis data, find the patient and create a condition record linked to their encounter",
    sample_data={
        "patient_last_name": "Rippin",
        "patient_first_name": "Clay",
        "diagnosis_code": "I10",
        "encounter_date": "2024-01-15"
    },
    fhir_provider_id="550e8400-e29b-41d4-a716-446655440000",
)

⚙️ Parameters

id: str — ID of the workflow to update

name: str — Human-readable name for the workflow

workflow_instructions: str — Natural language instructions that define the workflow logic

sample_data: typing.Dict[str, typing.Any] — Sample data to use for workflow graph generation

fhir_provider_id: UpdateWorkflowRequestFhirProviderId — FHIR provider ID(s) - must be valid UUID(s) from existing FHIR providers

verbose: typing.Optional[bool] — If true, includes full workflow implementation details in workflow_details field

dynamic_generation: typing.Optional[bool] — Enable dynamic lang2fhir calls instead of pre-populated templates

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.workflows.delete(...) -> DeleteResponse

📝 Description

Deletes a workflow definition by its ID

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.workflows.delete(
    id="id",
)

⚙️ Parameters

id: str — ID of the workflow to delete

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.workflows.execute(...) -> ExecuteWorkflowResponse

📝 Description

Executes a workflow with provided input data and returns results

🔌 Usage

from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.workflows.execute(
    id="7a8b9c0d-1234-5678-abcd-ef9876543210",
    input_data={
        "patient_last_name": "Johnson",
        "patient_first_name": "Mary",
        "diagnosis_code": "M79.3",
        "encounter_date": "2024-03-20"
    },
)

⚙️ Parameters

id: str — ID of the workflow to execute

input_data: typing.Dict[str, typing.Any] — Input data for workflow execution

preview: typing.Optional[bool] — If true, create operations return mock resources instead of persisting to the FHIR server

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Uh oh!

FilesExpand file tree

reference.md

Latest commit

History

reference.md

File metadata and controls

Reference

Agent

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

Chat

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

Agent Prompts

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

Authtoken

📝 Description

🔌 Usage

⚙️ Parameters

Cohort

📝 Description

🔌 Usage

⚙️ Parameters

Code Systems

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters