Canvas Medical

https://github.com/canvas-medical/documentation
Admin
Canvas Medical provides documentation for its platform, outlining requirements, development setup,...
Tokens:2,417,223
Snippets:15,230
Trust Score:8.9
Update:5 days ago
Show doc for...
Tokens:
Raw
### canvas install example from parent directory

Source: https://github.com/canvas-medical/documentation/blob/main/sdk-context.txt

Example of running canvas install from one directory above the plugin folder, passing the folder name and the --host option. The manifest is expected at extensions/encounter_list/CANVAS_MANIFEST.json.

```console
$ canvas install encounter_list --host your-host
```

--------------------------------

### Setup for Observation examples

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/effects/observation.md

Shared imports and patient retrieval used by all examples on this page.

```python
import datetime

from canvas_sdk.effects.observation import Observation, CodingData, ObservationComponentData
from canvas_sdk.v1.data.observation import Observation as ObservationModel
from canvas_sdk.v1.data.patient import Patient

patient = Patient.objects.first()
```

--------------------------------

### catalog manifest example

Source: https://github.com/canvas-medical/documentation/blob/main/sdk-context.txt

JSON example showing the catalog section with fields for title, kind, category, surfaces, keywords, screenshots, pricing, vendors, icon, setup guides, and release notes.

```json
{
  "catalog": {
    "title": "Intake Summary",
    "kind": "plugin",
    "category": "Charting",
    "surfaces": ["Note"],
    "keywords": ["intake", "summary"],
    "screenshots": [
      {"path": "assets/summary.png", "caption": "In the note", "alt": "An intake summary in a note"}
    ],
    "pricing": [
      {"unit": "visit", "price_per_unit": "1.50"},
      {"unit": "token"}
    ],
    "vendors": [
      {"name": "Twilio", "relationship": "self_managed", "additional_fees": true}
    ],
    "icon": "assets/icon.png",
    "setup_guide": "setup_guide.md",
    "setup_instructions": "setup_instructions.md",
    "release_notes": {"kind": "fix", "title": "Summaries keep their line breaks"}
  }
}
```

--------------------------------

### Complete Workflow Example

Source: https://github.com/canvas-medical/documentation/blob/main/sdk-context.txt

Shows a full workflow: importing the SDK, creating a client, starting a processor, polling for status with a timeout, handling the result, and cleaning up files. Includes a usage example at the end.

```python
import time
from canvas_sdk.clients.extend_ai.libraries import Client
from canvas_sdk.clients.extend_ai.constants import RunStatus
from canvas_sdk.clients.extend_ai.structures import RequestFailed

def extract_from_document(api_key: str, processor_id: str, document_url: str) -> dict:
    """
    Extract structured data from a document using Extend AI.

    Args:
        api_key: Your Extend AI API key
        processor_id: The processor ID to use
        document_url: Public URL to the document

    Returns:
        Dictionary containing the extracted data

    Raises:
        RequestFailed: If the API request fails
        RuntimeError: If processing fails or times out
    """
    client = Client(key=api_key)

    # Start processing
    run = client.run_processor(
        processor_id=processor_id,
        file_name="document.pdf",
        file_url=document_url,
        config=None,
    )

    # Wait for completion (with timeout)
    max_attempts = 30  # 60 seconds max
    attempts = 0
    while run.status in (RunStatus.PENDING, RunStatus.PROCESSING):
        if attempts >= max_attempts:
            raise RuntimeError("Processing timed out")
        time.sleep(2)
        run = client.run_status(run.id)
        attempts += 1

    # Handle result
    if run.status == RunStatus.PROCESSED:
        # Clean up files
        for file in run.files:
            client.delete_file(file.id)
        return run.output.value if hasattr(run.output, 'value') else run.output.to_dict()

    raise RuntimeError(f"Processing failed: {run.status.value}")

# Usage
result = extract_from_document(
    api_key="your_api_key",
    processor_id="proc_xxxxxxxxxxxxxxxxx",
    document_url="https://example.com/document.pdf"
)
print(result)
```

--------------------------------

### .canvasignore example

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/canvas_cli.md

Example .canvasignore file using .gitignore syntax to exclude test files from the package. Place it in the directory you run canvas install from.

```md
# Exclude test files
test_*.py
```

--------------------------------

### Issue a simple GET request asynchronously

Source: https://github.com/canvas-medical/documentation/blob/main/sdk-context.txt

This example creates an HttpRequestEffect for a GET request and schedules it asynchronously with delay_seconds=0. It is a minimal example showing the basic usage of .set_async().

```python
http_effect = HttpRequestEffect(
    url="https://api.example.com/status",
)
return [http_effect.apply().set_async(delay_seconds=0)]
```

--------------------------------

### canvas deploy example

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/canvas_cli.md

Example of deploying a plugin to a specific instance using the `--instance` option.

```console
$ canvas deploy paperwork-eviscerator/acme__paperwork_eviscerator --instance acme-staging
```

--------------------------------

### curl GET Request Example

Source: https://github.com/canvas-medical/documentation/blob/main/fhir-context.txt

Example curl command to make a GET request to the FHIR Observation API. The command is incomplete in the source, ending with a line continuation.

