API overview

Warning

The RiskScape Platform API is provided as-is, and is subject to change without notice.

Most users interact with the RiskScape Platform by logging in via their web browser. However, the RiskScape Platform also has a web API that you can use to automate tasks, instead of clicking through in your web browser manually.

The RiskScape Platform API is aimed at advanced users who have some web development expertise. The API lets you interact with the RiskScape Platform programmatically, which means you can integrate the RiskScape Platform with other third-party applications, such as customized dashboards to view model results.

The RiskScape Platform API lets you automate tasks, such as the following, from a script:

  • upload files

  • run models

  • check on scheduled model run results

  • or even create new projects

This documentation is not a comprehensive guide to every single API endpoint, but it should give you enough information to explore the API yourself and start scripting up simple API requests.

Base URL

All API requests are made under the /api path on the RiskScape Platform:

https://riskscape.nz/api

The rest of this section uses /api as a shorthand for this base URL.

Getting started

The root of the API, /api, lists the top-level resources you can access, such as:

  • /api/projects

  • /api/organizations

  • /api/users

  • /api/session

The API is “browsable”, so the simplest way to explore the RiskScape Platform API is in your web browser. Make sure you’re logged in to the Platform and then open https://riskscape.nz/api in your browser - you should see an HTML page with clickable links, supported actions, and a list of resources available.

Note

What you can do in the API is still limited by your Platform account’s access permissions. For example, to view an /api/organizations resource, you would need to be an admin user for that particular organization.

API access in more detail

  • API conventions covers the general rules that apply across the API, such as request and response formats, and how errors are reported.

  • Authentication covers how to authenticate your requests.

  • WebDAV

  • Worked examples has worked, end-to-end examples of common tasks.