Using the Curiosity REST API to Run and Track Jobs

Curiosity is API-first: anything you set up or run in the web app can also be done through its REST API, documented as an OpenAPI 3.1 specification in Swagger. This page is a short introduction. Each Swagger group has the full detail of its endpoints, fields and responses.

Your API key is on Your Profile in the web app. Send it with every request in an X-API-KEY header.

Swagger specifications

Swagger UI	URL	What's in it
Core API	https://partner.testinsights.io/api/swagger-ui/index.html	Job Engine: jobs, server profiles and server processes. Also Admin, Test Modeller and Test Data Manager.
Test Data Management API	https://partner.testinsights.io/api/tdm/swagger-ui/index.html	Data Dictionary (connections, scans, tables, columns, keys), Data Activities, and Rules for masking, subset, defaults, generation, transform, machine learning, and queries and parameters.

On your own installation, the same pages are at <api-url>/swagger-ui/index.html and <api-url>/tdm/swagger-ui/index.html. Pick a group from the drop-down at the top of each page. Because the specification is standard OpenAPI, you can import it into tools such as Postman or generate a client in your preferred language.

What you can do

To…	Swagger group	Start with
Connect to and scan databases	TDM › Data Dictionary	`/connections`, `/metadata/definitions`
Configure masking	TDM › Rules – Masking	`/masking/rule-sets`
Configure subsets	TDM › Rules – Subset	`/subset/rule-sets`
Apply rules across many columns	TDM › Rules – Defaults	`/metadata/defaults`
Manage data activities	TDM › Data Activities	`/metadata/data-activities`
Run and track jobs	Core › Job Engine	`/job`, `/job/{job_id}/status`

Each Swagger group shows how to call its endpoints. To chain them together for a particular task, ask your Curiosity team. The rest of this page walks through the most common one: running a job.

Running a job

Running a data activity through the API does the same as pressing Run on its server process in the web app: you look up the process and its parameters, submit a job, then poll it until it finishes. The examples use one masking activity, so your IDs and parameters will differ.

You need the API base URL and API key (both on Your Profile) and the machine key of the job server, from the Machine Key column of the Server Profiles page.

1. Find the server process

Open the data activity and choose the version to run.
On the Components tab, find the Server Process row. The number on its badge is the server process ID (40579 here).
Note the data activity version ID: the version_id in the page address (3688 here).

2. Read its parameters

GET <api-url>/server-profile/server-process/40579/min?includeParameters=true returns the process name (proccessName), its scope (serverProcessScope) and its parameters. GET <api-url>/server-profile/server-process/40579/parameters returns just the parameters. For the full field lists, see the Job Engine group.

Three things Swagger doesn't spell out:

Send only parameters with showInForm: true. The others are internal.
The Run dialog fills in context parameters from the page, so you must send them yourself: parActivityVersionID (the version ID from step 1) and, where the process has it, parRuleSetVersionID.
Every value is a string. Checkboxes take "true" or "false", dropdowns take one of the options in additionalParameters, and version-ID fields take the version ID, not the parent's ID.

3. Submit the job

POST <api-url>/job
{
  "jobType": "VIPAutoExecutionJob",
  "vipAutomationJobSettings": {
    "machineKey": "<machine key>",
    "serverProcessId": 40579,
    "automationType": "<proccessName from step 2>",
    "scope": "<serverProcessScope from step 2>",
    "automationParameters": [
      { "var": "parActivityVersionID", "paramIndex": 1, "value": "3688" },
      { "var": "parRunAuditScripts", "paramIndex": 2, "value": "false" },
      ...
    ]
  }
}

var and paramIndex are each parameter's name and index from step 2.
Always send scope. Without it the job defaults to ModelTestSuite and won't run as intended.
Send every form parameter, using its defaultValue where you have no value of your own. The API doesn't fill them in.

The response includes the job id. For optional fields such as readableJobName, emailAddresses and callbackURL, see POST /job in the Job Engine group.

4. Track it

Poll GET <api-url>/job/{job_id}/status until jobState is Complete, Error or Cancelled. A job in PendingInput is waiting for a user, and one stuck in InQueue usually means its job server is offline. Logs (/job/{job_id}/log/tail), results and cancelling are all in the Job Engine group.

More ways to automate

VIP: Curiosity's process automation tool, with API calls as ready-made building blocks.
MCP server: lets AI assistants work with Curiosity, for example to draft masking rules for review.
Masking functions: a large built-in library, with national identifier formats added on request.

Tell your Curiosity team what you want to automate and we'll show you the best way to do it.