Leveraging the API

runZero provides three primary APIs as well as integration-specific endpoints:

  • The Export API provides read-only access to a specific organizations.
  • The Organization API provides read-write access to a specific organizations (Professional and Enterprise licenses).
  • The Account API provides read-write access to all account settings and organizations (Enterprise license).

To get started, you will need an export token or API key. Export API tokens and Organization API keys can be generated by going to the Organizations section in the runZero web console, clicking on the appropriate organization name, and scrolling down to the export token or API keys section. A button there will let you generate a secure API key, in the form of a long random token. You must have administrator access to generate API keys.

Account API keys are generated from the Accounts settings page. Note that the Account API requires an Enterprise license.

Once you have generated a token, your REST client should use it with the Authorization: Bearer standard header to authenticate.

To use an Account API key with the Organization API, specify the additional parameter _oid=[organization-id] in the query parameters.

API calls are rate limited. You can make as many API calls per day as you have licensed assets in your account. For example, if you have 1,000 licensed assets, you can make 1,000 API calls per day. Each API call returns rate limit information in the HTTP headers of the response:

  • X-API-Usage-Total - Total number of calls made to the API
  • X-API-Usage-Today - Number of calls made to the API today
  • X-API-Usage-Limit - Your daily API call limit, shared across all API keys
  • X-API-Usage-Remaining - The number of API calls remaining from your daily limit

Please see the Swagger documentation and runZero OpenAPI specification for details on the individual API calls.