Canopy API

This page introduces you to using and developing REST APIs for Canopy.


Modern web applications are often based on separating the front-end UI code and the backend services, and ensuring proper communication using the various HTTP methods as they were intended for. Canopy adopts a (mostly) REST based approach to its own API, and we are happy for our users to develop against our API. This provides a language-agnostic way of integrating with Canopy, as an alternative to using the python interface (See: Writing plugins for Canopy).

Our API is stable in the sense that we try to avoid breaking changes where possible. Advanced warning will be provided where breaking changes are likely to occur to allow our users to determine the impact against their own API integrations. However, if we find that we need to make more frequent API changes in the future, we will fork development of a more stable API-specific server which will be preferred over our internal API.


Currently, we can support the following authentication types:

  • User-based (i.e. username and password)
  • Token based authentication

We recommend that all communications with the API server be conducted over HTTPS.

Token based authentication

Token authentication uses a header field containing a token to authenticate API users on a per call basis (Each API calls requires the token). Each user in Canopy can have a single token associated with them that allows access which their privileges and the token does not expire.

To generate a token for a user execute the following on the Canopy server as the canopy user:

canopy-manage drf_create_token USER_EMAIL_ADDRESS

This will generate a 40 character alpha numeric token which can be used to perform API actions for the associated user.

For token based authentication the 'Authorization' http header should have the value 'Token GENERATED_TOKEN'

Header field name: Authorization

Header field value: Token<SPACE><GENERATED_TOKEN>

Example http header:

Authorization: Token 2cdd70527c03ac18be79fc6a56ab11f857bd2ad9

Example usage via curl to retrieve the list of companies:

curl -v -X GET https://CANOPY_SERVER/api/company/company/ -H 'Authorization: Token 2cdd70527c03ac18be79fc6a56ab11f857bd2ad9'

Example usage via Python and the requests library:

