M↓ View as Markdown ↗

Public API¶

The Actian AI Analyst Public API lets scripts and pipelines export and import a Workspace's semantic layer and AI Analysts without signing in to the UI.

Common uses:

Version control: export a Workspace on a schedule and commit the files to a Git repository.
Promotion between Workspaces: export from one Workspace (for example, a development Workspace) and import the file into another as part of a CI/CD pipeline.
Backups: keep dated copies of your models, metrics, glossary terms and AI Analysts.

Availability

Who can do this: anyone holding an active API key. Members with the Manage organization capability create and revoke keys (see API Keys).
Deployment: Actian SaaS and self-managed deployments.

What the API does¶

Version 1 of the Public API has two operations, both on the same path:

Operation	Method and path	What it does
Export	`GET /api/public/v1/environment`	Downloads the key's Workspace as a file.
Import	`PUT /api/public/v1/environment`	Uploads a file and applies it to the key's Workspace.

There is no Workspace parameter. Each API key is bound to one Workspace, and every request acts on that Workspace.

Two more paths describe the API itself and need no key:

Path	What it returns
`GET /api/public/v1/openapi.json`	The Public API specification (OpenAPI).
`GET /api/public/v1/docs`	An interactive reference built from that specification.

The API does the same work as Settings → Import / export in the product, with the same file formats, matching rules and import summary. The difference is how you are identified: Settings → Import / export uses your own sign-in and needs the Edit capability in the active Workspace, while the Public API uses an API key. See Export Semantic Layer & Agents and Import Semantic Layer & Agents for the file formats.

Base URL¶

The Public API is served on the same host you sign in to, under /api/public/v1:

https://<your AI Analyst host>/api/public/v1

Use the host you sign in to. For example, if you sign in at https://ai-analyst.example.com, the base URL is https://ai-analyst.example.com/api/public/v1. Self-managed deployments use their own host name.

Authentication¶

Send an API key as a Bearer token in the Authorization header of every export and import request:

Authorization: Bearer aia_...

API key secrets start with aia_. A header in any other form is rejected.
The word Bearer must be written exactly like this, followed by a space.
Each key works in one Workspace only. To automate several Workspaces, create a key for each one.

See API Keys to create, revoke and delete keys.

Export a Workspace¶

GET /api/public/v1/environment downloads everything in the key's Workspace. The export always covers the whole Workspace; you can't filter it by entity type.

Query parameter	Values	Default	Notes
`format`	`lossless`, `osi`	`lossless`	`lossless` is a zip with models (including relationships), metrics, glossary terms and AI Analysts. `osi` is a single Open Semantic Interchange YAML file with models and metrics.
`encoding`	`yaml`, `json`	`yaml`	Applies to the files inside a Lossless zip. Open Semantic Interchange exports are YAML only, so `format=osi&encoding=json` returns `400`.

The response is a file download:

Format	Content type	File name
Lossless	`application/zip`	`ai-analyst-export-<id>-<YYYY-MM-DD>.zip`
Open Semantic Interchange	`application/yaml`	`ai-analyst-export-<id>-<YYYY-MM-DD>.yaml`

The Lossless zip contains four files: models, metrics, glossary and agents, each as .yaml or .json depending on encoding. In the file name, <id> is an internal identifier for the Workspace (not its display name) and the date is in UTC.

# Lossless zip with YAML files (the defaults)
curl "https://<your AI Analyst host>/api/public/v1/environment" \
  -H "Authorization: Bearer $AI_ANALYST_API_KEY" \
  -o export.zip

# Lossless zip with JSON files
curl "https://<your AI Analyst host>/api/public/v1/environment?encoding=json" \
  -H "Authorization: Bearer $AI_ANALYST_API_KEY" \
  -o export-json.zip

# Open Semantic Interchange YAML
curl "https://<your AI Analyst host>/api/public/v1/environment?format=osi" \
  -H "Authorization: Bearer $AI_ANALYST_API_KEY" \
  -o export.yaml

In these examples, AI_ANALYST_API_KEY is a shell variable you set from your secrets manager. Don't paste the secret into scripts you commit.

Import into a Workspace¶

PUT /api/public/v1/environment applies a file to the key's Workspace. Send the file itself as the request body (raw bytes, not a JSON object or a form upload). The body can be:

a Lossless export zip, with YAML or JSON files;
an Open Semantic Interchange YAML file;
a single-file YAML or four-file zip exported from the previous version of the product.

The body can be up to 16 MB. Larger files are rejected with 413.

Query parameter	Values	Default	Notes
`orphaned`	`keep`, `delete`	`keep`	What to do with items in the Workspace that the file doesn't contain.

How an import is applied:

Items are matched by name. An item in the file with the same name as an existing one updates it; an item with a new name is created.
Models refer to their connection (data source) by name. Every connection the file refers to must already exist in your organization under the same name; otherwise the import is refused with 422 and the response lists the missing names.
With orphaned=keep, items that aren't in the file are left alone.
With orphaned=delete, items that aren't in the file are deleted. For a Lossless zip this covers models, metrics, glossary terms and AI Analysts; glossary terms that came from a catalog sync are never deleted. For an Open Semantic Interchange file it covers models and metrics only.
If the import fails, none of its changes are applied.

