Usage
=====

Read this guide to learn how to install ProKnow SDK and get started with your first script.

Installation
------------

Use ``pip`` to install::

    pip install --upgrade proknow

Basic Usage
-----------

To use the SDK, you'll need two important items:

* Base URL: This is the URL that will be used to make API requests to ProKnow. It's the first part of the web address you see when you are signed in to your ProKnow DS account. The form of this URL is typically ``https://your-domain.proknow.com``.
* API Token: You can generate an `API token <https://support.proknow.com/hc/en-us/articles/360019798893-Configuring-Your-Profile#managing-api-keys>`_ in the ProKnow DS user interface. Always keep your API Token secret. Once you have your ``credentials.json``, make note of the file path.

The code snippet below can be used to test your installation of the ``proknow`` package. Please be sure to replace ``https://example.proknow.com`` with your organization's Base URL described above, and replace ``./credentials.json`` with the path to your credentials file::

    from proknow import ProKnow

    pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
    workspaces = pk.workspaces.query()
    print("The workspaces are as follows:")
    for workspace in workspaces:
        print(workspace.name)

If an adaptation of the script above does not work for you see the troubleshooting section below.

Feature List
------------

❌ - Not Implemented ✅ - Implemented

+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| Status                | Description                                                | Route                                                                    |
+=======================+============================================================+==========================================================================+
| ❌                    | Resolve the organization client from the current subdomain | ``GET /api/organization/resolve``                                        |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Get the current organization details                       | ``GET /api/organization``                                                |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Updates the current organization settings                  | ``PATCH /api/organization``                                              |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Create a group                                             | ``POST /api/groups``                                                     |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List groups                                                | ``GET /api/groups``                                                      |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update a group                                             | ``PATCH /api/groups/:gid``                                               |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Delete a group                                             | ``DELETE /api/groups/:gid``                                              |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List group members                                         | ``GET /api/groups/:gid/members``                                         |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Add a group member                                         | ``PUT /api/groups/:gid/members/:mid``                                    |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Delete a group member                                      | ``DELETE /api/groups/:gid/members/:mid``                                 |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Create a role                                              | ``POST /api/roles``                                                      |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | List roles                                                 | ``GET /api/roles``                                                       |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get a role                                                 | ``GET /api/roles/:rid``                                                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update a role                                              | ``PATCH /api/roles/:rid``                                                |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete a role                                              | ``DELETE /api/roles/:rid``                                               |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List role assignments                                      | ``GET /api/resources/:rid/assignments``                                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Add a role assignment                                      | ``PUT /api/resources/:rid/assignments``                                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Delete a role assignment                                   | ``DELETE /api/resources/:rid/assignments``                               |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Resolve permissions for a given resource                   | ``GET /api/resources/:rid/permissions/session``                          |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Create a user                                              | ``POST /api/users``                                                      |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete a user                                              | ``DELETE /api/users/:uid``                                               |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get a user                                                 | ``GET /api/users/:uid``                                                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | List users                                                 | ``GET /api/users``                                                       |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update a user                                              | ``PUT /api/users/:uid``                                                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get the current user                                       | ``GET /api/user``                                                        |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update the current user’s MFA settings                     | ``PUT /api/user/mfa``                                                    |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Delete the current user’s MFA settings                     | ``DELETE /api/user/mfa``                                                 |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update the current user’s preferences                      | ``PATCH /api/user/preferences``                                          |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Get the current user’s preferences                         | ``GET /api/user/preferences``                                            |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update the current user’s state                            | ``PATCH /api/user/state``                                                |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Get the current user’s state                               | ``GET /api/user/state``                                                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Create an API keys                                         | ``POST /api/apikeys``                                                    |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List API keys                                              | ``GET /api/apikeys``                                                     |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Delete API keys                                            | ``DELETE /api/apikeys/:id``                                              |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Create a workspace                                         | ``POST /api/workspaces``                                                 |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete a workspace                                         | ``DELETE /api/workspaces/:wid``                                          |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | List workspaces                                            | ``GET /api/workspaces``                                                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update a workspace                                         | ``PATCH /api/workspaces/:wid``                                           |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Search audit events                                        | ``POST /api/audit/events/search``                                        |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Create a custom metric                                     | ``POST /api/metrics/custom``                                             |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | List custom metrics                                        | ``GET /api/metrics/custom``                                              |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get a custom metric                                        | ``GET /api/metrics/custom/:id``                                          |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete a custom metric                                     | ``DELETE /api/metrics/custom/:id``                                       |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update a custom metric                                     | ``PUT /api/metrics/custom/:id``                                          |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Create a scorecard template                                | ``POST /api/metrics/templates``                                          |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | List scorecard templates                                   | ``GET /api/metrics/templates``                                           |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get a scorecard template                                   | ``GET /api/metrics/templates/:msid``                                     |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete a scorecard template                                | ``DELETE /api/metrics/templates/:msid``                                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update a scorecard template                                | ``PUT /api/metrics/templates/:msid``                                     |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Create an organization metric objectives set               | ``POST /api/metrics/objectives``                                         |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List organization metric objectives sets                   | ``GET /api/metrics/objectives``                                          |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update an organization metric objectives set               | ``DELETE /api/metrics/objectives/:id``                                   |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Perform a renaming rule search                             | ``POST /api/renaming/search``                                            |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | List renaming rules                                        | ``GET /api/renaming/rules``                                              |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update renaming rules                                      | ``PUT /api/renaming/rules``                                              |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Execute a renaming rule                                    | ``POST /api/renaming/rules/:id/exec``                                    |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Create a checklist template                                | ``POST /api/checklists/templates``                                       |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List checklist templates                                   | ``GET /api/checklists/templates``                                        |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update a checklist template                                | ``PUT /api/checklists/templates/:id``                                    |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Delete a checklist template                                | ``DELETE /api/checklists/templates/:id``                                 |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Create a structure set template                            | ``POST /api/structuresets/templates``                                    |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List structure set templates                               | ``GET /api/structuresets/templates``                                     |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update a structure set template                            | ``PUT /api/structuresets/templates/:id``                                 |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Delete a structure set template                            | ``DELETE /api/structuresets/templates/:id``                              |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Create a collection                                        | ``POST /api/collections``                                                |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | List collections                                           | ``GET /api/collections``                                                 |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get a collection                                           | ``GET /api/collections/:id``                                             |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete a collection                                        | ``DELETE /api/collections/:id``                                          |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update a collection                                        | ``PUT /api/collections/:id``                                             |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update workspaces for a collection                         | ``PATCH /api/collections/:id/workspaces``                                |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Get analysis data for a collection                         | ``GET /api/collections/:id/analysis/:tag``                               |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Add patients to a collection                               | ``PUT /api/collections/:id/workspaces/:wid/patients``                    |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete patients from a collection                          | ``DELETE /api/collections/:id/workspaces/:wid/patients``                 |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | List collection patients                                   | ``GET /api/collections/:id/patients``                                    |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List ROIs observed in a collection                         | ``GET /api/collections/:id/rois``                                        |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List patients in collection with specified ROI             | ``GET /api/collections/:id/rois/patients``                               |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List analysis ROIs configured for a collection             | ``GET /api/collections/:id/rois/analysis``                               |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update analysis ROIs configured for a collection           | ``PUT /api/collections/:id/rois/analysis``                               |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List collection computed metrics                           | ``GET /api/collections/:id/metrics/computed``                            |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List collection computed metric values                     | ``GET /api/collections/:id/metrics/computed/values``                     |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Add computed metrics to a collection                       | ``PUT /api/collections/:id/metrics/computed``                            |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Delete computed metrics from a collection                  | ``DELETE /api/collections/:id/metrics/computed``                         |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List collection custom metrics                             | ``GET /api/collections/:id/metrics/custom``                              |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List collection custom metric values                       | ``GET /api/collections/:id/metrics/custom/:metric``                      |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Create a bookmark for a collection                         | ``POST /api/collections/:id/bookmarks``                                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List bookmarks for a collection                            | ``GET /api/collections/:id/bookmarks``                                   |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Delete a bookmark from a collection                        | ``DELETE /api/collections/:id/bookmarks/:aid``                           |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update a bookmark for a collection                         | ``PUT /api/collections/:id/bookmarks/:aid``                              |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Create a scorecard for a collection                        | ``POST /api/collections/:id/metrics/sets``                               |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | List scorecards for a collection                           | ``GET /api/collections/:id/metrics/sets``                                |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get a scorecard for a collection                           | ``GET /api/collections/:id/metrics/sets/:msid``                          |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete a scorecard from a collection                       | ``DELETE /api/collections/:id/metrics/sets/:msid``                       |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update a scorecard for a collection                        | ``PUT /api/collections/:id/metrics/sets/:msid``                          |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List prescriptions observed in a collection                | ``GET /api/collections/:id/prescriptions``                               |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Create a patient                                           | ``POST /api/workspaces/:wid/patients``                                   |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | List patients                                              | ``POST /api/workspaces/:wid/patients/search``                            |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get a patient                                              | ``GET /api/workspaces/:wid/patients/:id``                                |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update a patient                                           | ``PUT /api/workspaces/:wid/patients/:id``                                |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete a patient                                           | ``DELETE /api/workspaces/:wid/patients/:id``                             |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update metadata for a patient                              | ``PATCH /api/workspaces/:wid/patients/metadata``                         |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Get patient state                                          | ``GET /api/workspaces/:wid/patients/:id/state``                          |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Lookup patients                                            | ``POST /api/workspaces/:wid/patients/lookup``                            |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update patient collections                                 | ``PATCH /api/workspaces/:wid/patients/:id/collections``                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Move a patient                                             | ``POST /api/workspaces/:wid/patients/:id/move``                          |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Create a scorecard for a patient                           | ``POST /api/workspaces/:wid/patients/:id/metrics/sets``                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | List scorecards for a patient                              | ``GET /api/workspaces/:wid/patients/:id/metrics/sets``                   |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get a scorecard for a patient                              | ``GET /api/workspaces/:wid/patients/:id/metrics/sets/:msid``             |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete a scorecard from a patient                          | ``DELETE /api/workspaces/:wid/patients/:id/metrics/sets/:msid``          |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update a scorecard for a patient                           | ``PUT /api/workspaces/:wid/patients/:id/metrics/sets/:msid``             |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update patient state                                       | ``POST /api/workspaces/:wid/patients/:id/state``                         |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Create a checklist for a patient                           | ``POST /api/workspaces/:wid/patients/:id/checklists``                    |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List checklists for a patient                              | ``GET /api/workspaces/:wid/patients/:id/checklists``                     |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update a checklist for a patient                           | ``PUT /api/workspaces/:wid/patients/:id/checklists/:cid``                |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Delete a checklist from a patient                          | ``DELETE /api/workspaces/:wid/patients/:id/checklists/:cid``             |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Create an item for a patient checklist                     | ``POST /api/workspaces/:wid/patients/:pid/checklists/:cid/items``        |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update an item for a patient checklist                     | ``PUT /api/workspaces/:wid/patients/:pid/checklists/:cid/items/:id``     |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update a batch of items for a patient checklist            | ``POST /api/workspaces/:wid/patients/:pid/checklists/:cid/items/update`` |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Reorder items for a patient checklist                      | ``POST /api/workspaces/:wid/patients/:pid/checklists/:cid/items/order``  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Delete items from a patient checklist                      | ``POST /api/workspaces/:wid/patients/:pid/checklists/:cid/items/delete`` |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Create a note for a patient                                | ``POST /api/workspaces/:wid/patients/:id/notes``                         |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List notes for a patient                                   | ``GET /api/workspaces/:wid/patients/:id/notes``                          |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update a note for a patient                                | ``PUT /api/workspaces/:wid/patients/:id/notes/:nid``                     |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Delete a note from a patient                               | ``DELETE /api/workspaces/:wid/patients/:id/notes/:nid``                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Create a document for a patient                            | ``POST /api/workspaces/:wid/patients/:id/documents/:name``               |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Download a document for a patient                          | ``GET /api/workspaces/:wid/patients/:id/documents/:did/:name``           |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | List documents for a patient                               | ``GET /api/workspaces/:wid/patients/:id/documents``                      |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update a document for a patient                            | ``PUT /api/workspaces/:wid/patients/:id/documents/:did``                 |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Delete a document from a patient                           | ``DELETE /api/workspaces/:wid/patients/:id/documents/:did``              |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Create a patient copy operation                            | ``POST /api/workspaces/:wid/patients/copies``                            |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Get patient copy operation details                         | ``GET /api/patients/copies/:id``                                         |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Create a task for a patient                                | ``POST /api/workspaces/:wid/patients/:id/tasks``                         |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | List tasks for a patient                                   | ``GET /api/workspaces/:wid/patients/:id/tasks``                          |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get a task for a patient                                   | ``GET /api/workspaces/:wid/patients/:id/tasks/:tid``                     |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete a task from a patient                               | ``DELETE /api/workspaces/:wid/patients/:id/tasks/:tid``                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update a study for a patient                               | ``PUT /api/workspaces/:wid/studies/:id``                                 |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Create an upload                                           | ``POST /api/workspaces/:wid/uploads``                                    |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | List uploads                                               | ``GET /api/workspaces/:wid/uploads``                                     |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete matching uploads                                    | ``DELETE /api/workspaces/:wid/uploads``                                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete an upload                                           | ``DELETE /api/workspaces/:wid/uploads/:id``                              |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Resolve upload conflicts                                   | ``POST /api/workspaces/:wid/uploads/resolve``                            |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get chunk information                                      | ``GET /api/uploads/chunks``                                              |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Post an upload chunk                                       | ``POST /api/uploads/chunks``                                             |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Create a download request                                  | ``POST /api/workspaces/:wid/downloads``                                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Create a download of audit archives                        | ``POST /api/audit/archives``                                             |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Get the status of a download                               | ``GET /api/downloads/:id/status``                                        |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Download a file                                            | ``GET /api/downloads/:id/:file``                                         |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update an entity                                           | ``PUT /api/workspaces/:wid/entities/:id``                                |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update the parent of an entity                             | ``PUT /api/workspaces/:wid/entities/:id/parent/:pid``                    |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete an entity                                           | ``DELETE /api/workspaces/:wid/entities/:id``                             |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update a batch of entities                                 | ``PATCH /api/workspaces/:wid/entities``                                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get an image set                                           | ``GET /api/workspaces/:wid/imagesets/:id``                               |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Get PET information for an image set                       | ``PUT /api/workspaces/:wid/imagesets/:id/pet``                           |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Download an image for an image set                         | ``GET /api/workspaces/:wid/imagesets/:id/images/:iid/dicom``             |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Create a structure set                                     | ``POST /api/workspaces/:wid/structuresets``                              |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get an structure set                                       | ``GET /api/workspaces/:wid/structuresets/:id``                           |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get ROI data for a structure set                           | ``GET /api/structuresets/:id/rois/:tag``                                 |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Create a draft for a structure set                         | ``POST /api/workspaces/:wid/structuresets/:id/draft``                    |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get a lock for a structure set draft                       | ``GET /api/workspaces/:wid/structuresets/:id/draft/lock``                |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Renew a lock for a structure set draft                     | ``PUT /api/workspaces/:wid/structuresets/:id/draft/lock/:lid``           |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Release a lock for a structure set draft                   | ``DELETE /api/workspaces/:wid/structuresets/:id/draft/lock/:lid``        |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Create an ROI for a structure set draft                    | ``POST /api/workspaces/:wid/structuresets/:id/draft/rois``               |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update an ROI for a structure set draft                    | ``PUT /api/workspaces/:wid/structuresets/:id/draft/rois/:rid``           |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update ROI data for a structure set draft                  | ``PUT /api/workspaces/:wid/structuresets/:id/draft/rois/:rid/data``      |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete an ROI from a structure set draft                   | ``DELETE /api/workspaces/:wid/structuresets/:id/draft/rois/:rid``        |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Commit the draft as new version of a structure set         | ``POST /api/workspaces/:wid/structuresets/:id/draft/approve``            |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Discard the structure set draft                            | ``POST /api/workspaces/:wid/structuresets/:id/draft/discard``            |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | List versions of a structure set                           | ``GET /api/workspaces/:wid/structuresets/:id/versions``                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get the status of a structure set version                  | ``GET /api/workspaces/:wid/structuresets/:id/versions/:vid/status``      |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Download the DICOM for a structure set version             | ``GET /api/workspaces/:wid/structuresets/:id/versions/:vid/dicom``       |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update a version of a structure set                        | ``PUT /api/workspaces/:wid/structuresets/:id/versions/:vid``             |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete a version from a structure set                      | ``DELETE /api/workspaces/:wid/structuresets/:id/versions/:vid``          |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Revert to a version of a structure set                     | ``POST /api/workspaces/:wid/structuresets/:id/approve/:vid``             |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get a plan                                                 | ``GET /api/workspaces/:wid/plans/:id``                                   |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Download the DICOM for a plan                              | ``GET /api/workspaces/:wid/plans/:id/dicom``                             |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Create a plan                                              | ``POST /api/workspaces/:wid/plans``                                      |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update the prescription information for a plan             | ``PUT /api/workspaces/:wid/plans/:id/prescription``                      |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update the opportunity DVH parameters for a plan           | ``PUT /api/workspaces/:wid/plans/:id/opportunity``                       |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Get the opportunity DVH for a plan                         | ``GET /api/plans/:id/opportunity/:tag``                                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get a dose                                                 | ``GET /api/workspaces/:wid/doses/:id``                                   |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Download the DICOM for a dose                              | ``GET /api/workspaces/:wid/doses/:id/dicom``                             |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get the analysis data for a dose                           | ``GET /api/doses/:id/analysis/:tag``                                     |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Update computed metrics for a dose                         | ``PUT /api/workspaces/:wid/doses/:id/metrics``                           |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get computed metrics for a dose                            | ``GET /api/workspaces/:wid/doses/:id/metrics``                           |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Create an SRO                                              | ``POST /api/workspaces/:wid/sros``                                       |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Get an SRO                                                 | ``GET /api/workspaces/:wid/sros/:id``                                    |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Delete an SRO                                              | ``DELETE /api/workspaces/:wid/sros/:id``                                 |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Update an SRO                                              | ``PATCH /api/workspaces/:wid/sros/:id``                                  |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ❌                    | Get the status of an SRO                                   | ``GET /api/workspaces/:wid/sros/:id/status``                             |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+
| ✅                    | Download the DICOM for an SRO                              | ``GET /api/workspaces/:wid/sros/:id/dicom``                              |
+-----------------------+------------------------------------------------------------+--------------------------------------------------------------------------+


