Performing Tonic tasks with the Tonic API

For more detailed information about the Tonic API endpoints, parameters, and responses, see the Tonic API Documentation.

Create an API token

Before you can use the API, you must have an API token. The API token grants you the same permissions that you have in the Tonic application.
You create API tokens from the User Settings view in Tonic.
To display the User Settings view:
  1. 1.
    Click the actions menu at the top right of the Tonic screen.
  2. 2.
    In the actions menu, select User Settings.
On the User Settings view, to create a token, click Create Token.
User API Tokens list on the User Settings view
After you create the token, set your authorization header to Authorization: Apikey <token>.
This type of token does not expire. The user who creates the token can revoke it.

Create a workspace

To create a workspace, use:
POST /api/Workspace
If the request to create the workspace is successful, the response returns id, the workspace identifier.
You need the workspace identifier to make requests to update or run data generation jobs on the workspace.
For information on how to retrieve the workspace identifier for an existing workspace, see Getting the workspace ID.

Connect to the source database

To configure the connection to the source database for the workspace, use:
PUT /api/DataSource/source_db
You specify the data connector type, and provide the required connection details for that data connector type.

Connect to the destination database

Before you can run data generation, you must configure the connection to the destination database. To do this, use:
PUT /api/DataSource/destination_db
The destination database must use the same data connector type as the source database. You provide the required connection details based on the data connector type.

Assign table modes to source database tables

By default, each table is assigned the Masked (De-Identify) table mode.
To change the assigned table mode for a set of tables, use:
POST /api/Workspace/{workspaceId}/bulk_table_mode
The request provides a list of tables to update, and the table mode (tableModeEnum) to assign to those tables.
For example:
"tables": [
"schema": "public",
"table": "customers_legacy"
"schema": "public",
"table": "legacy_wo"
"tableModeEnum": "Truncated"
The available values for tableModeEnum are:
  • Masked - Indicates to use De-Identify table mode.
  • Synthesized - Indicates to use Scale table mode. Note that for Scale mode, you can specify a number of rows to generate. The default is 100. You cannot use the API to set the number of rows. You must use the Tonic application.
  • Truncated - Indicates to use Truncate table mode.
  • PreserveDestination - Indicates to use Preserve Destination table mode.
  • Incremental - Indicates to use Incremental table mode. Note that for Incremental mode to work, you must specify a date updated column to use. You cannot use the API to select the column. You must use the Tonic application.
For more information about each table mode, see Table modes.

Assign generators to columns in a table

By default, columns are assigned the Passthrough generator, which copies the data as is from the source database to the destination database.
To specify and configure the assigned generators for columns in a table, use:
PUT /api/Workspace/{workspaceId}/update_replacements/{schema}/{table}
Note that when you use this endpoint, you must always specify the configuration for all of the columns in the table for which to override the default Passthrough generator.
The request replaces all of the current column configuration in the table with the configuration that is in the request.
For columns that are not in the request, the assigned generator reverts to Passthrough.

Check for and resolve schema changes

Before you start a data generation job, we recommend that you check for and resolve any schema changes on the source database.
You can use the Schema Changes view to review and resolve any changes.
From the API:
  • To view the list of schema changes, use GET /api/SchemaDiff.
  • To resolve schema changes, use POST /api/SchemaDiff/resolve_multiple.
For non-conflicting schema changes (new tables and columns), Tonic does not make any changes to the configuration.
For information on how Tonic resolves conflicting schema changes, see How Tonic resolves conflicting issues.

Add a data generation job to the queue

After you complete the workspace configuration and verify that there are no conflicting schema changes, to start a data generation job, use:
POST /api/GenerateData/start
If the request to create the job is successful, the response returns id, the identifier of the job.
You use the job identifier to monitor the job.

Monitor the status of a job

After you create the data generation job, to get the status of the job, use:
GET /api/job/{jobId}
You can poll this API endpoint regularly to get periodic updates on the job status.
For information on how to use the Tonic application to track job status, see Viewing jobs and job details.