DataMasque's REST API for DevOps Engineers: A Practical Reference

Updated 1 July 2026

When platform engineers evaluate data masking tools on API maturity, the criteria are consistent: does the tool have a REST API on every plan tier, can configuration live in Git alongside application code, and can a pipeline trigger a run without a vendor plugin or custom integration? DataMasque was built to pass all three tests. It ships a REST API available from free trial through Enterprise, an open-source Python SDK, an open-source CLI built for agentic access, and YAML rulesets designed to live in version control alongside application code.

This guide covers each layer in detail: the API surface, exact endpoints, authentication model, the polling pattern for async jobs, and practical examples for GitHub Actions, Jenkins, and GitLab CI.

What Separates an API-First Platform from a Tool with an API Bolted On

DataMasque is API-first: masking configuration lives in a YAML file that sits in Git, and any HTTP client can trigger a run. A GUI-first masking tool locks configuration inside a vendor portal and requires custom integration work before programmatic triggering is possible.

The distinction shows up in daily workflow. With an API-first tool, a developer adds a new PII column to a schema migration PR and adds the corresponding masking rule to the same YAML file in the same PR. The change is reviewed by the same team, merged with the same approval, and the full history lives in version control. A compliance team member can audit what gets masked at any point by reading a file, with no secondary tool login required.

With a GUI-first tool, schema changes and masking configuration exist in separate systems. Keeping them in sync is a manual process. The moment the team is moving fast, the two drift apart.

The technical difference comes down to where the state lives. API-first means the ruleset is a file, whereas GUI-first means the ruleset is a row in a vendor's database, accessible only through their interface.

DataMasque's API Surface

DataMasque ships three layers of programmatic access: a REST API available on every plan tier, an open-source Python SDK built for ops automation, and an open-source CLI designed for agentic and automated access. Each layer covers a different integration style, and all three work against the same underlying API.

REST API

The REST API is the foundation. It is available on every DataMasque plan tier, which means there is no pricing penalty for building automation around it. The API follows standard HTTP conventions: JSON request and response bodies, token-based authentication in the Authorization header, and HTTP status codes. Every capability available in the DataMasque dashboard is also available through the API. For CI/CD integration, the three endpoints a DevOps engineer uses in 90% of workflows cover triggering a run, polling run status, and retrieving run logs.

Python SDK

The open-source Python SDK is built for ops automation. It ships utilities for the common pipeline patterns, such as triggering runs, waiting for completion, and handling errors, so teams do not need to re-implement the polling loop for every project. The SDK is published on GitHub and installable via pip, which means it can be added to a pipeline environment without any vendor approval process.

CLI

The open-source CLI is designed for agentic and automated access. Any pipeline step that can execute a shell command can call it. The CLI is particularly useful when a team wants to avoid writing platform-specific scripting for every CI/CD tool they support: the same CLI call works in GitHub Actions, Jenkins, GitLab CI, and any other tool that runs shell commands. Like the SDK, it is published on GitHub.

Core API Endpoints

DataMasque's three core run-management endpoints cover the full lifecycle of a masking job: trigger a run with POST /api/runs/, poll for completion with GET /api/runs/{id}/, and retrieve job logs with GET /api/runs/{id}/log/. These three calls are all a CI/CD pipeline needs to integrate masking as a gated stage.

Trigger a Masking Run: POST /api/runs/

Start a new masking run by providing the connection UUID, ruleset UUID, and an options object. The response returns a run ID you use to poll status.

curl -X POST "https://<your-datamasque-host>/api/runs/" \
 -H "Authorization: Token $DATAMASQUE_API_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "staging-mask-run",
   "source_connection": "<connection-uuid>",
   "ruleset": "<ruleset-uuid>",
   "options": {
     "run_secret": "<your-run-secret>"
   }
 }'


The response includes an id (integer), the status field set to queued, and the full Run Object. Store the id for the polling step.

Poll Run Status: GET /api/runs/{id}/

Check the current status of a run. The status field returns one of: queued, running, validating, finished, finished_with_warnings, failed, cancelling, or cancelled. A status of finished or finished_with_warnings means the run completed successfully. failed means an error occurred. validating indicates the ruleset is still being validated against the target schema: treat it the same as running in your polling loop.