```shell
curl --request GET \
```

--------------------------------

### Example confirmation and output of namespace reset --execute

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/custom-data/namespace-lifecycle.md

Example showing the confirmation prompt and the result of the reset.

```text
This will reset namespace 'acme_corp__shared_data'. This cannot be undone.
Type the full namespace name to confirm: acme_corp__shared_data

Namespace 'acme_corp__shared_data' has been reset.
  Dropped tables: customnote, specialty
  Truncated tables: custom_attribute, attribute_hub
```

--------------------------------

### Full Batch Originate Example with Multiple Commands

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/effects/batch_originate.md

Complete example showing how to create multiple commands (PlanCommand, HistoryOfPresentIllnessCommand, AssessCommand, QuestionnaireCommand) and batch originate them. It retrieves the last note and a questionnaire by name, then returns a BatchOriginateCommandEffect with all commands.

```python
from canvas_sdk.commands import (
    PlanCommand,
    HistoryOfPresentIllnessCommand,
    QuestionnaireCommand,
    AssessCommand
)
from canvas_sdk.effects.batch_originate import BatchOriginateCommandEffect
from canvas_sdk.handlers import BaseHandler
from canvas_sdk.v1.data import Questionnaire, Note
from canvas_sdk.events import EventType


class Handler(BaseHandler):

    def compute(self):
        note_uuid = str(Note.objects.last().id)

        # Create multiple commands
        plan1 = PlanCommand()
        plan1.narrative = "Order labs for lipid panel"
        plan1.note_uuid = note_uuid

        plan2 = PlanCommand()
        plan2.narrative = "Schedule follow-up in 3 months"
        plan2.note_uuid = note_uuid

        hpi = HistoryOfPresentIllnessCommand()
        hpi.narrative = "Annual wellness visit"
        hpi.note_uuid = note_uuid

        assess = AssessCommand()
        assess.icd10_code = "E11.9"
        assess.note_uuid = note_uuid
        assess.background = "Type 2 diabetes mellitus"

        # Add a questionnaire
        questionnaire = QuestionnaireCommand()
        questionnaire.note_uuid = note_uuid
        questionnaire_id = Questionnaire.objects.filter(
            name="Patient Health Questionnaire"
        ).first()
        if questionnaire_id:
            questionnaire.questionnaire_id = str(questionnaire_id.id)

        # Batch originate all commands
        commands_to_originate = [plan1, plan2, hpi, assess, questionnaire]
        return [BatchOriginateCommandEffect(commands=commands_to_originate).apply()]
```

--------------------------------

### SimpleAPIRoute GET and POST

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/handlers/simple-api/api.md

Example of a SimpleAPIRoute handler that supports GET and POST requests on the same path.

```APIDOC
## GET /plugin-io/api/<plugin-name>/routes/hello-world

### Description
Returns a JSON response with a greeting message.

### Method
GET

### Endpoint
`https://<instance-name>.canvasmedical.com/plugin-io/api/<plugin-name>/routes/hello-world`

### Response
#### Success Response (200)
- **message** (string) - Greeting message.

#### Response Example
{
  "message": "Hello world from my GET endpoint!"
}

## POST /plugin-io/api/<plugin-name>/routes/hello-world

### Description
Returns a JSON response with a greeting message.

### Method
POST

### Endpoint
`https://<instance-name>.canvasmedical.com/plugin-io/api/<plugin-name>/routes/hello-world`

### Response
#### Success Response (200)
- **message** (string) - Greeting message.

#### Response Example
{
  "message": "Hello world from my POST endpoint!"
}
```

--------------------------------

### Initialize a new plugin with canvas init

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_guides/your-first-plugin.md

Run `canvas init` and answer the prompt to name your plugin. The output shows the project location and confirms registration with Canvas Platform. The command names the package with your organization's prefix, registers it, and makes the project folder a git repository that `canvas deploy` pushes to.

```sh
$ canvas init
  [1/1] project_name (My Cool Plugin): Paperwork Eviscerator
Project created in /Users/andrew/src/canvas-plugins/paperwork-eviscerator
Registered acme__paperwork_eviscerator with Canvas Platform.
```

--------------------------------

### Chaining example

Source: https://github.com/canvas-medical/documentation/blob/main/sdk-context.txt

Example of chaining convenience methods with for_patient and committed to get active adjustments for a patient and protocol key.

```APIDOC
## Chaining example

### Description
Example of chaining convenience methods with `for_patient`, `committed`, and `active` to get active adjustments for a given patient and protocol key.

### Method
chaining

### Request Example
```python
from canvas_sdk.v1.data.protocol_override import ProtocolOverride
adjustments = (
    ProtocolOverride.objects
    .for_patient("1eed3ea2a8d546a1b681a2a45de1d790")
    .committed()
    .active()
    .adjustments("HCC001v1")
)
```