import requests
res = requests.get(
        Authorization='Token 2cdd70527c03ac18be79fc6a56ab11f857bd2ad9'
print res.json()

Unlike user-based session authentication no CSRF token or session id is required for token based authentication.

Demo API integration

A demo API client is available at Demo API Client.

API reference

Canopy ships with a browsable API interface, which is self documenting and provides test forms for invoking different API methods (GET, POST, PUT, DELETE, etc. depending on the permissions of the user).

You can enable the browsable API interface by adding the following configuration line to /etc/canopy/canopy.ini:


And then restarting canopy: sudo systemctl restart canopy

(star) This configuration is NOT recommended for production use.

Canopy's API is grouped into a set of top-level roots, with each one providing access to a number of related sub-sections.

API rootSub-sectionsDescription


N/AA simple health check for backend services.


  • entry
  • entry_object

Provides access to the logged in user's activity log. Predominantly for internal use and UI display.

  • custom_roles
  • permissions
  • profile
  • skills
  • allgrants
  • status
  • user
  • accesscontrol

Accounts gives the user access to certain information relating to users, roles, and other account (authentication/authorisation/etc.) information on the system. This data is restricted based on the user's permissions. For example, a standard user can list user account information. However, they cannot modify it. 


API to list and manage (with sufficient privileges) custom (i.e. user defined) roles defined on the system.


API to list all permissions available on Canopy.


API to list and manage the user's profile.


API to list and manage skills available on the system, which users can link to their profile.


API to list all assigned privileges on the system (useful for debugging).


Status feedback on the logged in user.


API to list and manage users on the system.


Used for driving access control settings/updates for various UI components based on the user's access profile.

  • attackclass
  • backup (DEPRECATED)
  • category
  • compliance (DEPRECATED)
  • currency
  • frontenderror
  • industry
  • license
  • locale
  • log (placeholder)
  • logo
  • rating
  • setting
  • skill
  • substitutionvariable
  • tool
  • toolresult
  • workflowstate

Access to common settings on the server. This root allows you access various settings on the server, including skills, currency, and so on. This are global values for use in other sections of the application. Write access is based on user permissions. The root level provides a list of all global configuration elelements.


The list of attack classes defined via the admin section and used to classify findings / KB findings. This list can be read by anyone, but is managed by Administrators.


The list of categories defined via the admin section and used to group attack classes together. This list can be read by anyone, but is managed by Administrators.


A list of currencies supported by Canopy. This list can be read by anyone, but is managed by Tech Managers and Administrators.


Used to capture front-end JavaScript errors and return them to the backend for logging.


A list of company industries. This list can be read by anyone, but is managed by Administrators.


License information about the installed Canopy instance.


Local information.




Access to the license holders logo, for display in Canopy.


A list of standard rating labels (Info - Critical) used within Canopy. This is not modfiable.


A list of global settings. This list can be read by anyone, but is managed by Administrators.


Used to list the available skills that users can associate with their user profile.


A list of supported substitution variables.


A list of supported tools.


A list of imported tool result ID information.


A list of workflow states for use in the application. 

  • company
  • company_custom_field
  • files

Access to the company objects on the system. Companies can be considered things like clients or internal business units. The root level will provide steps to navigate to company sub-sections.


To access a list of companies, navigate to:


To access a single company:


/api/company/company_custo_ field

This lists the custom fields defined on the company model. Used for building the custom sections of the UI layouts.


A list of files associated with a company. These are top level files that are stored separately to project data, reports, etc.

  • contact

Access to the contact objects. Contacts store contact information that is associated with a company and can be related to a project, opportunity, phase, etc.


To access the list of contacts, navigate to:


To access a single contact:


  • project
  • project_custom_field

Access to the project objects. Projects are used to group phases together. They're a lightweight container.


To access the list of all projects, navigate to:


To access a single contact:


Note: a project is a container for 1-many phases. To access a phase and its details, see the phases endpoint.


A list of custom fields defined on the project model. Used for building the custom field sections of the UI layouts.

  • template_methodology
  • template_methodology_item
  • methodology
  • methodology_item
  • phase
  • phase_custom_field
  • finding
  • upload
  • asset
  • example
  • finding_custom_field
  • finding_reference
  • tool_field_mapping

The phase container is where all of the assessments details are linked to, such as findings, assets, examples and evidence, methodoligies, etc.


To list all phases:


To view/manage a single phase:



A list of methodologies available for use within the phase.


A list of methodology items associated with template methodllogies available for use.


A list of methodologies associated with the phase.


A list of specific methodology items associated with methodologies that have been linked to a phase.


List custom fields associated with the phase model. Managed via the Administration interface.


List and work with findings associated with a phase.


Upload files to a phase.


List and manage assets associated with a phase.


List and manage examples associated with a phase.


List custom fields associated with the finding model. These are managed via the administration section.


List and manage finding references associated with findings of a phase.


List tool fields and their mappings.

  • content
  • generated_report
  • report
  • tablerow
  • version

The reports endpoint gives access to all reports on the system - restricted by access controls.


To list all reports:


To request a specific report:



For content fields (i.e. non-table data), this is used to list the fields and their content for arrangement in the report layout.


This end point retreives generated documents, which have been generated from the report object.


For tables stored in reports, this is where the content is stored. Used for arranging table data in the report layout.


Version history table associated with each report. This is managed by report authors and also by the workflows.

  • finding
  • finding_reference
  • document
  • content
  • tablerow
  • documentupload
  • taxonomy
  • taxonomy_item

A number of different template management interfaces. Template content is a big part of Canopy's proposal to save time and ensure consistency. This section is used to manage all template information. Access in general is open to users for read purposes, but only Tech Managers and Administrators can manage.











  • events
  • resources
  • userresources

Development against this API at the moment is not recommended.


Manage and list events associated with the scheduler.


Manage and list resources associated with the schedule.


Manage and list user resources associated with the schedule.


Not supportedMessaging API, predominantly for internal use within Canopy.
/api/workflows/Not supportedWorkflow event API, predominantly for internal use within Canopy.
/api/analytics/ (experimental)Experimental. Do not use.Experimental API being used to generate analytics data in excel format. This should not be developed against.
  • opportunity
  • questionnaire
  • questionnairequestion
  • scopequestion
  • scope
  • scopefile
  • sow
  • sowcontent
  • sowtablerow
  • sowversion
  • tariff













/api/portals/ (experimental)Experimental. Do not use.This is the initial MVP version of the portal API, which is used for pushing Canopy data into a 'secure portal' (e.g. for publishing on the internet). This functionality is under development and should not be used.
  • tickettracker
  • tickets
This API endpoint is used for managing ticket trackers and querying data from them. It is managed via the Administration interface, but is accessible via projects.