curl "https://<your-datamasque-host>/api/runs/$RUN_ID/" \
 -H "Authorization: Token $DATAMASQUE_API_TOKEN"


Parse the status field from the JSON response: jq -r '.status'.

Retrieve Run Logs: GET /api/runs/{id}/log/

Fetch the full log for a run. Useful for CI/CD systems that capture and surface job output. Supports limit and offset query parameters for pagination on large runs.

curl "https://<your-datamasque-host>/api/runs/$RUN_ID/log/" \
 -H "Authorization: Token $DATAMASQUE_API_TOKEN"


For compliance use cases, GET /api/runs/{id}/run-report/ returns a CSV report and GET /api/runs/validate/ lets you cryptographically confirm that a specific run occurred against a specific ruleset, which is useful for audit evidence.

Authentication

DataMasque uses token-based authentication. Two token types serve distinct purposes: a long-lived API Token built for automated pipelines, which can trigger runs, poll status, and retrieve logs while being blocked from configuration endpoints by default, and a short-lived User Token with a 12-hour expiry that covers all endpoints. For CI/CD integration, the API Token is the correct choice.

The long-lived API Token (not the token generated from username/password) is specifically designed for use in automated scripts. It is scoped to run-management endpoints, covering triggering runs, polling status, and retrieving logs: every operation a CI/CD pipeline needs. It does not expire unless revoked. Tokens are 40-character hex strings and travel in the Authorization HTTP header:

Authorization: Token abcdef1234567890abcdef1234567890abcdef12

Tokens are scoped per user and can be rotated independently of other credentials. If a team member leaves or a token is suspected to have been exposed, rotating it does not affect any other user's access.

Storing Tokens Securely in CI/CD

Never commit the token to a repository. Inject it at runtime from your CI/CD platform's secrets store.

The token should be treated as a service account credential: created for the CI/CD service specifically, rotated on the same schedule as other infrastructure credentials, and never shared between teams.

Policy as Code: YAML Rulesets in Git

DataMasque masking configuration is stored as a YAML ruleset file. When that file lives in the application repository alongside schema migration scripts, every change to what gets masked is reviewed and auditable, with full version history, in the same PR workflow the team already uses.

A typical ruleset file for a customer-facing database looks like this:

version: "1.0"
tasks:
 - type: mask_table
   table: customers
   key: customer_id
   rules:
     - column: first_name
       hash_columns:
         - customer_id
       masks:
         - type: from_file
           seed_file: DataMasque_firstNames_mixed.csv
           seed_column: firstname-mixed
     - column: email
       masks:
         - type: from_file
           seed_file: DataMasque_emails_mixed.csv
           seed_column: email-mixed
     - column: phone_number
       masks:
         - type: imitate
           pattern: '\d{3}-\d{3}-\d{4}'
 - type: mask_table
   table: orders
   key: order_id
   rules:
     - column: customer_id
       hash_columns:
         - customer_id
       masks:
         - type: from_column
           source_column: customers.customer_id


When a developer adds a date_of_birth column to the customers table in a schema migration PR, the corresponding masking rule goes in the same PR. The reviewer approves both at once. There is no second login to a separate system and no risk that the schema change ships without a masking rule covering it.

The Polling Pattern

DataMasque masking jobs run asynchronously, because masking a multi-terabyte production snapshot can take minutes to hours. The correct integration calls POST /api/runs/ to start a job, loops on GET /api/runs/{id}/ until the status is finished or failed, then exits non-zero on failure to gate every downstream pipeline stage.

The polling loop is a standard pattern; it takes about 10 lines of shell. Holding a synchronous HTTP connection open for the duration of a masking run is not practical in CI/CD environments, so the async model is the right approach. The examples below show the complete pattern for the three most common CI/CD platforms.

GitHub Actions

