For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Skip to content

Discover

Find the API contracts that expose a Data Product's metadata and semantic model.

Use Discover APIs before querying a Data Product. They explain what the product contains, what fields mean, how it is governed, and which integration artifacts are available.

Understand what a Data Product exposes: models, columns, semantic schema, lineage, ODCS and ODPS contracts, and BI tool artifacts. Start here when onboarding a new consumer or building a catalog UI.

Read a Data Product's catalog, contracts, and BI export artifacts.

Metadata

Retrieve Data Product metadata: model definitions, semantic schema, and lineage graph.

Fingerprint tip: The fingerprint field changes whenever a new plan is applied. Cache it and compare to detect schema changes cheaply, with no need to diff the full response body.

Full product metadata

API endpoint: GET /api/v1/metadata

Description: Returns the complete Data Product catalog. Use it to build catalog pages, inspect models and columns, traverse lineage, discover gateways, or evaluate scheduler readiness. It includes product identity, environment, version, fingerprint, model definitions, gateway information, and governance metadata. The full response includes lineage and scheduler-readiness information.

The response includes a status array showing freshness (is_pending, last run time, cron boundaries) for each model. Status includes missing intervals and nominal run boundaries. The fingerprint changes whenever a new plan is applied.

cURL:

Full metadata
curl -s https://$BASE_URL/api/v1/metadata \
  -H "Authorization: Bearer $TOKEN"

Returns: 200 OK with a JSON object containing name, env, version, fingerprint, models[] (name, kind, cron, columns), graph (nodes + edges), gateway, governance metadata, and status[] (one freshness entry per model).

Key query params: minimal (default false): when true, returns a slim catalog without graph, missing_intervals, nominal_runs, or index.

Usage agreement

API endpoint: GET /api/v1/metadata/agreement

Description: Human-readable usage agreement configured for the Data Product. Present it before granting access or allowing a consumer to build on the data. Returns 404 when no agreement text is configured.

cURL:

Returns: Markdown or plain-text usage agreement. 404 if none is configured.

Semantic schema

API endpoint: GET /api/v1/metadata/semantic

Description: Lightweight representation of the semantic layer: models, measures, dimensions, and named metrics. Use it to populate a query builder and validate member names before semantic queries. Query execution happens through /query, not this endpoint. The fingerprint changes when a new plan is applied.

cURL:

Returns: JSON object with name, tenant, fingerprint, and models[]: each model lists its kind (SEMANTIC or METRIC) and columns[] with kind (measure/dimension) and name.

Open data standards: ODCS and ODPS

Vulcan translates its environment catalog into portable, vendor-neutral documents maintained by the Bitol project under the Linux Foundation AI & Data ecosystem.

Standard
Scope
Question answered

ODCS

One model

What data does this model provide, who owns it, and what can consumers expect?

ODPS

Entire Data Product

What does this product consume and expose, and how is it governed?

Each ODPS output port contains a contractId. That value matches the id of the ODCS contract for the corresponding model.

ODCS v3.1.0 data contract

API endpoint: GET /api/v1/metadata/odcs/{model_name}

Description: Retrieves one model as an Open Data Contract Standard (ODCS) v3.1.0 document, translated from the environment catalog. Catalogs, governance tools, and consuming teams can use it without depending on Vulcan's internal metadata format.

The contract can describe model purpose, identity, domain, tags, and version. It can also describe columns, logical and physical types, keys, row granularity, classifications, masking, ownership, support, quality checks, lineage, relationships, refresh frequency, gateways, compliance, residency, and legal contacts.

Path params: model_name: exact fully qualified model name from /metadata, e.g. demo.retail.customer_orders_enriched.

cURL:

Example response:

Key response fields:

Field
Description

id

Stable model-contract identifier. The matching ODPS output port uses it as contractId.

status

active in production and draft in other environments.

version

Data Product version used for this export.

schema[].properties

Column names, types, keys, descriptions, tags, classifications, and lineage when available.

schema[].quality

Soda rules and Vulcan audits configured for the model.

team and support

People responsible for the model and published help channels.

servers

Gateways and environment through which the model is served.

slaProperties

Refresh frequency derived from the model schedule.

customProperties

Additional governance information such as compliance metadata.

Returns: 200 OK with a JSON document conforming to the ODCS v3.1.0 schema for the requested model. 404 Not Found means the model name does not exist in the current environment catalog.

ODPS v1.0.0 data product

API endpoint: GET /api/v1/metadata/odps/product

Description: Retrieves the complete Vulcan deployment as one Open Data Product Standard (ODPS) v1.0.0 document. Use it to register the product in a catalog, display ownership and support, discover upstream inputs, and enumerate consumer-facing outputs.

Port
Meaning in Vulcan

inputPorts

External models or upstream datasets consumed by the product.

outputPorts

Non-external Vulcan models exposed by a discoverable product.

cURL:

Example response:

Key response fields:

Field
Description

id

Stable identifier for the Data Product document.

status

active in production and draft in other environments.

inputPorts

Upstream external models consumed by the product.

outputPorts

Published models. Each contractId identifies its ODCS contract.

team

Product members and their roles.

support

Published support and issue-reporting channels.

customProperties

Additional governance information such as compliance metadata.

To inspect one output, find its name, call /metadata/odcs/{model_name}, and confirm that the returned ODCS id matches the ODPS contractId.

Returns: 200 OK with a JSON document conforming to the ODPS v1.0.0 schema for the entire data product.

Exports

Download BI tool integration artifacts (Power BI, Tableau) generated during prod deployment.

Download Power BI artifact (.zip)

API endpoint: GET /api/v1/metadata/exports/powerbi

Description: Downloads the Power BI connection bundle generated during the latest production deployment.

cURL:

Returns: 200 OK with an application/zip bundle. 404 Not Found applies outside prod, before artifact generation, or when the artifact is unavailable.

Download Tableau artifact (.zip)

API endpoint: GET /api/v1/metadata/exports/tableau

Description: Downloads the Tableau connection bundle generated during the latest production deployment.

cURL:

Returns: 200 OK with an application/zip bundle. 404 Not Found applies outside prod, before artifact generation, or when the artifact is unavailable.

Publish Tableau data source

API endpoint: POST /api/v1/metadata/exports/tableau/publish

Description: Publishes the product's semantic models to Tableau Cloud or Tableau Server as a single data source, using the Tableau artifact from the last prod deployment. The target project is created if missing; an existing data source with the same name is overwritten.

Request body: Use either Personal Access Token or username/password authentication. server_address and site_id identify the Tableau destination. project_name is optional.

cURL:

Returns: 200 OK with the Tableau server, site, project, data-source name, and published data-source ID. Credentials in the request body authenticate this call only. They are never stored, logged, or cached. Available only in prod.

404 Not Found means the production artifact is unavailable. 502 Bad Gateway means Tableau authentication, connection, or publishing failed.

Last updated

Was this helpful?