Skip to content
Docs

API

The Adverity Atlas REST API lets your own systems do what your team does in the product: register data sources, manage the glossary and knowledge, run automations, and fetch the files and artifacts they produce. It is the counterpart to MCP: MCP hands Adverity Atlas tools to an AI assistant, the API hands the same resources to a script, a pipeline, or a backend service.

  • Automate setup: Create workspaces, connect data sources, and keep the glossary in sync from your own source of truth

  • Run and collect: Trigger automations on your own schedule and pull their findings into other tools

  • Move files in and out: Upload files for analysis and download the files and artifacts Adverity Atlas produces

  • Govern and monitor: Read the audit trail, track AI costs, and manage members and access

Note

Asking questions in Chat is not part of the REST API. To work with Adverity Atlas conversationally from another tool, connect it over MCP.

Prerequisites

  • An Admin to create a service account and its API key

  • A workspace the integration should work in

  • An HTTPS client. Every request and response body is JSON, except file uploads and downloads

Key concepts

The API uses the product’s own vocabulary. These are the terms that come up across most endpoints.

Term

What it is

Organization

Your company’s account in Adverity Atlas. Everything else belongs to one organization

Workspace

A team’s space inside the organization, arranged as a tree. Access to a workspace includes the workspaces below it. See Workspaces

Data source

A connection to a warehouse, such as BigQuery or Snowflake. See Data sources

Collection, asset, field

What a sync finds inside a data source: a collection is a schema or dataset, an asset is a table or view in it, a field is a column

Glossary concept

A business term, such as a KPI, with its definition. Concepts live in three tiers, standard, organizational, and workspace, and the most specific one wins. See Concept layers

Business knowledge

Broader context and rules beyond single terms, such as brand guidelines. See Knowledge

Automation, run

An automation is a saved analysis on a schedule; each execution of it is a run, with its own status, output, and findings

Task execution

A background job, such as a connection diagnostic. Endpoints that start one and return its id let you check its status with the task executions endpoints

Artifact

An output saved from Chat or an automation, such as a presentation or a data app. See Artifacts

Service account

A non-human account for integrations, with its own API keys and permissions

IDs are UUIDs, and timestamps are ISO 8601 in UTC.

Authentication

Every request carries an API key, either in the X-API-Key header or as a bearer token:

curl https://<your-atlas-host>/api/v1/auth/me \
  -H "X-API-Key: $ADVERITY_API_KEY"

curl https://<your-atlas-host>/api/v1/auth/me \
  -H "Authorization: Bearer $ADVERITY_API_KEY"

There are two kinds of key.

  • Service account key: For integrations, scripts, and CI jobs. Belongs to one organization and acts with the permissions ticked on the service account. Created under Settings > Service Accounts

  • Personal API token: For your own scripts. Acts as you, with your own roles. Created with adverity tokens create once you have signed in with adverity login in the CLI

Both keys are shown once, when they are created. Store the key before closing the dialog or discarding the response.

Tip

Use a service account for anything that runs without you. Activity is then attributed to the integration in the audit log, and revoking its key leaves everyone else’s access untouched.

Choosing the organization and workspace

Two headers set the context a request runs in.

Header

When you need it

X-Tenant-ID

On every request made with a personal token, to pick which of your organizations it is for. Without it the request is answered with 400 and the error tenant_required. A service account key already belongs to one organization and does not need it

X-Workspace-ID

For workspace-scoped resources such as artifacts, when the endpoint does not take a workspace_id

A workspace the key cannot reach is answered with 403, the same as a workspace that does not exist. A service account reaches a workspace only once it has been granted access to it, with POST /api/v1/workspace-access/service-account/. Access to a workspace also covers the workspaces below it.

What you can do