jobs:
 provision-masked-data:
   runs-on: ubuntu-latest
   steps:

     - name: Trigger DataMasque masking run
       id: masking
       run: |
         RUN_ID=$(curl -s -X POST \
           "$DATAMASQUE_URL/api/runs/" \
           -H "Authorization: Token ${{ secrets.DATAMASQUE_API_TOKEN }}" \
           -H "Content-Type: application/json" \
           -d '{
             "name": "staging-run-${{ github.run_number }}",
             "source_connection": "${{ vars.DM_CONNECTION_ID }}",
             "ruleset": "${{ vars.DM_RULESET_ID }}",
             "options": {
               "run_secret": "${{ secrets.DM_RUN_SECRET }}"
             }
           }' | jq -r '.id')
         echo "run_id=$RUN_ID" >> $GITHUB_OUTPUT

     - name: Wait for masking run to finish
       run: |
         STATUS="running"
         while [ "$STATUS" = "running" ] || [ "$STATUS" = "queued" ] || [ "$STATUS" = "validating" ]; do
           sleep 15
           STATUS=$(curl -s \
             "$DATAMASQUE_URL/api/runs/${{ steps.masking.outputs.run_id }}/" \
             -H "Authorization: Token ${{ secrets.DATAMASQUE_API_TOKEN }}" \
             | jq -r '.status')
           echo "Masking status: $STATUS"
         done
         if [ "$STATUS" != "finished" ] && [ "$STATUS" != "finished_with_warnings" ]; then
           echo "Masking run failed with status: $STATUS"
           exit 1
         fi

     - name: Run integration tests
       run: ./run-tests.sh


Jenkins (Declarative Pipeline)

stage('Provision masked data') {
 steps {
   script {
     def runId = sh(
       script: """
         curl -s -X POST "${DATAMASQUE_URL}/api/runs/" \
           -H "Authorization: Token ${DATAMASQUE_API_TOKEN}" \
           -H "Content-Type: application/json" \
           -d '{"name":"staging-run","source_connection":"${DM_CONNECTION_ID}","ruleset":"${DM_RULESET_ID}","options":{"run_secret":"${DM_RUN_SECRET}"}}'
         | jq -r '.id'
       """,
       returnStdout: true
     ).trim()

     def status = 'running'
     while (status == 'running' || status == 'queued' || status == 'validating') {
       sleep(15)
       status = sh(
         script: """
           curl -s "${DATAMASQUE_URL}/api/runs/${runId}/" \
             -H "Authorization: Token ${DATAMASQUE_API_TOKEN}" \
           | jq -r '.status'
         """,
         returnStdout: true
       ).trim()
       echo "Masking status: ${status}"
     }
     if (status != 'finished' && status != 'finished_with_warnings') {
       error("Masking run failed with status: ${status}")
     }
   }
 }
}


GitLab CI

mask-data:
 stage: provision
 script:
   - |
     RUN_ID=$(curl -s -X POST "$DATAMASQUE_URL/api/runs/" \
       -H "Authorization: Token $DATAMASQUE_API_TOKEN" \
       -H "Content-Type: application/json" \
       -d "{\"name\":\"staging-run-$CI_PIPELINE_ID\"," \
       "\"source_connection\":\"$DM_CONNECTION_ID\"," \
       "\"ruleset\":\"$DM_RULESET_ID\"," \
       "\"options\":{\"run_secret\":\"$DM_RUN_SECRET\"}}" \
       | jq -r '.id')
     STATUS="running"
     while [ "$STATUS" = "running" ] || [ "$STATUS" = "queued" ] || [ "$STATUS" = "validating" ]; do
       sleep 15
       STATUS=$(curl -s "$DATAMASQUE_URL/api/runs/$RUN_ID/" \
         -H "Authorization: Token $DATAMASQUE_API_TOKEN" | jq -r '.status')
       echo "Masking status: $STATUS"
     done
     if [ "$STATUS" != "finished" ] && [ "$STATUS" != "finished_with_warnings" ]; then
       echo "Run failed with status: $STATUS"
       exit 1
     fi


The pipeline halts and alerts the team before any unmasked data reaches the test environment if the masking run returns failed or cancelled. Downstream stages (integration tests, deployment, data refresh) only execute against a freshly masked dataset.

Cross-Environment Consistency with the Run Secret

DataMasque's run secret produces deterministic masked output: the same source value combined with the same run secret always generates the same masked result across every environment, database, deployment, and run simultaneously, which makes cross-environment bug reproduction reliable.

This solves a specific problem that matters for bug investigations. If a defect only reproduces when customer_id 12345 is present in the dataset, you need dev, staging, and UAT to all mask that value identically. Without a shared run secret, the same customer ID produces three different masked values in three environments, and the bug is impossible to replicate consistently.