Troubleshooting
---------------

**Connection errors**

These can be caused by the failure to replace ``https://example.proknow.com`` as your ``base_url``. ``https://example.proknow.com`` is not a real endpoint and will not work. If you've already replaced the base URL, login to your ProKnow DS account and check to make sure it matches the base URL shown in the address bar.

If you are able to login to your ProKnow DS account and have verified that the base URLs match, there is also a chance that your organization's firewall is configured to block traffic originating from unknown sources like your Python script. If this is the case please contact your IT department to request special permission for your script to access the ProKnow API from inside your organization's network.

**File not found errors**

If you specified a ``credentials_file`` in the ProKnow constructor, but are receiving a message saying that the file or directory does not exist, you may have a typo in your credentials file path. Correct the file path, and try again. Note that relative file paths are usually relative to the directory from which the ``python`` executable is being invoked.

**Type or Assertion errors**

These indicate that you've provided invalid parameters to the ``ProKnow`` contructor. The error message can usually point you in the right direction. Correct the parameters, and try again.

**Copying examples without modification**

The examples shown throughout this documentation are meant to be representative and are not likely to work without modification. Let's take a look at the example for the method :meth:`proknow.Patients.PatientItem.set_metadata`::

    from proknow import ProKnow

    pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
    patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
    patient = patients[0].get()
    meta = patient.get_metadata()
    meta["Genetic Type"] = "Type II"
    patient.set_metadata(meta)
    patient.save()

This script will not work in your set up for several reasons:

* Your ``base_url`` for your ProKnow account is not ``https://example.proknow.com``.
* Your ``credentials.json`` file may not be located at the path "./credentials.json."
* You probably do not have a patient with the MRN "HNC-0522c0009" in a workspace called "Clinical."
* You probably do not have a custom metric called "Genetic Type."

If you run into problems while running your script, examine the error message and make sure you didn't copy a code example without making the proper modifications. Values may need to be replaced or additional setup code may need to be added before the code you copied in order for your script to function properly.

Guides
------


.. toctree::
   :maxdepth: 2

   usage/computed_metrics
   usage/find_methods
   usage/contouring_data
   usage/dose_analysis
   usage/pydicom_primer
   usage/scorecard_objectives
   usage/patient_tasks