What can Matia’s API do for you?

Matia's API covers more than creating integrations. It also exposes the controls to help you manage and maintain oversight of your unified data platform: running syncs from an orchestrator, deciding which data is replicated, attaching ownership and governance metadata, and exporting account activity for operational or compliance workflows.

We’ll talk through several use cases in this post, but it doesn’t cover every endpoint. The API reference covers all of the available endpoints. (Note: The examples below assume you're already comfortable with REST APIs, authentication headers, environment variables, and JSON payloads.)

Getting your API key

Every request to https://api.matia.io/v1 requires an API key in the x-api-key header.

To create one, log into your Matia tenant, go to Settings → Admin → API Tokens, then generate a new token. Give it a meaningful name and set the expiration date. When selecting a role, be sure to make sure that role has access to the operation you want to perform via the API. For instance, if you want to create an integration, ensure you add the “Integrations Editor” role. (Find the full list of roles and permissions in our docs.) Copy it when it is created and store it in your team's secret manager rather than committing it to a repository or embedding it in a script.

For local testing, export the token as an environment variable:

export MATIA_API_KEY="..."

You can verify it by listing your integrations:

curl --fail-with-body --silent --show-error \
	https://api.matia.io/v1/integrations \
	-H "x-api-key: $MATIA_API_KEY"

All of the examples below use the same environment variable.

Run an existing integration

A common reason to call Matia's API is to run an integration as one step in a larger data workflow. For example, you may want a sync to start only after an upstream job has finished, or you may want downstream transformations to wait until fresh source data has landed.

Set the ID of an existing integration, then trigger a run:

export MATIA_INTEGRATION_ID="685af4d14d1e1c4b54960eb8"

curl --fail-with-body --silent --show-error \
  -X POST \
  "https://api.matia.io/v1/integrations/$MATIA_INTEGRATION_ID/run" \
  -H "x-api-key: $MATIA_API_KEY"

The response includes an identifier for the new run. Use that identifier to retrieve its status:

export MATIA_RUN_ID="<run ID returned by the trigger request>"

curl --fail-with-body --silent --show-error \
  "https://api.matia.io/v1/integrations/$MATIA_INTEGRATION_ID/runs/$MATIA_RUN_ID" \
  -H "x-api-key: $MATIA_API_KEY"

This maps cleanly to an orchestrator such as Airflow or Prefect. A task can:

1. Call the run endpoint after its upstream dependencies succeed.
2. Save the returned run ID.
3. Poll the run-status endpoint until the run reaches a terminal state.
4. Fail the task on an unsuccessful run so the orchestrator can retry, alert, or stop downstream work.

Your Airflow or Prefect DAG can execute API request. Keep the API token in the orchestrator's secret store, keep the integration ID in deployment configuration, and let a non-successful HTTP response fail the task instead of silently continuing.

This pattern is useful for scheduled syncs, dependency-aware pipelines, controlled backfills, and workflows that don’t begin transformation work until Matia has finished loading the required data.

Control what gets replicated

Production integrations rarely need every table and column from a source. You may want to exclude an internal table, omit unused fields, or hash a sensitive column before it reaches the destination.

The schema configuration endpoints provide control at the schema, table, and column levels. Start by retrieving the current configuration for an integration:

curl --fail-with-body --silent --show-error \
  https://api.matia.io/v1/integrations/$MATIA_INTEGRATION_ID/schemas \
  -H "x-api-key: $MATIA_API_KEY"

Here is an example response:

{
  "code": "OK",
  "data": {
    "schemas": {
      "public": {
        "enabled": true,
        "tables": {
          "customers": {
            "enabled": true,
            "syncMode": "incremental",
            "cursorField": "updated_at",
            "columns": {
              "id": { "enabled": true, "isPrimaryKey": true, "hashed": false },
              "email": { "enabled": true, "isPrimaryKey": false, "hashed": false }
            }
          },
          "internal_notes": { "enabled": true, "columns": {} }
        }
      }
    }
  }
}

The following request disables public.internal_notes and enables hashing for public.customers.email:

curl --fail-with-body --silent --show-error \
  -X PATCH \
  https://api.matia.io/v1/integrations/$MATIA_INTEGRATION_ID/schemas \
  -H "x-api-key: $MATIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": {
      "public": {
        "enabled": true,
        "tables": {
          "customers": {
            "enabled": true,
            "columns": {
              "email": { "enabled": true, "hashed": true }
            }
          },
          "internal_notes": {
            "enabled": false,
            "columns": {}
          }
        }
      }
    }
  }'