### Response
Returns a queryset of ProtocolOverride objects that are active adjustments for the given patient and protocol key.
```

--------------------------------

### Python GET Group example

Source: https://github.com/canvas-medical/documentation/blob/main/fhir-context.txt

Python script using requests to GET a FHIR Group resource. Prints the response text.

```python
import requests
url = "https://fumage-example.canvasmedical.com/Group/<id>"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)
```

--------------------------------

### Initialize OpenAI client with LlmOpenai

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/clients/llms.md

Create an OpenAI client using LlmOpenai with LlmSettingsGpt4. Requires an OpenAI API key. The example uses model 'gpt-4o' and temperature 0.7.

```python
from canvas_sdk.clients.llms import LlmOpenai
from canvas_sdk.clients.llms.structures.settings import LlmSettingsGpt4

client = LlmOpenai(LlmSettingsGpt4(
    api_key="your_openai_api_key",
    model="gpt-4o",
    temperature=0.7,
))
```

--------------------------------

### Initialize Google client with LlmGoogle

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/clients/llms.md

Create a Google client using LlmGoogle with LlmSettingsGemini. Requires a Google API key. The example uses model 'models/gemini-2.0-flash' and temperature 0.7.

```python
from canvas_sdk.clients.llms import LlmGoogle
from canvas_sdk.clients.llms.structures.settings import LlmSettingsGemini

client = LlmGoogle(LlmSettingsGemini(
    api_key="your_google_api_key",
    model="models/gemini-2.0-flash",
    temperature=0.7,
))
```

--------------------------------

### 200 Response for GET Allergen by ID

Source: https://github.com/canvas-medical/documentation/blob/main/fhir-context.txt

Example 200 response for a successful GET Allergen by ID request, returning an Allergen resource.

```json
{
    "resourceType": "Allergen",
    "id": "fdb-6-2754",
    "text": {
        "status": "generated",
        "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>minocycline HCl</p><p>6979</p>\"</div>"
    },
    "code": {
        "coding": [
            {
                "system": "http://www.fdbhealth.com/",
                "code": "6-2754",
                "display": "minocycline HCl"
            },
            {
                "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                "code": "6979"
            }
        ]
    }
}
```

--------------------------------

### 200 Success response for GET Group

Source: https://github.com/canvas-medical/documentation/blob/main/fhir-context.txt

Example of a successful GET response containing a FHIR Group resource with practitioner type and member reference.

```json
{
    "resourceType": "Group",
    "id": "3340c331-d446-4700-9c23-7959bd393f26",
    "type": "practitioner",
    "actual": true,
    "name": "A Test Team",
    "quantity": 1,
    "characteristic": [
        {
            "code": {
                "text": "responsibility"
            },
            "valueCodeableConcept": {
                "text": "COLLECT_SPECIMENS_FROM_PATIENT"
            },
            "exclude": false
        }
    ],
    "member": [
        {
            "entity": {
                "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39",
                "type": "Practitioner"
            }
        }
    ]
}
```

--------------------------------

### Initialize a plugin with canvas init

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_guides/custom-landing-page.md

Run this command to create a new plugin project. Follow the prompts to name and configure the project. If signed in, the package is named with your organization's prefix and registered with Canvas Platform.

```bash
  canvas init
```

--------------------------------

### Search DocumentReference with HTTP GET

Source: https://github.com/canvas-medical/documentation/blob/main/fhir-context.txt

Example HTTP GET request to search for DocumentReference resources. Requires an Authorization header with a Bearer token.

```http
GET /DocumentReference?subject=Patient%2Fcfd91cd3bd9046db81199aa8ee4afd7f&status=current&type=http%3A%2F%2Floinc.org%7C11502-2&_count=10&_offset=0
Authorization: Bearer <token>
```

--------------------------------

### Limits and page size examples

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/plugin-logs.md

Examples showing how to use --limit and --page-size to control the number of logs fetched and printed.

```console
# One fixed page of size 200 (default page-size):
$ canvas logs --no-follow --since 24h

# Fetch up to 2000 logs across pages (non-interactive):
$ canvas logs --no-follow --since 72h --limit 2000

# Smaller batches for slow connections:
$ canvas logs --no-follow --since 24h --limit 1000 --page-size 100
```

--------------------------------

### SimpleAPI Response Types Example

Source: https://github.com/canvas-medical/documentation/blob/main/sdk-context.txt

Example of a SimpleAPIRoute handler that returns different response types for GET, POST, PUT, and PATCH methods.

```APIDOC
## SimpleAPI Response Types

### Description
Example of a SimpleAPIRoute handler that returns different response types for GET, POST, PUT, and PATCH methods.

### Method
GET, POST, PUT, PATCH

### Endpoint
/routes/hello-world

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
None

### Response
#### Success Response (200)
- **HTMLResponse** - Returns HTML content with status code and headers.
- **JSONResponse** - Returns JSON content with status code and headers.
- **PlainTextResponse** - Returns plain text with status code and headers.
- **Response** - Returns raw content with status code, headers, and content type.

