Patient context and handoffs

The API accepts context at two points:

Both fields are clinical input. They are not credentials, executable instructions, or a substitute for structured patient identity.

Keep the trust boundary on your backend

Your backend should resolve the current patient to the Doctronic user ID stored for your organization. Do not accept a Doctronic user ID from a browser, mobile client, agent, or external workflow without validating that mapping.

Do not put an API token, webhook secret, or another system credential in either context field.

Pass useful context

Good context is relevant to the clinical task and attributable to its source. Examples include:

• The reason the patient entered the workflow.
• Answers collected in a prior intake step.
• A concise handoff from another approved clinical workflow.
• Constraints the patient explicitly selected, such as language or location.

Avoid copying an entire application state, unrestricted chart export, hidden routing commands, or content that the current workflow is not authorized to use.

{
  "timezone": "America/New_York",
  "conversationPromptContext": "The patient entered from a sore-throat intake flow and reported symptoms beginning yesterday."
}

{
  "userEvent": {
    "type": "user_message",
    "userInput": "My fever is 101.5 F.",
    "messagePromptContext": "Temperature was entered in the intake form immediately before this turn."
  },
  "timezone": "America/New_York"
}

Return control to the caller

Treat typed stream events as the return contract:

• Relay message.* events when the calling experience displays the conversation.
• Route guardian through the safety behavior approved for the integration.
• Use conversation.offtopic or conversation.end to return to an appropriate local flow.
• Map supported skill_code.cta values to explicit actions.
• Store artifact IDs from ai_consultation.complete and retrieve the required documents.
• Ignore unknown events and record enough metadata to investigate them.

The API does not provide a general-purpose agent callback or arbitrary routing endpoint. Keep caller-specific orchestration in your system unless a separate contract is established with Doctronic.