Because this configuration is available through the API, it can be managed as policy rather than as a one-time setup step. A scheduled job could inspect newly discovered columns, compare them with a PII policy, and update the integration when a sensitive field appears. (You can also utilize Matia’s MCP server for this! Request access to the private preview today!)

Excluding unneeded tables and columns can also reduce the amount of data extracted, transferred, and stored at the destination, saving time and cost.

Attach operational metadata with tags

As the number of integrations and assets grows, ownership and sensitivity become difficult to infer from names alone. Tags let you attach metadata to resources such as integrations, data assets, and monitors, then use that metadata in later queries and automation.

Create a tag with POST /tags:

curl --fail-with-body --silent --show-error \
  -X POST \
  https://api.matia.io/v1/tags \
  -H "x-api-key: $MATIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pii",
    "owner": "be3b01b9-7696-469c-8236-33a5d508af0b",
    "description": "Resources that contain personally identifiable information"
  }'

The response returns the ID of the tag:

{
  "code": "OK",
  "message": "Tag created",
  "data": { "id": "6a0f0e42be640fb37252289e }
}

Assign the tag to an integration through the tag's relation endpoint, using the ID returned from the first call:

curl --fail-with-body --silent --show-error \
  -X POST \
  https://api.matia.io/v1/tags/6a0f0e42be640fb37252289e/relation \
  -H "x-api-key: $MATIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceId": "$MATIA_INTEGRATION_ID",
    "resourceType": "Integration",
    "taggedBy": "be3b01b9-7696-469c-8236-33a5d508af0b"
  }'

Tags are most useful when they follow a consistent convention. Common categories include data sensitivity, owning team, environment, and operational criticality.

One practical pattern is to combine tags with schema policy. When an automated process identifies and hashes a PII column, it can also assign a pii tag and a data-owner:<team> tag. Ownership and sensitivity then become queryable through the API instead of being maintained in a separate spreadsheet or wiki page.

Export account activity with audit logs

The audit log endpoint returns a paginated, filterable feed of account activity, including changes to integrations and tags.

The following request returns events starting on July 1, ordered from oldest to newest:

curl --fail-with-body --silent --show-error \
  -G https://api.matia.io/v1/audit-logs \
  -H "x-api-key: $MATIA_API_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "sortOrder=asc" \
  --data-urlencode "startAt=2026-07-01T00:00:00Z"

The response will contain the paginated list of logs:

{
  "code": "OK",
  "data": {
    "totalItems": 214,
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "timestamp": "2026-07-14T16:20:00Z",
        "event": "Integration paused",
        "actor": {
          "type": "user",
          "email": "engineer@example.com"
        },
        "context": {
          "ipAddress": "192.168.1.1",
          "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
        }
      }
      // ... 49 more
    ]
  }
}

Use limit and offset for pagination, sortBy and sortOrder for ordering, and startAt and endAt to restrict the time range.

A common workflow is to query this endpoint on a schedule and forward new events to a SIEM, observability platform, or object store. Store the timestamp of the last event you processed, use it as the next request's startAt value, and deduplicate records by event ID at the destination.

The actor fields distinguish user and system activity, while the context fields provide details such as IP address and user agent when available. That makes the endpoint useful both for routine troubleshooting and for compliance evidence collection.

Other API capabilities

The endpoints above are useful in day-to-day platform work, but they are only a small part of the API. Other capabilities include:

• Assets (POST /assets, PATCH /assets/{id}): Register and update metadata for source and destination assets.
• Integrations (GET /integrations, POST /integrations, and GET, PATCH, or DELETE /integrations/{id}): Create and manage integrations.
• Table columns (GET /integrations/{id}/schemas/{schema}/tables/{table}/columns): Inspect column-level configuration for a single table without retrieving the full schema tree.
• Users (GET /users): List users and resolve identifiers used by fields such as owner and taggedBy.

The API reference contains the complete request and response details for these endpoints.

Where the API fits

Matia's API is most useful when it participates in systems your team already operates:

• Trigger a sync from Airflow, Prefect, or another orchestrator, then gate downstream work on the run result.
• Apply schema-selection and masking rules from a policy service.
• Add ownership and sensitivity metadata from an internal service catalog.
• Export audit events into an existing security or compliance pipeline.

The result is a set of repeatable workflows that can be reviewed, tested, scheduled, and monitored alongside the rest of your data platform.