#### Response Example
```python
from http import HTTPStatus
from canvas_sdk.effects import Effect
from canvas_sdk.effects.simple_api import HTMLResponse, JSONResponse, PlainTextResponse, Response
from canvas_sdk.handlers.simple_api import APIKeyCredentials, SimpleAPIRoute

class MyAPI(SimpleAPIRoute):
    PATH = "/routes/hello-world"
    def authenticate(self, credentials: APIKeyCredentials) -> bool:
        ...
    def get(self) -> list[Response | Effect]:
        return [
            HTMLResponse(
                "<p>Hello world from my GET endpoint!</p>",
                status_code=HTTPStatus.OK,
                headers={"My-Header", "my header value"}
            )
        ]
    def post(self) -> list[Response | Effect]:
        return [
            JSONResponse(
                {"message": "Hello world from my POST endpoint!"},
                status_code=HTTPStatus.CREATED,
                headers={"My-Header", "my header value"}
            )
        ]
    def put(self) -> list[Response | Effect]:
        return [
            PlainTextResponse(
                "Hello world from my PUT endpoint!",
                status_code=HTTPStatus.ACCEPTED,
                headers={"My-Header", "my header value"}
            )
        ]
    def patch(self) -> list[Response | Effect]:
        return [
            Response(
                b'{"message": "Hello world from my PATCH endpoint!"}',
                status_code=HTTPStatus.NOT_MODIFIED,
                headers={"My-Header", "my header value"},
                content_type="application/json"
            )
        ]
```

### Error Handling
- Multiple response objects: **500 Internal Server Error**
- No response object: **204 No Content**
```

--------------------------------

### Create ProtocolCard with Recommendations and Commands

Source: https://github.com/canvas-medical/documentation/blob/main/sdk-context.txt

Shows how to build a ProtocolCard with various recommendation types: plain text, multiple commands, and a command recommendation via .recommend(). Uses AssessCommand and PlanCommand. The card is applied with p.apply().

```python
from canvas_sdk.events import EventType
from canvas_sdk.handlers import BaseHandler
from datetime import date
from canvas_sdk.effects.protocol_card import ProtocolCard, Recommendation
from canvas_sdk.commands import AssessCommand, PlanCommand
class MyHandler(BaseHandler):
    RESPONDS_TO = EventType.Name(EventType.PATIENT_UPDATED)
    def compute(self):
        assess = AssessCommand(
            icd10_code="I10",
            background="feeling bad for many years",
            approximate_date_of_onset=date(2020, 1, 1),
            narrative="still not great",
        )
        plan = PlanCommand(
            narrative="Follow up in 2 weeks",
        )
        p = ProtocolCard(
            patient_id=self.target,
            key="testing-protocol-cards",
            title="This is a ProtocolCard title",
            narrative="this is the narrative",
            status=ProtocolCard.Status.DUE,
            recommendations=[
              Recommendation(title="this recommendation has no action, just words!"),
              Recommendation(title="this recommendation inserts multiple commands", button="add commands", commands=[assess, plan])
            ],
        )
        p.add_recommendation(
            title="this is a recommendation", button="go here", href="https://canvasmedical.com/"
        )
        p.recommendations.append(assess.recommend(title="this inserts an assess command"))
        p.recommendations.append(title="new recommendation", button="start", commands=[assess])
        return [p.apply()]
```

--------------------------------

### Python request example

Source: https://github.com/canvas-medical/documentation/blob/main/fhir-context.txt

Example of making a GET request to the Location API using the requests library. The response text is printed to the console.

```python
response = requests.get(url, headers=headers)
print(response.text)
```

--------------------------------

### LaunchModalEffect example for Hello World modal

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_guides/growth-charts.md

Shows a simple plugin that uses LaunchModalEffect to display a 'Hello World' message when the button is clicked. The handle method returns the effect after applying it.

```python
from canvas_sdk.effects import Effect
from canvas_sdk.effects.launch_modal import LaunchModalEffect
from canvas_sdk.handlers.action_button import ActionButton
from canvas_sdk.templates import render_to_string


class HelloWorld(ActionButton):
    BUTTON_TITLE = "Hello World"
    BUTTON_KEY = "show_hello_world"
    BUTTON_LOCATION = ActionButton.ButtonLocation.NOTE_HEADER

    def handle(self) -> list[Effect]:
        launch_modal = LaunchModalEffect(content=render_to_string("templates/hello-world.html", { "title": "hello world" }))

        return [launch_modal.apply()]
```

--------------------------------

### Create a ReferCommand with ServiceProvider

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/commands.md

Shows how to instantiate a ServiceProvider with provider details and pass it to a ReferCommand. The example sets a note_uuid, diagnosis_codes, priority, clinical_question, notes_to_specialist, and service_provider.

```python
from canvas_sdk.commands import ReferCommand
from canvas_sdk.commands.constants import ServiceProvider

# Creating a referral with service provider information
service_provider = ServiceProvider(
    first_name="John",
    last_name="Smith",
    specialty="Cardiology",
    practice_name="Heart Health Center",
    business_phone="555-0123",
    business_address="123 Medical Plaza, Suite 100"
)

