diff --git a/docs/api/authentication.mdx b/docs/api/authentication.mdx index 76e33a2ee..00e93a2ac 100644 --- a/docs/api/authentication.mdx +++ b/docs/api/authentication.mdx @@ -74,7 +74,8 @@ Access is governed by your token's role at three levels: `env_id` returns `403`. 2. **Resource scope** — the asset, column, and lineage endpoints require the _assets_ view scope. A role that can reach the environment but isn't granted - the assets resource returns `403`. + the assets resource returns `403`. Test endpoints (**coming soon**) require + the _tests_ view scope. 3. **Per-asset access** — see below. If your token's role is restricted to a subset of an environment's assets @@ -87,9 +88,10 @@ columns and lineage edges derived from them — that you're allowed to see: - Column-lineage edges are returned only when the downstream column's asset is visible to you. A returned edge's `upstream_column_id` may reference a restricted upstream asset; only the id is exposed, not its metadata. -- **Get-one endpoints** (`/assets/{id}`, `/columns/{id}`) - return `404` for an object you can't view — the same response as a nonexistent - object, so the API never discloses that a restricted asset exists. +- **Get-one endpoints** (`/assets/{id}`, `/columns/{id}`, and coming-soon + `/tests/{id}`) return `404` for an object you can't view — the same response + as a nonexistent object, so the API never discloses that a restricted asset + or test exists. Because filtering is applied per page after rows are read, a page may contain fewer than `limit` items while `has_more` is still `true`. Always iterate on diff --git a/docs/api/incremental-sync.mdx b/docs/api/incremental-sync.mdx index 88152ba7a..b5c976408 100644 --- a/docs/api/incremental-sync.mdx +++ b/docs/api/incremental-sync.mdx @@ -72,6 +72,12 @@ Timestamps are UTC ISO-8601. | Asset lineage | ✅ | Full replace | | Column lineage | ✅ | ✅ (`synced_since`, `deleted_since`) | + + **Coming soon:** tests will use the same `synced_since` / `deleted_since` + pair as assets. Latest test executions will be a full snapshot (no incremental + feed). Per-test execution history is a time window, not an incremental feed. + + Column lineage is returned one record per edge, but edges do not have their own timestamps. The incremental filters use the downstream column's diff --git a/docs/api/introduction.mdx b/docs/api/introduction.mdx index 9a66f04c6..a5d5fd959 100644 --- a/docs/api/introduction.mdx +++ b/docs/api/introduction.mdx @@ -1,12 +1,12 @@ --- title: 'Introduction' -description: "Read Elementary's assets, columns, and lineage over a REST API." +description: "Read Elementary's assets, columns, lineage, and tests over a REST API." --- The **Elementary Public API** is a REST interface for programmatically reading -the assets, columns, and lineage Elementary tracks for one -environment. Use it to sync your data catalog and lineage into your own systems -(a warehouse, a BI tool, a data catalog, an internal service). +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 @@ -53,18 +53,22 @@ Follow `next_cursor` until `has_more` is `false` — see [Pagination](/api/pagin ## What you can read -| Resource | Endpoint | Notes | -| -------------- | ------------------------------ | ---------------------------------------- | -| Environments | `GET /environments` | Account-scoped discovery | -| Assets | `GET /{env_id}/assets` | Every asset, common fields + `kind` | -| Table assets | `GET /{env_id}/assets/tables` | Table assets + warehouse-specific fields | -| BI assets | `GET /{env_id}/assets/bi` | BI assets + BI-specific fields | -| Columns | `GET /{env_id}/columns` | Columns of assets | -| Asset lineage | `GET /{env_id}/asset-lineage` | Asset-to-asset edges | -| Column lineage | `GET /{env_id}/column-lineage` | Column-to-column edges | +| Resource | Endpoint | Notes | +| ----------------------- | ------------------------------------------------- | ----------------------------------------------- | +| Environments | `GET /environments` | Account-scoped discovery | +| Assets | `GET /{env_id}/assets` | Every asset, common fields + `kind` | +| Table assets | `GET /{env_id}/assets/tables` | Table assets + warehouse-specific fields | +| BI assets | `GET /{env_id}/assets/bi` | BI assets + BI-specific fields | +| Columns | `GET /{env_id}/columns` | Columns of assets | +| Asset lineage | `GET /{env_id}/asset-lineage` | Asset-to-asset edges | +| Column lineage | `GET /{env_id}/column-lineage` | Column-to-column edges | +| Tests | `GET /{env_id}/tests` | Test definitions. **Coming soon.** | +| Latest test executions | `GET /{env_id}/latest-test-executions` | Current run per sub-test. **Coming soon.** | +| Test execution history | `GET /{env_id}/tests/{test_id}/executions` | History for one test. **Coming soon.** | Every list endpoint supports a full scan and keyset pagination; assets and columns also expose incremental feeds — see [Incremental sync](/api/incremental-sync). +Tests will use the same incremental pair when they ship. ## Assets: one base endpoint, plus typed endpoints @@ -92,13 +96,33 @@ 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**. +**API Reference**. Test endpoints are documented there as **coming soon** until +they ship. + +## Tests (coming soon) + +Three datasets, one table each — definitions, current status, and per-test +history are not merged into a single response: + +- **[`GET /tests`](/api/reference/tests/list-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`](/api/reference/latest-test-executions/list-latest-test-executions)** — + the current run per sub-test. Full snapshot; no incremental feed in this cut. + Join to tests on `test_id`. +- **[`GET /tests/{test_id}/executions`](/api/reference/test-executions/list-test-executions)** — + history for one test (default last 30 days). Not an environment-wide dump. + +Table / relation name is a join to [table assets](/api/reference/assets/list-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`), but that set +`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 diff --git a/docs/api/reference/latest-test-executions/get-a-latest-test-execution.mdx b/docs/api/reference/latest-test-executions/get-a-latest-test-execution.mdx new file mode 100644 index 000000000..69765a3c3 --- /dev/null +++ b/docs/api/reference/latest-test-executions/get-a-latest-test-execution.mdx @@ -0,0 +1,50 @@ +--- +title: 'Get a latest test execution' +description: 'Fetch the current run for one sub-test. Coming soon.' +--- + + + **Coming soon.** This endpoint is not live yet. The contract below is the + planned shape and may change. Calling it today returns `404`. + + +``` +GET /public/beta/{env_id}/latest-test-executions/{sub_test_unique_id} +``` + +Path parameter is **`sub_test_unique_id`**, not the execution `id`. Unknown, +not permitted, or parent test not visible → `404`. + +The body's `id` is the **current** execution id and **changes** on every new +run. Use `sub_test_unique_id` as the stable key. + +## Response + +Bare object. Field meanings match +[List latest test executions](/api/reference/latest-test-executions/list-latest-test-executions). + +```json +{ + "id": "exec_9f3c2a", + "test_id": "elementary_cloud.freshness_anomalies.analytics.orders", + "sub_test_unique_id": "elementary_cloud.freshness_anomalies.analytics.orders", + "sub_type": "freshness_anomalies", + "column_name": null, + "status": "PASS", + "failure_count": 0, + "start_time": "2026-08-20T11:55:00Z", + "duration_seconds": 12.4, + "quality_dimension": "freshness", + "result_reason": "NO_ANOMALY_DETECTED", + "exception": null, + "description": null, + "synced_at": "2026-08-20T11:55:10Z" +} +``` + +## Example + +```bash +curl -H "Authorization: Bearer $ELEMENTARY_TOKEN" \ + "$BASE/$ENV_ID/latest-test-executions/$SUB_TEST_UNIQUE_ID" +``` diff --git a/docs/api/reference/latest-test-executions/list-latest-test-executions.mdx b/docs/api/reference/latest-test-executions/list-latest-test-executions.mdx new file mode 100644 index 000000000..2f5993990 --- /dev/null +++ b/docs/api/reference/latest-test-executions/list-latest-test-executions.mdx @@ -0,0 +1,87 @@ +--- +title: 'List latest test executions' +description: 'Current run per sub-test. Coming soon.' +--- + + + **Coming soon.** This endpoint is not live yet. The contract below is the + planned shape and may change. Calling it today returns `404`. + + +``` +GET /public/beta/{env_id}/latest-test-executions +``` + +Current status snapshot: one row per live sub-test, updated in place. There is +**no** incremental feed (`synced_since` / `deleted_since`) on this dataset — +re-pull the full list (or filter with `test_ids`) when you want a refresh. + +Rows whose parent test is deleted are omitted. Cloud monitors are typically +1:1 with `test_id`; dbt tests may have multiple sub-tests. + +The execution `id` on each row **changes** when a new run overwrites the row. +The stable key is `sub_test_unique_id`. + +## Query parameters + +Shared pagination: `cursor`, `limit` (default `500`, max `2000`). Filter arrays +are any-of within a param, AND across params, max `1000` values each. + +| Parameter | Notes | +| ------------------ | --------------------------------------------------------------------------------------------- | +| `sub_test_ids` | Filter by `sub_test_unique_id`. | +| `test_ids` | Latest rows for these tests. | +| `asset_ids` | Latest rows whose parent test is on these assets. | +| `test_types` | Parent test `test_type`. Extensible. | +| `definition_types` | Parent test `definition_type`. Extensible. | +| `source_types` | Parent test `source_type`. Extensible. | +| `statuses` | As stored: `PASS`, `WARN`, `FAIL`, `ERROR`, `SKIPPED`, `NO_DATA`. | +| `order_by` | `id` (default) or `synced_at`. Here `id` means **`sub_test_unique_id`**, not the execution id. | +| `direction` | `asc` (default) or `desc`. | + +## Response + +List envelope `{ items, next_cursor, has_more }`. Item shape is shared with +[test execution history](/api/reference/test-executions/list-test-executions). + +```json +{ + "items": [ + { + "id": "exec_9f3c2a", + "test_id": "elementary_cloud.freshness_anomalies.analytics.orders", + "sub_test_unique_id": "elementary_cloud.freshness_anomalies.analytics.orders", + "sub_type": "freshness_anomalies", + "column_name": null, + "status": "PASS", + "failure_count": 0, + "start_time": "2026-08-20T11:55:00Z", + "duration_seconds": 12.4, + "quality_dimension": "freshness", + "result_reason": "NO_ANOMALY_DETECTED", + "exception": null, + "description": null, + "synced_at": "2026-08-20T11:55:10Z" + } + ], + "next_cursor": "eyJ...", + "has_more": true +} +``` + +| Field | Notes | +| --------------------- | ---------------------------------------------------------------------------------------------------------- | +| `id` | This run's execution id. On latest rows it **changes** when a new run overwrites the row. | +| `sub_test_unique_id` | Stable per sub-test. Path key for get-one. | +| `status` | As stored: `PASS`, `WARN`, `FAIL`, `ERROR`, `SKIPPED`, `NO_DATA`. | +| `failure_count` | Cloud freshness/volume often `0` — the signal is `status`. | +| `quality_dimension` | Nullable. Examples: `completeness`, `uniqueness`, `freshness`, `validity`, `accuracy`, `consistency`. | +| `result_reason` | Nullable. Examples: `ANOMALY_DETECTED`, `NO_ANOMALY_DETECTED`, `PERMISSIONS_ERROR`, `NOT_ENOUGH_DATA_SAMPLES`. | +| `description` | Empty string in storage is returned as `null`. No `metrics` in this cut. | + +## Example + +```bash +curl -H "Authorization: Bearer $ELEMENTARY_TOKEN" \ + "$BASE/$ENV_ID/latest-test-executions?test_types=elementary_cloud&limit=500" +``` diff --git a/docs/api/reference/test-executions/get-a-test-execution.mdx b/docs/api/reference/test-executions/get-a-test-execution.mdx new file mode 100644 index 000000000..9bcaedd79 --- /dev/null +++ b/docs/api/reference/test-executions/get-a-test-execution.mdx @@ -0,0 +1,47 @@ +--- +title: 'Get a test execution' +description: 'Fetch one historical execution for a test. Coming soon.' +--- + + + **Coming soon.** This endpoint is not live yet. The contract below is the + planned shape and may change. Calling it today returns `404`. + + +``` +GET /public/beta/{env_id}/tests/{test_id}/executions/{execution_id} +``` + +Path `test_id` unknown or not visible → `404`. An `execution_id` that exists +but belongs to a **different** test also returns `404`. + +## Response + +Bare object. Field meanings match +[Test execution history](/api/reference/test-executions/list-test-executions). + +```json +{ + "id": "exec_9f3c2a", + "test_id": "elementary_cloud.freshness_anomalies.analytics.orders", + "sub_test_unique_id": "elementary_cloud.freshness_anomalies.analytics.orders", + "sub_type": "freshness_anomalies", + "column_name": null, + "status": "FAIL", + "failure_count": 0, + "start_time": "2026-08-20T11:55:00Z", + "duration_seconds": 12.4, + "quality_dimension": "freshness", + "result_reason": "ANOMALY_DETECTED", + "exception": null, + "description": null, + "synced_at": "2026-08-20T11:55:10Z" +} +``` + +## Example + +```bash +curl -H "Authorization: Bearer $ELEMENTARY_TOKEN" \ + "$BASE/$ENV_ID/tests/$TEST_ID/executions/$EXECUTION_ID" +``` diff --git a/docs/api/reference/test-executions/list-test-executions.mdx b/docs/api/reference/test-executions/list-test-executions.mdx new file mode 100644 index 000000000..e98e0b5fd --- /dev/null +++ b/docs/api/reference/test-executions/list-test-executions.mdx @@ -0,0 +1,75 @@ +--- +title: 'Test execution history' +description: 'Execution history for one test. Coming soon.' +--- + + + **Coming soon.** This endpoint is not live yet. The contract below is the + planned shape and may change. Calling it today returns `404`. + + +``` +GET /public/beta/{env_id}/tests/{test_id}/executions +``` + +History for **one** test — not an environment-wide dump of every run. Unknown +or not-visible `test_id` → `404`. + +There is no `synced_since` feed on this nested list. Default lookback is the +last **30 days** (`start_time >= now - 30d`) when `start_time_from` is omitted. +Default sort is `start_time` **descending**. + +Item shape is shared with +[latest test executions](/api/reference/latest-test-executions/list-latest-test-executions). +Metrics (`metric_value`, `expected_min`, `expected_max`, `chart_data`) are not +in this cut. + +## Query parameters + +Shared pagination: `cursor`, `limit` (default `500`, max `2000`). Filter arrays +are any-of within a param, AND across params, max `1000` values each. + +| Parameter | Notes | +| ----------------- | --------------------------------------------------------------------------------------------- | +| `sub_test_ids` | Filter by `sub_test_unique_id`. | +| `statuses` | As stored: `PASS`, `WARN`, `FAIL`, `ERROR`, `SKIPPED`, `NO_DATA`. | +| `start_time_from` | Inclusive lower bound (UTC ISO-8601). Default: 30 days ago. | +| `start_time_to` | Inclusive upper bound (UTC ISO-8601). | +| `order_by` | `start_time` (default) or `id`. | +| `direction` | Default `desc` when `order_by` is omitted; otherwise `asc` unless you pass `desc`. | + +## Response + +List envelope `{ items, next_cursor, has_more }`. + +```json +{ + "items": [ + { + "id": "exec_9f3c2a", + "test_id": "elementary_cloud.freshness_anomalies.analytics.orders", + "sub_test_unique_id": "elementary_cloud.freshness_anomalies.analytics.orders", + "sub_type": "freshness_anomalies", + "column_name": null, + "status": "FAIL", + "failure_count": 0, + "start_time": "2026-08-20T11:55:00Z", + "duration_seconds": 12.4, + "quality_dimension": "freshness", + "result_reason": "ANOMALY_DETECTED", + "exception": null, + "description": null, + "synced_at": "2026-08-20T11:55:10Z" + } + ], + "next_cursor": "eyJ...", + "has_more": true +} +``` + +## Example + +```bash +curl -H "Authorization: Bearer $ELEMENTARY_TOKEN" \ + "$BASE/$ENV_ID/tests/$TEST_ID/executions?limit=500" +``` diff --git a/docs/api/reference/tests/get-a-test.mdx b/docs/api/reference/tests/get-a-test.mdx new file mode 100644 index 000000000..9a15307fd --- /dev/null +++ b/docs/api/reference/tests/get-a-test.mdx @@ -0,0 +1,54 @@ +--- +title: 'Get a test' +description: 'Fetch one test definition by id. Coming soon.' +--- + + + **Coming soon.** This endpoint is not live yet. The contract below is the + planned shape and may change. Calling it today returns `404`. + + +``` +GET /public/beta/{env_id}/tests/{test_id} +``` + +Returns a single test definition, or `404` if the id does not exist or is not +visible to this token (same as [assets](/api/authentication)). + +## Response + +Bare object (not wrapped in the list envelope). + +```json +{ + "id": "elementary_cloud.freshness_anomalies.analytics.orders", + "name": "freshness_anomalies", + "test_type": "elementary_cloud", + "definition_type": "freshness_anomalies", + "source_type": "elementary_cloud", + "asset_id": "table.analytics.orders", + "column_name": null, + "severity": "ERROR", + "disabled": false, + "config": { + "sensitivity": "medium" + }, + "tags": [], + "owners": ["data-platform"], + "description": null, + "path": "elementary_cloud/freshness_anomalies", + "project": null, + "updated_at": "2026-08-20T12:00:00Z", + "synced_at": "2026-08-20T12:00:00Z", + "deleted_at": null +} +``` + +Field meanings match [List tests](/api/reference/tests/list-tests). + +## Example + +```bash +curl -H "Authorization: Bearer $ELEMENTARY_TOKEN" \ + "$BASE/$ENV_ID/tests/$TEST_ID" +``` diff --git a/docs/api/reference/tests/list-tests.mdx b/docs/api/reference/tests/list-tests.mdx new file mode 100644 index 000000000..193731047 --- /dev/null +++ b/docs/api/reference/tests/list-tests.mdx @@ -0,0 +1,97 @@ +--- +title: 'List tests' +description: 'List test definitions in an environment. Coming soon.' +--- + + + **Coming soon.** This endpoint is not live yet. The contract below is the + planned shape and may change. Calling it today returns `404`. + + +``` +GET /public/beta/{env_id}/tests +``` + +Returns test **definitions** (monitors and dbt tests) — not execution results. +Join [latest test executions](/api/reference/latest-test-executions/list-latest-test-executions) +on `test_id` for the current run. Table / relation name is a join to +[table assets](/api/reference/assets/list-table-assets) on `asset_id`, not a +field on the test. + +Supports a full scan and incremental feeds (`synced_since` / `deleted_since`), +same contract as [assets](/api/incremental-sync). A new run does **not** bump +`synced_at` on the test. + +## Query parameters + +Shared pagination: `cursor`, `limit` (default `500`, max `2000`). Filter arrays +are any-of within a param, AND across params, max `1000` values each. Pass +exactly one of `synced_since` or `deleted_since` — not both. + +| Parameter | Notes | +| ------------------ | ---------------------------------------------------------------------------------------------- | +| `ids` | Test ids. | +| `asset_ids` | Tests on these assets. | +| `test_types` | Extensible. Examples: `elementary_cloud`, `generic`, `singular`, `source_freshness`. | +| `definition_types` | Extensible. Examples: `freshness_anomalies`, `volume_anomalies`, `not_null`, `unique`. | +| `source_types` | Extensible. Examples: `elementary_cloud`, `dbt`, `python_sdk`. | +| `tags` | Any-of tag match. | +| `disabled` | `true` or `false`. | +| `order_by` | `id` (default) or `synced_at`. Incremental feeds force `synced_at` / `deleted_at` ascending. | +| `direction` | `asc` (default) or `desc`. | +| `synced_since` | Upserts feed: tests created or updated at/after this UTC ISO-8601 timestamp. | +| `deleted_since` | Tombstones feed: tests soft-deleted at/after this timestamp. Mutually exclusive with `synced_since`. | + +## Response + +List envelope `{ items, next_cursor, has_more }`. On the `deleted_since` feed, +`deleted_at` is set and other fields are last-known. + +```json +{ + "items": [ + { + "id": "elementary_cloud.freshness_anomalies.analytics.orders", + "name": "freshness_anomalies", + "test_type": "elementary_cloud", + "definition_type": "freshness_anomalies", + "source_type": "elementary_cloud", + "asset_id": "table.analytics.orders", + "column_name": null, + "severity": "ERROR", + "disabled": false, + "config": { + "sensitivity": "medium" + }, + "tags": [], + "owners": ["data-platform"], + "description": null, + "path": "elementary_cloud/freshness_anomalies", + "project": null, + "updated_at": "2026-08-20T12:00:00Z", + "synced_at": "2026-08-20T12:00:00Z", + "deleted_at": null + } + ], + "next_cursor": "eyJ...", + "has_more": true +} +``` + +| Field | Notes | +| ----------------- | ---------------------------------------------------------------------------------------------- | +| `severity` | As stored: `ERROR` or `WARNING` (extensible string). | +| `config` | JSON pass-through (sensitivity, threshold, training period, direction, …). `{}` when none. | +| `path` | Tree path (same idea as asset `path`). Not the dbt file path. | +| `project` | dbt package / namespace, when applicable. | +| `owners` | Display names. | +| `description` | Empty string in storage is returned as `null`. | + +No `column_id` and no embedded latest results. + +## Example + +```bash +curl -H "Authorization: Bearer $ELEMENTARY_TOKEN" \ + "$BASE/$ENV_ID/tests?test_types=elementary_cloud&definition_types=freshness_anomalies,volume_anomalies&limit=500" +``` diff --git a/docs/docs.json b/docs/docs.json index 80abfffe6..31a244de4 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -545,6 +545,27 @@ "api/reference/columns/get-a-column", "api/reference/column-lineage/list-column-lineage" ] + }, + { + "group": "Tests", + "pages": [ + "api/reference/tests/list-tests", + "api/reference/tests/get-a-test" + ] + }, + { + "group": "Latest test executions", + "pages": [ + "api/reference/latest-test-executions/list-latest-test-executions", + "api/reference/latest-test-executions/get-a-latest-test-execution" + ] + }, + { + "group": "Test execution history", + "pages": [ + "api/reference/test-executions/list-test-executions", + "api/reference/test-executions/get-a-test-execution" + ] } ] }