Pass the run_secret in the options object when triggering a run. Store it in your CI/CD secrets manager alongside the API token. DataMasque does not store the run secret itself, which means masked values cannot be reverse-engineered even if someone has access to the masking configuration.

Schema Alerting

DataMasque proactively detects new schema fields matching PII patterns and sends alerts before unmasked data can reach non-production environments, giving platform teams an automated safety net between schema changes and ruleset updates.

When a developer adds a column named tax_id, national_id, or date_of_birth to a schema migration, DataMasque identifies the new field against its built-in and custom keyword lists during the next schema discovery run and flags it for review. The alert fires before the column gets populated with production data in a non-production environment.

For teams working across large or rapidly-changing schemas, this catches the gap between "schema changed" and "ruleset updated." The YAML ruleset is the definitive record of what gets masked; schema alerting is the safety net that surfaces columns not yet covered.

API-First vs. GUI-First Masking Tools

API-first masking means the configuration is a file, the trigger is an HTTP call, and the entire workflow fits inside a standard CI/CD pipeline. GUI-first masking means configuration is locked in a vendor portal and the integration path into automation requires custom work that sits outside the standard code review process.

• Masking config location: API-first: YAML file in Git. GUI-first: Vendor portal (proprietary format).
• Trigger a run: API-first: Any HTTP client (curl, SDK, CI step). GUI-first: Custom integration or vendor-specific plugin.
• Review coverage changes: API-first: Standard PR diff. GUI-first: Log into the masking tool.
• Audit trail: API-first: Git history. GUI-first: Vendor audit log (access required).
• Works in air-gapped environments: API-first: Yes (on-premise deployment). GUI-first: Varies.

For enterprises where compliance teams need to audit masking coverage independently of the engineering team, the file-in-Git model is a meaningful operational advantage. The compliance reviewer reads a file; they do not need a vendor account.

Frequently Asked Questions

Does the DataMasque API work with on-premise CI/CD tools like Jenkins or TeamCity?

Yes. DataMasque can be deployed on-premise on Ubuntu or Red Hat Enterprise Linux, and its REST API is accessible from any tool that can make HTTP requests. Jenkins, TeamCity, Bamboo, and self-hosted GitLab CI runners all work identically to cloud-native tools: the pipeline makes an authenticated POST to the DataMasque API endpoint, polls for completion, and gates on the result.

How do we handle masking rulesets when the schema changes mid-sprint?

DataMasque masking rulesets live in the application repository as YAML files and are updated in the same PR as the schema migration. When a developer adds a column that contains PII, the masking rule for that column goes into the ruleset file in the same PR, reviewed by the same approver. DataMasque's schema alerting flags any new columns matching sensitive data patterns that are not yet covered by a masking rule, providing an additional check before data flows into non-production environments.

Does high-frequency pipeline use affect pricing?

DataMasque pricing is based on environments rather than per-job or per-record volume. Running the masking step on every pull request, every nightly build, and every on-demand refresh costs the same as running it once a month. There is no economic incentive to mask less frequently, which removes the stale-data problem that per-record pricing creates.

How does DataMasque maintain consistency across dev, staging, and UAT simultaneously?

DataMasque enforces referential integrity on every run, keeping relationships intact not just across tables within a single database, but across databases, deployments, and environments simultaneously, including structured tables and unstructured sources such as call transcripts and clinical notes. The run secret extends this across environments: provide the same run secret to all three environment masking jobs and customer_id 12345 resolves to the same masked value in dev, staging, and UAT. This is the mechanism ADP uses to deliver consistent masked data across test environments. As Venkat Narra, Principal Design Engineer at ADP, put it, DataMasque has been "integrated into our toolkit to guarantee irreversible masked data in our test environments, offering both agility and simplicity."

Next Steps

View the DataMasque API documentation: full endpoint reference including run objects, connection management, ruleset management, and the Git integration setup guide.

Request a demo to see the API in your environment: guided proof of concept against your actual database and pipeline toolchain.

For deeper context on how masking integrates with CI/CD pipelines, see Integrating Data Masking into CI/CD Pipelines: An API-First Approach. For referential integrity handling across complex schemas, see What Is Referential Integrity in Data Masking and Why It Matters.

Updated 1 July 2026. Technical specifications reflect DataMasque platform v3.26.11.0. For the latest API documentation, visit portal.datamasque.com/portal/documentation.