refer = ReferCommand(
    note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
    diagnosis_codes=["E119"],
    priority=ReferCommand.Priority.ROUTINE,
    clinical_question=ReferCommand.ClinicalQuestion.DIAGNOSTIC_UNCERTAINTY,
    notes_to_specialist="Patient needs cardiac evaluation",
    service_provider=service_provider
)
```

--------------------------------

### Commands manifest example

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/canvas_manifest.md

Declares a custom command in the manifest. The schema_key must be unique across every plugin installed on the instance, or installation fails.

```json
{
  "components": {
    "commands": [
      {
        "name": "RiskAssessment",
        "label": "Risk Assessment",
        "schema_key": "myPluginRiskAssessment",
        "section": "assessment"
      }
    ]
  }
}
```

--------------------------------

### Create processor with client.create_processor()

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/clients/extend-ai.md

Creates a new processor with a name and configuration. Uses ConfigExtraction with base processor, extraction rule, schema, and advanced options. Prints the new processor ID.

```python
from canvas_sdk.clients.extend_ai.constants import BaseProcessor
from canvas_sdk.clients.extend_ai.structures.config import (
    ConfigExtraction,
    AdvancedOptionsExtraction,
    Parser,
)

config = ConfigExtraction(
    base_processor=BaseProcessor.EXTRACTION_PERFORMANCE,
    extraction_rule="Extract all relevant fields",
    schema={
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "date": {"type": "string"},
            "amount": {"type": "number"},
        }
    },
    advanced_options=AdvancedOptionsExtraction.from_dict({}),
    parser=Parser.from_dict({}),
)

processor = client.create_processor("Invoice Extractor", config)
print(f"Created: {processor.id}")
```

--------------------------------

### Get Coverage by ID - Python Request

Source: https://github.com/canvas-medical/documentation/blob/main/fhir-context.txt

Python example using requests to GET a Coverage resource by ID. Requires a valid bearer token.

```python
import requests
url = "https://fumage-example.canvasmedical.com/Coverage/<id>"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)
```

--------------------------------

### GET request with Http.get

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/utils.md

Sends a GET request to the specified URL with optional headers. The example includes an Authorization header using a Bearer token.

```python
from canvas_sdk.utils import Http

http = Http()
http.get("https://my-url.com/", headers={"Authorization": f"Bearer token"})
```

--------------------------------

### Install test-utils via uv

Source: https://github.com/canvas-medical/documentation/blob/main/sdk-context.txt

Installs the canvas[test-utils] extra directly using uv.

```bash
uv add "canvas[test-utils]"

```

--------------------------------

### Initialize the S3 client

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/clients/aws-s3.md

Create Credentials with your AWS access key, secret, region, and bucket name, then instantiate the S3 client.

```python
from canvas_sdk.clients.aws import S3, Credentials

credentials = Credentials(
    key="your_aws_access_key_id",
    secret="your_aws_secret_access_key",
    region="us-east-1",
    bucket="your-bucket-name"
)

client = S3(credentials)
```

--------------------------------

### Get a VitalSignReading by ID

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/data/vitals.md

Use the get method on the VitalSignReading model manager to fetch a single reading by its identifier. The example uses a hardcoded UUID.

```python
from canvas_sdk.v1.data.vitals import VitalSignReading

reading = VitalSignReading.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
```

--------------------------------

### Get Instruction by ID

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/data/instruction.md

Use the get method on the Instruction model manager to retrieve a single instruction by its identifier. The example uses a hardcoded UUID.

```python
from canvas_sdk.v1.data.instruction import Instruction

instruction = Instruction.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
```

--------------------------------

### Example - Working with Existing Commands

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/commands.md

A common use case is retrieving existing PhysicalExam commands from a note and modifying their toggle states.

```python
from canvas_sdk.commands import PhysicalExamCommand
from canvas_sdk.v1.data import Command, Note
from logger import log

# Get existing physical exam commands from a note
note = Note.objects.get(id="ff287601-fff4-46c4-b21f-04760e88adf1")
physical_exam_commands = Command.objects.filter(
    note=note,
    schema_key="exam"  # Physical exam commands have schema_key "exam"
).all()

effects = []
for command in physical_exam_commands:
    # The command.data contains the question responses and skip states
    # Example structure of command.data:
    # {
    #     "questionnaire": {"value": "83d93454-25a9-404d-83a5-e0ed2ec3af00"},
    #     "question-12": "70",  # Body length response
    #     "question-13": None,   # Head circumference (no response)
    #     "skip-12": True,   # Body length is enabled (counterintuitive: skip=True means enabled)
    #     "skip-13": False,  # Head circumference is disabled
    # }

    # Create a PhysicalExamCommand instance from the existing command
    exam = PhysicalExamCommand(command_uuid=str(command.id))

    # The exam.questions property gives you access to all questions with their IDs
    log.info(f"Processing Physical Exam Command: {exam.command_uuid}")
    for question in exam.questions:
        # Each question object has an 'id' property with the question ID
        question_id = question.dbid
        if exam.is_question_enabled(question_id):
            log.info(f"Question {question_id} is enabled")

            # Check if there's a response in the command data
            question_key = f"question-{question_id}"
            if question_key in command.data:
                response = command.data[question_key]
                if response:
                    log.info(f"Response: {response}")

    # Example: Enable all questions that have responses, disable those without
    for question in exam.questions:
        question_id = question.dbid
        question_key = f"question-{question_id}"
        # Check if question has a response in command.data
        has_response = question_key in command.data and command.data[question_key]

        if has_response:
            exam.set_question_enabled(question_id, True)
        else:
            # Optionally disable questions without responses
            exam.set_question_enabled(question_id, False)

    effects.append(exam.edit())

