Comment on page
About the Tonic API
The Tonic API is a REST API that allows you perform Tonic tasks.
The basic API is available with the Basic and Professional licenses.
It allows you to perform most API tasks. However, you cannot use the basic API to:
- Configure table modes
- Configure generators
- Configure subsetting
The advanced API requires an Enterprise license and allows you to perform all API tasks.
You can use the advanced API to:
- Configure table modes
- Configure generators
- Configure subsetting
Tonic releases a new version of the API approximately once per quarter.
All API requests are against a specific version of the API. You include the version as a parameter in the request URL. Alternatively, you configure the version to use for all API requests.
After a version is released, no breaking changes are added to it.
Tonic API version numbers for released versions use the following format:
vYYYY.MM.PWhere:
YYYYis the release yearMMis the release month- P is the number of the patch release. The initial release of a version is 0. Patch releases do not contain any breaking changes. They are only used to fix bugs or to add other non-breaking changes such as new parameters that are not required.
For example, a release issued in July of 2023 is v2023.07.0. The first patch release on that version would be v2023.07.1.
The current release candidate version of the API always has the version
vRC.You might use the release candidate version to work on API updates for newly released features or while using a beta version of a new feature.
When you make an API request, you include the API version in the request URL.
To specify the version, use the
api-version query parameter. For example, to use v2023.07.0, add api-version=v2023.07.0 .You can specify a released version or the current release candidate.
The response also provides the API version that was used.
If you do not include the API version in your request, then Tonic uses the configured default API version. The default version must be a released version. You cannot select the release candidate version as your default version.
On the System Status tab of Tonic Settings view, Version in Use lists the version that is currently selected as the default. Before you select a default version, Version in Use is not set.
API Version section of the System Status tab on Tonic Settings view
If you do not select a specific API version to be the default, and do not provide a version in the request:
- Until January 31, 2024, Tonic uses the latest API version.
- After January 31, 2024, Tonic returns an error.
To select the default API version:
- 1.Click Select a version.
- 2.From the dropdown list, select the API version to use.
You cannot select the release candidate as the default API version.
To always use the latest API version, select Automatically apply latest.
Older versions of the Tonic API are eventually deprecated and removed.
When a version is deprecated, the response header includes the date that the version will be removed.
When a version is removed, you cannot make requests against that version.
A new API version is not guaranteed to be backward compatible with previous versions. To use the new version, you might need to update your requests.
A patch version is always compatible with the original version that it patches.
For example,
2023.10.0 is not guaranteed to be compatible with 2023.07.0.However,
2023.07.1 is guaranteed to be compatible with 2023.07.0.For the Tonic API, there is generated Swagger documentation that provides details about the API endpoints and models.
For self-hosted instances, the API documentation is bundled with the instance. The API documentation is specific to that version of Tonic.
The generated API documentation is located at <instance URL>/apidocs/index.html.
To display the API documentation for a self-hosted instance, click the actions menu at the top right, then select API Documentation.
The API Documentation option in the actions menu is linked to that URL.
This API documentation is for the current version of Tonic Cloud.
The generated documentation includes documentation for both released versions and the release candidate.
From the version dropdown list at the top right, select the version of the documentation to display.
Dropdown list to select the version of the API to display documentation for
Last modified 1mo ago