---
title: "Using the Curiosity REST API to Run and Track Jobs"
slug: "using-the-curiosity-rest-api"
updated: 2026-10-13T14:03:14Z
published: 2026-10-13T14:03:14Z
canonical: "knowledge.curiositysoftware.ie/using-the-curiosity-rest-api"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.curiositysoftware.ie/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](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](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

1. Open the data activity and choose the version to run.
2. On the **Components** tab, find the **Server Process** row. The number on its badge is the server process ID (**40579** here).
3. 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 &lt;api-url&gt;/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.