```

--------------------------------

### Get CancelPrescriptionResponse by ID

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/data/cancel_prescription_response.md

Use the `get` method on the `CancelPrescriptionResponse` model manager to retrieve a response by its identifier. The example uses a specific UUID as the `id`.

```python
from canvas_sdk.v1.data import CancelPrescriptionResponse

response = CancelPrescriptionResponse.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
```

--------------------------------

### Example seed.py file

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/testing-utils.md

Example Python file that populates the database with test data.

```python
from canvas_sdk.test_utils.factories import PatientFactory
from canvas_sdk.v1.data.discount import Discount

PatientFactory.create(first_name="Seeded", last_name="Patient")

Discount.objects.create(
    name="20%",
    adjustment_group="X",
    adjustment_code="Y",
    discount=0.20
)
```

--------------------------------

### Application with on_open() and on_context_change() handling claim, queue, and revenue contexts

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/handlers/applications.md

This example shows an application that opens in the right chart pane and reloads with claim or queue details as the user moves through revenue pages. It implements on_open() to launch an iframe and on_context_change() to handle claim, claim_queue, and general revenue page contexts, returning None when no relevant context is found.

```python
from canvas_sdk.effects import Effect
from canvas_sdk.effects.launch_modal import LaunchModalEffect
from canvas_sdk.handlers.application import Application


class IFrameApp(Application):
    def on_open(self) -> Effect | list[Effect]:
        return LaunchModalEffect(url=f"https://www.your-iframe-app.com",
            target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE, title="Your Iframe App").apply()

    def on_context_change(self) -> Effect | list[Effect] | None:
        # Access the current URL that triggered the context change
        current_url = self.event.context.get("url", "")

        # Handle claim-specific context
        if claim := self.event.context.get("claim"):
            claim_id = claim["id"]
            return LaunchModalEffect(
                url=f"https://www.your-iframe-app.com?claim_id={claim_id}&source_url={current_url}",
                target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE,
                title=f"Your Iframe App - Claim {claim_id}"
            ).apply()

        # Handle queue-specific context
        if queue := self.event.context.get("claim_queue"):
            queue_id = queue["dbid"]
            return LaunchModalEffect(
                url=f"https://www.your-iframe-app.com?queue_id={queue_id}&source_url={current_url}",
                target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE,
                title=f"Your Iframe App - Queue {queue_id}"
            ).apply()

        # Handle general revenue page context
        if current_url.startswith("/revenue"):
            return LaunchModalEffect(
                url=f"https://www.your-iframe-app.com?page=revenue&source_url={current_url}",
                target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE,
                title="Your Iframe App - Revenue"
            ).apply()

        # Return None when no relevant context - this will result in an empty effect list
        return None
```

--------------------------------

### Install plugin with access key using canvas install --secret

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/custom-data/sharing-data.md

Provide the access key during installation using the `--secret` flag. This is required for plugins that join a namespace. The example uses the `namespace_read_write_access_key`.

```bash
canvas install my_plugin \
  --host demo.canvasmedical.com \
  --secret namespace_read_write_access_key=3b35fad9-6462-4e83-83f5-c0e4bde49b71
```

--------------------------------

### 200 OK Response Example

Source: https://github.com/canvas-medical/documentation/blob/main/fhir-context.txt

Example JSON response for a successful GET request to the MedicationRequest endpoint. Shows the resource structure with medication, subject, and encounter references.

```json
{
    "resourceType": "MedicationRequest",
    "id": "3423a69c-618d-4cbe-861a-54c60f48744e",
    "status": "active",
    "intent": "order",
    "category": [
        {
            "coding": [
                {
                    "system": "http://terminology.hl7.org/CodeSystem/medicationrequest-category",
                    "code": "outpatient",
                    "display": "Outpatient"
                }
            ]
        }
    ],
    "reportedBoolean": false,
    "medicationCodeableConcept": {
        "coding": [
            {
                "system": "http://www.fdbhealth.com/",
                "code": "244899",
                "display": "lisinopril 10 mg tablet"
            },
            {
                "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                "code": "314076",
                "display": "lisinopril 10 mg tablet"
            }
        ]
    },
    "subject": {
        "reference": "Patient/6cb2a409334943c2b48f1686dc739f11",
        "type": "Patient"
    },
    "encounter": {
        "reference": "Encounter/bdadce18-098b-40dc-8bdd-ef8481bd999a",
        "type": "Encounter"
    },
    "authoredOn": "2023-09-21T18:19:36.106449+00:00"
}
```

--------------------------------

### PrescribeCommand with full parameters

Source: https://github.com/canvas-medical/documentation/blob/main/sdk-context.txt

Example of creating a PrescribeCommand with all parameters including sig, days_supply, quantity_to_dispense, refills, substitutions, pharmacy, prescriber_id, supervising_provider_id, and note_to_pharmacist.

```python
sig="Apply thin layer to affected area twice daily",
        days_supply=30,
        quantity_to_dispense=30,
        refills=3,
        substitutions=PrescribeCommand.Substitutions.ALLOWED,
        pharmacy="pharmacy_ncpdp_id",
        prescriber_id="a7c2e9d1-3b4f-4a6c-8e0d-5f1a2b3c4d5e",
        supervising_provider_id='c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f',
        note_to_pharmacist="Please verify patient's insurance before processing."
    )
