Skip to main content
The Elementary Public API is a REST interface for programmatically reading the assets, columns, lineage, and tests Elementary tracks for one environment. Use it to sync your data catalog, lineage, and test results into your own systems (a warehouse, a BI tool, a data catalog, an internal service).
This API is in active development (beta) and is not intended for production use. The interface can change — including breaking changes — while we co-design it with early adopters, and availability, stability, and support are not guaranteed. Endpoints live under /public/beta; wait for a stable v1 before depending on it in production. See Versioning.

​
Base URL

​
Quickstart

1

Get a token

Create a personal or account token in Elementary and send it as a bearer token. See Authentication.
2

Discover your environments

Each returned id is an env_id you use in every other endpoint.
3

List assets

Follow next_cursor until has_more is false — see Pagination.

​
What you can read

Every list endpoint supports a full scan and keyset pagination. Assets, columns, and tests also expose incremental feeds — see Incremental sync. Latest test executions are a full snapshot; per-test history is a time window.

​
Assets: one base endpoint, plus typed endpoints

Elementary tracks assets of several kinds — warehouse tables and views, BI dashboards and explores, semantic models, and more. They share a common set of fields but each kind also has its own attributes, so the API splits them:
  • GET /assets returns every asset of every kind with the common fields (id, name, source_type, tags, owners, timestamps, …) plus a kind discriminator. This is the complete list of lineage nodes: every asset id referenced by asset lineage or column lineage appears here, so you can resolve any edge endpoint to a node.
  • GET /assets/tables and GET /assets/bi return the same assets narrowed to a single kind, with that kind’s extra fields fully populated — warehouse coordinates (db_name, schema_name, table_name, materialization) for tables, and bi_platform / bi_type / url for BI assets. Kind-specific filters live here too (e.g. db_names on /assets/tables, bi_platforms on /assets/bi).
Why the split? A single asset shape would leave most fields null on any given row (a BI dashboard has no db_name; a table has no bi_platform). Keeping the common fields on /assets gives you a clean node list for building the lineage graph, while the typed endpoints give each kind a tight, fully-populated shape. A typical flow: page /assets to build the graph, then enrich the kinds you care about via the typed endpoints — use the kind field to decide which one. The full endpoint and schema reference is generated from the API and lives under API Reference.

​
Tests

Three datasets, one table each — definitions, current status, and per-test history are not merged into a single response:
  • GET /tests — the test definition (name, type, asset, severity, config, owners/tags). Incremental synced_since / deleted_since. A new run does not bump Test.synced_at.
  • GET /latest-test-executions — the current run per sub-test. Full snapshot; no incremental feed. Join to tests on test_id.
  • GET /tests/{test_id}/executions — history for one test (default last 30 days). Not an environment-wide dump.
Table / relation name is a join to table assets on asset_id, not a field on the test. Metric numbers behind a freshness/volume verdict are not in this cut.

​
Forward compatibility

Some string fields are extensible enums: they carry a value from a small, known set today (e.g. kind, source_type, data_platform, materialization, bi_platform, bi_type, warehouse_type, last_sync_status, test_type, definition_type, status), but that set grows as Elementary adds integrations and asset types. In the schema these fields are typed as plain strings with an Extensible enum. note and their currently-known values listed under examples — they are not a closed enum. To stay compatible as the API evolves, build your integration so that:
  • Unknown values never break you. Treat any value you don’t recognize as a safe fallback (for kind, use other) rather than failing. New values can appear in a normal, non-breaking release.
  • New fields are ignored, not rejected. We may add fields to a response; don’t configure your parser to reject unknown properties.
  • You iterate on has_more, not item counts (see Pagination).
Our side of the contract: we add enum values and fields additively without a version bump, and never silently change the meaning of an existing value. Removing or renaming a field or a known value is a breaking change and would ship under a new API version, not under beta.