Release notesAPI docs
Information portal
Structural CloudTonic.ai

About the Structural API

The Tonic Structural API is a REST API that allows you perform Structural tasks.

Basic and advanced APIs

Basic API

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

Advanced API

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 generator presets

  • Configure custom sensitivity rules

  • Configure subsetting

API versioning

Structural 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.

Version format

Released versions

Structural API version numbers for released versions use the following format:

vYYYY.MM.P

Where:

  • YYYY is the release year

  • MM is 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.

Release candidate

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.

Specifying the version for API requests

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.

Configuring a default API version for requests

If you do not include the API version in your request, then Structural 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 Structural 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.

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, Structural uses the latest API version.

  • After January 31, 2024, Structural 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.

Deprecating and removing API versions

Older versions of the Structural 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.

Backward compatibility

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.

Viewing generated API documentation

For the Structural API, there is generated Swagger documentation that provides details about the API endpoints and models.

Self-hosted instances

For self-hosted instances, the API documentation is bundled with the instance. The API documentation is specific to that version of Structural.

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.

Structural Cloud

For Structural Cloud, the generated API documentation is at https://app.tonic.ai/apidocs/index.html.

The API Documentation option in the actions menu is linked to that URL.

This API documentation is for the current version of Structural Cloud.

Selecting the version to view

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.

Last updated