```

--------------------------------

### Create ProtocolCard with Recommendations

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/effects/protocol_cards.md

Shows how to instantiate commands, create a ProtocolCard with recommendations (including a recommendation with multiple commands), add a non-command recommendation via add_recommendation, and append command-generated recommendations. The handler responds to PATIENT_UPDATED and applies the effect.

```python
from canvas_sdk.events import EventType
from canvas_sdk.handlers import BaseHandler
from datetime import date
from canvas_sdk.effects.protocol_card import ProtocolCard, Recommendation
from canvas_sdk.commands import AssessCommand, PlanCommand


class MyHandler(BaseHandler):
    RESPONDS_TO = EventType.Name(EventType.PATIENT_UPDATED)

    def compute(self):
        assess = AssessCommand(
            icd10_code="I10",
            background="feeling bad for many years",
            approximate_date_of_onset=date(2020, 1, 1),
            narrative="still not great",
        )
        
        plan = PlanCommand(
            narrative="Follow up in 2 weeks",
        )
        
        p = ProtocolCard(
            patient_id=self.target,
            key="testing-protocol-cards",
            title="This is a ProtocolCard title",
            narrative="this is the narrative",
            status=ProtocolCard.Status.DUE,
            recommendations=[
              Recommendation(title="this recommendation has no action, just words!"),
              Recommendation(title="this recommendation inserts multiple commands", button="add commands", commands=[assess, plan])
            ],
        )

        p.add_recommendation(
            title="this is a recommendation", button="go here", href="https://canvasmedical.com/"
        )

        p.recommendations.append(assess.recommend(title="this inserts an assess command"))
        p.recommendations.append(title="new recommendation", button="start", commands=[assess])

        return [p.apply()]

```

--------------------------------

### Get a clipboard by identifier

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/data/clipboard.md

Use the `get` method on the model manager to retrieve a clipboard by its UUID. The example shows importing the Clipboard model and fetching a specific record.

```python
from canvas_sdk.v1.data import Clipboard

clipboard = Clipboard.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
```

--------------------------------

### GET DiagnosticReport by ID - 200 Response

Source: https://github.com/canvas-medical/documentation/blob/main/fhir-context.txt

Example JSON response for a successful GET request, returning a DiagnosticReport resource with details such as status, code, subject, encounter, and presentedForm.

```json
{
    "resourceType": "DiagnosticReport",
    "id": "9b90621b-059f-4f6e-9ef5-58171098e424",
    "status": "final",
    "category":
    [
        {
            "coding":
            [
                {
                    "system": "http://loinc.org",
                    "code": "LP29684-5",
                    "display": "Radiology"
                }
            ]
        }
    ],
    "code":
    {
        "coding":
        [
            {
                "system": "http://www.ama-assn.org/go/cpt",
                "code": "73562",
                "display": "XRAY, knee; 3 views"
            }
        ],
        "text": "XRAY, knee; 3 views"
    },
    "subject":
    {
        "reference": "Patient/a1197fa9e65b4a5195af15e0234f61c2",
        "type": "Patient"
    },
    "encounter":
    {
        "reference": "Encounter/6a077e6f-ead2-4af7-803d-0a203bedfb1c",
        "type": "Encounter"
    },
    "effectiveDateTime": "2023-08-22",
    "issued": "2023-08-22T21:35:01.909441+00:00",
    "performer":
    [
        {
            "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
            "type": "Practitioner"
        }
    ],
    "presentedForm":
    [
        {
            "url": "https://fumage-example.canvasmedical.com/DiagnosticReport/9b90621b-059f-4f6e-9ef5-58171098e424/files/presentedForm"
        }
    ]
}
```

--------------------------------

### Log paging examples with --page-size and --limit

Source: https://github.com/canvas-medical/documentation/blob/main/sdk-context.txt

Examples showing how to fetch a fixed page, limit total logs across pages, and use smaller batches for slow connections. In non-interactive no-limit mode, the CLI prints one page; add --limit, --interactive, or --all to keep paging.

```console
# One fixed page of size 200 (default page-size):
$ canvas logs --no-follow --since 24h
# Fetch up to 2000 logs across pages (non-interactive):
$ canvas logs --no-follow --since 72h --limit 2000
# Smaller batches for slow connections:
$ canvas logs --no-follow --since 24h --limit 1000 --page-size 100
```

--------------------------------

### Quick Start Commands

Source: https://github.com/canvas-medical/documentation/blob/main/CLAUDE.md

Commands to start the development server using Devbox or manually with Yarn and Bundler. The dev server runs on ports 4000 (Jekyll) and 4001 (Webpack).

```sh
# With Devbox (recommended)
devbox run dev