The API is versioned under /api/v1/ and follows the product’s own structure. Each area has its own reference page listing every endpoint, with its parameters, request fields, and response.

  • Data sources: Create, verify, and sync connections; browse collections, assets, and fields; run profiling; resolve duplicate data

  • Glossary and knowledge: Manage glossary concepts and column classifications; add, confirm, and archive business knowledge

  • Automations: Create automations from templates, activate or pause them, run one now, and read run results

  • Files: Upload, list, rename, download, reprocess, and delete files

  • Artifacts: List, download, and delete artifacts; publish them; restore earlier versions

  • Workspaces: Create, rename, move, and delete workspaces, and configure their storage

  • People and access: Manage members, invitations, workspace access, service accounts, and single sign-on

  • Integrations: Manage webhooks, external MCP servers, and AI providers

  • Activity and monitoring: Read the audit trail, AI costs, background task status, and notifications

  • Account and organizations: Check who a key belongs to, manage personal tokens, and update your organization

Every call checks the same permission as the matching action in the product. A key can never do more through the API than its owner could in the browser.

Interactive reference

Your instance also serves an interactive version of the reference at https://<your-atlas-host>/api/v1/docs, and the machine-readable OpenAPI schema, for generating a client, at /api/v1/openapi.json. Both need you to be signed in as an Admin, or to send an API key whose owner is one. With a personal token, also send X-Tenant-ID for the organization where you are an Admin.

Example: run an automation and collect its findings

A common integration triggers an automation from your own scheduler and pushes its findings somewhere else.

  1. List automations: Find the automation in the workspace

  2. Run it: Start a run immediately

  3. Read the run: Check its status and findings

# 1. Find the automation
curl "https://<your-atlas-host>/api/v1/automations/?workspace_id=$WORKSPACE_ID" \
  -H "X-API-Key: $ADVERITY_API_KEY"

# 2. Run it now. The response holds the new run_id
curl -X POST "https://<your-atlas-host>/api/v1/automations/$AUTOMATION_ID/run/" \
  -H "X-API-Key: $ADVERITY_API_KEY"

# 3. Read the run, repeating while its status is pending, waiting, or running
curl "https://<your-atlas-host>/api/v1/automations/$AUTOMATION_ID/runs/$RUN_ID/" \
  -H "X-API-Key: $ADVERITY_API_KEY"

A run carries its status, the written output, a list of findings, and an error_message when it failed.

Example: upload a file for analysis

Files are sent as a multipart form, with the workspace they belong to:

curl -X POST "https://<your-atlas-host>/api/v1/files/upload/" \
  -H "X-API-Key: $ADVERITY_API_KEY" \
  -F "workspace_id=$WORKSPACE_ID" \
  -F "file=@campaign_plan.xlsx"

The file is processed in the background and then appears on the Files tab, ready to @mention in Chat.

Reacting to events instead of polling

To hear about changes as they happen, subscribe a webhook rather than polling the API. Each delivery is a signed POST to your endpoint, with these headers:

Header

Content

X-Adverity-Event

The event name, for example automation.run_started or file.uploaded

X-Adverity-Signature

sha256= followed by an HMAC-SHA256 of <timestamp>.<body>, keyed with the webhook secret

X-Adverity-Timestamp

Unix time the request was signed, for rejecting replays

X-Adverity-Delivery

A delivery id, the same across retries of one delivery

Responses and errors

Most list endpoints take limit and offset query parameters. Some return a plain JSON array; others wrap the page in an object with items, total, limit, and offset. The endpoint reference shows which.

Errors come back as JSON. Errors raised by Adverity Atlas carry an error message and, where useful, details. Errors raised before a request reaches it, such as a missing key or a body that does not match the schema, carry a detail field instead.

Status

Meaning

400

The request cannot be carried out as sent, for example no organization was selected or an automation is already running

401

The key is missing, revoked, or expired

403

The key’s owner lacks the permission, or cannot reach the organization or workspace

404

The resource does not exist

422

The request body failed validation

429

Too many requests. The Retry-After header holds the Unix time at which the limit resets, not a number of seconds

What’s next?

  • Automations API: every endpoint for running automations and reading their results

  • Service accounts: create the account and key an integration authenticates with

  • MCP servers: connect an AI assistant to Adverity Atlas instead of a script

  • Webhooks: get events pushed to your systems

  • Automations: build the automations the API runs

Was this page helpful?