curl -X PUT "https://<your AI Analyst host>/api/public/v1/environment?orphaned=keep" \
  -H "Authorization: Bearer $AI_ANALYST_API_KEY" \
  --data-binary @export.zip

Warning

orphaned=delete removes everything in the Workspace that the file doesn't name. Run the import with orphaned=keep first, or export the target Workspace as a backup, before you use delete.

A successful import returns 200 with a summary:

{
  "created": 3,
  "updated": 5,
  "deleted": 0,
  "unchanged": 42,
  "warnings": [
    {
      "code": "<warning code>",
      "message": "<what was skipped or adjusted>",
      "entityType": "<optional>",
      "entityName": "<optional>",
      "field": "<optional>"
    }
  ]
}

The numbers above are illustrative. Each warning has a code and a message, and can name the entity and field it concerns. Read the warnings after every import: they describe parts of the file that were skipped or adjusted.

Rate limits¶

Export and import requests are limited per API key and per organization:

Limit	Value
Per API key	60 requests per minute
Per organization (all keys combined)	300 requests per minute

Minutes are counted as fixed windows in UTC. A request over either limit gets 429 with code rate_limited and a Retry-After: 60 header. Wait and retry; nothing else is blocked. The specification and interactive reference paths aren't rate limited.

Errors¶

Error responses are JSON (except 413, see below) with an error message and, in most cases, a code:

{ "error": "Authentication failed", "code": "unauthorized" }

Status	`code`	Meaning
`400`	`VALIDATION_ERROR`	A query parameter has a value the API doesn't accept (for example `format=excel`).
`400`	`invalid_query`	Export only: the combination isn't supported, such as `format=osi&encoding=json`.
`400`	`invalid_zip`, `invalid_osi`, `invalid_import`	Import only: the file can't be read, is missing required files, or contains nothing to import.
`401`	`unauthorized`	The header is missing or malformed, or the key is unknown, wrong, revoked or expired.
`402`	`ANALYST_LIMIT_EXCEEDED`	Import only: creating the AI Analyst named in `subjectName` would exceed your plan's limit. Nothing was applied.
`402`	`MODELS_PER_ANALYST_LIMIT_EXCEEDED`	Import only: an AI Analyst's model access would exceed your plan's limit. Nothing was applied.
`403`	`org_pending_deletion`	Your organization is pending deletion or being closed.
`403`	`org_on_hold`	Your organization's access is on hold.
`403`	`trial_expired`	Your organization's trial has ended.
`403`	`licence_expired`	Import only, self-managed deployments: the deployment's licence has expired. Export keeps working.
`413`		Import only: the file is larger than 16 MB.
`422`	`data_source_missing`	Import only: the file refers to connections that don't exist in your organization, or (Open Semantic Interchange) to models that don't name a connection. `names` lists the missing connections or the models without one. Nothing was applied.
`429`	`rate_limited`	Too many requests. Retry after the number of seconds in `Retry-After`.

The 413 response comes from the request parser and might not use the JSON error format. Check the status code, not the body.

Specification and interactive reference¶

Every AI Analyst deployment serves its own copy of the specification, so it always matches the version you are running:

https://<your AI Analyst host>/api/public/v1/openapi.json: the OpenAPI specification. You can download it and open it in any OpenAPI tool, or generate a client from it.
https://<your AI Analyst host>/api/public/v1/docs: an interactive reference where you can try requests with your key.

Neither path needs a key. In the product, the Public API docs link on Settings → API keys and on Settings → Import / export opens the interactive reference.

Note

The interactive reference page loads its viewer from cdn.jsdelivr.net, so the browser you open it in needs internet access. If it can't reach that site, the page stays blank. Download openapi.json instead and open it in a local OpenAPI tool.

The API Reference on this site shows the same operations.

Audit trail and history¶

Every successful export, and every import that reaches the import step whether it succeeds or fails, is recorded:

In Audit, the Initiator is the member who created the key and the Executor is the key, shown by its name.
In Settings → Import / export, the history lists API exports and imports alongside the ones made in the product. Started by shows the member who created the key, and failed imports are marked Failed.

Requests refused with 401, 403, 413 or 429, imports with an invalid orphaned value, and exports refused because of an invalid query are not recorded.

Moving from the previous API¶

If you have scripts written for the API of the previous version of the product, update them as follows:

Previous API	Current API
The host your existing scripts call (the previous product's address), with its previous path	Your AI Analyst host (see Base URL); the path is now `/api/public/v1/environment`
Secrets starting `sk_`	Secrets starting `aia_`; create new keys in Settings → API keys
Keys for the whole organization	Keys bound to one Workspace
`entities` filter on export	Removed; an export always includes the whole Workspace
`format=json` or `format=yaml`, returning a JSON or YAML document	`format=lossless` (zip) or `format=osi` (YAML), with `encoding=yaml` or `encoding=json` for the files inside a Lossless zip
Import body: a JSON object with entity arrays and `orphaned` in the body	Import body: the export file itself; `orphaned` is a query parameter
2 requests per 5 seconds per IP address, with a one-hour ban	60 requests per minute per key and 300 per minute per organization, with no ban