# Manual
yarn install && bundle install
yarn dev
```

--------------------------------

### GET Consent by ID - 200 Response

Source: https://github.com/canvas-medical/documentation/blob/main/fhir-context.txt

Example 200 response for a successful GET Consent request. Contains the Consent resource with patient reference, category, and provision period.

```json
{
  "resourceType": "Consent",
  "id": "a9d3c0d9-e87a-4737-b909-ac81ee62f9a0",
  "status": "inactive",
  "scope": {
      "text": "Unknown"
  },
  "category": [
    {
      "coding": [
        {
          "system": "internal",
          "display": "Restraints"
        }
      ]
    }
  ],
  "patient": {
      "reference": "Patient/2c4b29a411b043bfb1c34c8c3683c7ca",
      "type": "Patient"
  },
  "dateTime": "2022-04-13T14:43:32.317476+00:00",
  "sourceAttachment": {
      "url": "https://fumage-example.canvasmedical.com/Consent/a9d3c0d9-e87a-4737-b909-ac81ee62f9a0/files/sourceAttachment"
  },
  "provision": {
      "period": {
          "start": "2022-04-13",
          "end": "2022-12-31"
      }
  }
}
```

--------------------------------

### 200 OK Response for GET Device

Source: https://github.com/canvas-medical/documentation/blob/main/fhir-context.txt

Example successful response for a GET Device request. Contains the full Device resource with attributes such as id, udiCarrier, status, manufacturer, and patient reference.

```json
{
    "resourceType": "Device",
    "id": "c6bf6efc-1fe1-4221-9821-e60acb53becc",
    "udiCarrier":
    [
        {
            "deviceIdentifier": "08717648200274",
            "carrierHRF": "=/08717648200274=,000025=A99971312345600=>014032=}013032&,1000000000000XYZ123"
        }
    ],
    "status": "active",
    "distinctIdentifier": "A99971312345600",
    "manufacturer": "ACME Biomedical",
    "manufactureDate": "2021-02-15",
    "expirationDate": "2021-09-15",
    "lotNumber": "234234",
    "serialNumber": "13213123123123",
    "modelNumber": "1.0",
    "type":
    {
        "coding":
        [
            {
                "system": "http://snomed.info/sct",
                "code": "2478003",
                "display": "Ocular prosthesis"
            }
        ]
    },
    "patient":
    {
        "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
        "type": "Patient"
    }
}
```

--------------------------------

### Serve built website locally

Source: https://github.com/canvas-medical/documentation/blob/main/README.md

Runs a local server to test the built website.

```sh
yarn serve:dist
```

--------------------------------

### 200 OK response for GET AllergyIntolerance

Source: https://github.com/canvas-medical/documentation/blob/main/fhir-context.txt

Example JSON response for a successful GET request. Contains the full AllergyIntolerance resource with clinical status, code, patient, encounter, and reaction details.

```json
{
    "resourceType": "AllergyIntolerance",
    "id": "3340c331-d446-4700-9c23-7959bd393f26",
    "extension": [
        {
            "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
            "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
        }
    ],
    "clinicalStatus": {
        "coding": [
            {
                "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
                "code": "active",
                "display": "Active"
            }
        ],
        "text": "Active"
    },
    "verificationStatus": {
        "coding": [
            {
                "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-verification",
                "code": "confirmed",
                "display": "Confirmed"
            }
        ],
        "text": "Confirmed"
    },
    "type": "allergy",
    "code": {
        "coding": [
            {
                "system": "http://www.fdbhealth.com/",
                "code": "2-15588",
                "display": "Allergy Medicine"
            }
        ],
        "text": "Allergy Medicine"
    },
    "patient": {
        "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
    },
    "encounter": {
        "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
    },
    "onsetDateTime": "2023-06-15",
    "recorder": {
        "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
    },
    "lastOccurrence": "2023-06-17",
    "note": [
        {
            "text": "AllergyIntolerance note"
        }
    ],
    "reaction": [
        {
            "manifestation": [
                {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/data-absent-reason",
                            "code": "unknown",
                            "display": "Unknown"
                        }
                    ],
                    "text": "Unknown"
                }
            ],
            "severity": "moderate"
        }
    ]
}
```

--------------------------------

### Create a Calendar with Calendar.create()

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/effects/calendar.md

Builds a Calendar with provider, type, location, and description, then calls create() to create the calendar. provider and type are required.

```python
from canvas_sdk.effects.calendar import Calendar, CalendarType

Calendar(
   provider="provider-uuid",
   type=CalendarType.Clinic,
   location="location-uuid",
   description="Primary clinic calendar"
).create()
```

--------------------------------

### Example output of canvas namespace inspect

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_sdk/custom-data/namespace-lifecycle.md

Example output showing system and custom tables with column details.

```text
Namespace: acme_corp__shared_data

System tables:
  namespace_auth       ~2 rows
  schema_version       ~2 rows
  custom_attribute     ~150 rows
  attribute_hub        ~3 rows

Custom tables:
  customnote   ~25 rows
    dbid     bigint    not null
    title    text      nullable
    body     text      nullable
  specialty    ~8 rows
    dbid     bigint    not null
    name     character varying    nullable
```

--------------------------------

### Deploy plugin with /cpa:deploy

Source: https://github.com/canvas-medical/documentation/blob/main/collections/_guides/your-first-plugin-with-claude-code.md

Run this command to validate the plugin, bump the version, deploy it to your Canvas instance, and start log monitoring for real-time output.

```text
/cpa:deploy
```
Tokens:
Raw