Core Concepts

The Nexa APIs share a small set of conventions for URLs, environments, errors, and long-running work. Learn these once and they apply whether you’re calling the Databricks, Snowflake, Agents, or ACTG-AI service. This page covers what’s consistent across services and where they intentionally differ.

Environments

An environment is a named target — typically dev, staging, and prod — that binds a data platform (Databricks or Snowflake), a Git provider and branch, and connection settings. Most write operations happen against a specific environment, and environments can be marked protected to guard production.

Environments are first-class API resources on the data-platform service (/api/v1/environments) and are also what the Nexa CLI and the Environments settings screen manage. Each environment record carries at least:

Field	Meaning
name	Environment name, e.g. dev, staging, prod
platform	databricks or snowflake
isActive	Whether this is the currently selected environment
gitProvider / targetGitBranch	Where generated code is committed
protected	Blocks unguarded changes (e.g. production)

The CLI passes the selected environment to the API as an X-Environment-Id header alongside the bearer token, so a single set of credentials can act on multiple environments.

URLs and versioning

There is no fixed public host — the base URL is whatever your customer-managed deployment exposes for each service. What is stable is the path structure:

Service	Prefix	Versioning
Databricks Platform API	/dbx root path, then /api/v1/…	v1 in the path
Snowflake API	/api/v1/…	v1 in the path
Agents API	/api/agents/…	Unversioned path; version tracked by the spec (info.version)
ACTG-AI	/api/v1/…	v1 in the path

The data-platform services carry an explicit v1 segment; breaking changes would land under a new version prefix. Build clients against the path prefix, not against a hardcoded host.

Tip

The exact spec version (for example the Databricks API’s info.version) is published in each generated reference — Databricks, Snowflake, Agents — pin against it in CI if you need reproducibility.

Resources you’ll work with

The services expose the same domain objects the platform is built on. The most common groups:

• Catalog & metadata — databases/catalogs, schemas, tables, and views, plus a catalog sync operation that refreshes metadata from the warehouse.
• Code generation (codegen) — generate DDL, curated and consumption transforms, connectors, and projections. See Pipelines and the Curated layer.
• Pipelines & jobs — deploy and run pipelines and orchestrated jobs; track run status.
• Lineage — column- and table-level data lineage.
• Deployments & environments — promote generated assets across environments.
• Agents & automations — the Agents API’s agent lifecycle and automation promotion.

Errors

Errors return a JSON body with a detail message and the matching HTTP status code:

{ "detail": "Missing Authorization header" }

The FastAPI services wrap failures in a consistent envelope that also includes a machine-readable error_code (for example HTTP_401, AUTH_SYSTEM_FAILURE). Rely on the HTTP status code first; treat the detail string as human-readable, not as a stable contract.

Status	Typical cause
400 / 422	Malformed request or failed validation
401	Missing or invalid token (see Authentication)
403	Authenticated but not permitted (e.g. inactive account, protected environment)
404	Resource not found
503	Auth misconfiguration or an unreachable upstream (warehouse, workspace)

Request tracing

Every response includes operational headers useful for debugging and support:

• X-Request-Id — a unique ID per request, set by the request-ID middleware. Include it when filing a support ticket.
• X-Process-Time — server-side handling time in seconds.

Long-running work is asynchronous

Heavy operations — LLM mapping, conflict resolution, projection and DDL/ETL generation — do not block the HTTP call. The data-platform service enqueues them as jobs processed by the ACTG-AI worker. The pattern is:

1. POST the operation; receive a job identifier.
2. Poll the job’s status endpoint (or subscribe to its event stream) until it reaches a terminal state.
3. Read the result once the job completes.

A background reaper marks jobs failed if their worker stops sending heartbeats, so a crashed worker still surfaces a terminal status rather than hanging. Design clients to poll to completion and to treat a terminal failed state as a normal outcome to handle.