> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/discover.md).

# 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.

{% hint style="info" %}
**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.
{% endhint %}

### 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:**

{% code title="Full metadata" %}

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

{% endcode %}

**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:**

{% code title="Usage agreement" %}

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

{% endcode %}

**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:**

{% code title="Semantic schema" %}

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

{% endcode %}

**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](https://bitol.io/) 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.

```
ODPS Data Product
  └── outputPorts[]
       ├── name: sales.customer_orders_enriched
       └── contractId ──────> ODCS contract id
```

### 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](https://bitol-io.github.io/open-data-contract-standard/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:**

{% code title="ODCS data contract" %}

```bash
curl -s https://$BASE_URL/api/v1/metadata/odcs/demo.retail.customer_orders_enriched \
  -H "Authorization: Bearer $TOKEN"
```

{% endcode %}

**Example response:**

```json
{
  "apiVersion": "v3.1.0",
  "kind": "DataContract",
  "id": "5870a08e-db16-5a48-8638-23cea2f93fce",
  "status": "active",
  "name": "demo.retail.customer_orders_enriched",
  "version": "1.2.0",
  "tenant": "demo",
  "domain": "sales",
  "dataProduct": "sales-analytics",
  "description": {
    "purpose": "Enriched customer orders for sales reporting"
  },
  "schema": [
    {
      "name": "demo.retail.customer_orders_enriched",
      "logicalType": "object",
      "physicalType": "table",
      "dataGranularityDescription": "One row per order_id",
      "properties": [
        {
          "name": "order_id",
          "logicalType": "string",
          "physicalType": "VARCHAR",
          "primaryKey": true,
          "primaryKeyPosition": 1,
          "tags": ["identifier"]
        },
        {
          "name": "customer_email",
          "logicalType": "string",
          "physicalType": "VARCHAR",
          "classification": "restricted",
          "tags": ["pii"]
        }
      ],
      "quality": [
        {
          "type": "custom",
          "dimension": "uniqueness",
          "name": "order_id_is_unique",
          "engine": "soda",
          "implementation": "duplicate_count(order_id) = 0"
        }
      ]
    }
  ],
  "team": {
    "members": [
      {
        "username": "sales-owner",
        "role": "owner"
      }
    ]
  },
  "slaProperties": [
    {
      "property": "frequency",
      "value": "1",
      "unit": "d",
      "scheduler": "cron",
      "schedule": "@daily"
    }
  ]
}
```

**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](https://bitol-io.github.io/open-data-product-standard/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:**

{% code title="ODPS data product" %}

```bash
curl -s https://$BASE_URL/api/v1/metadata/odps/product \
  -H "Authorization: Bearer $TOKEN"
```

{% endcode %}

**Example response:**

```json
{
  "apiVersion": "v1.0.0",
  "kind": "DataProduct",
  "id": "24fad65f-1433-5bfb-85c3-111d168c5515",
  "status": "active",
  "name": "sales-analytics",
  "version": "1.2.0",
  "domain": "sales",
  "tenant": "demo",
  "description": {
    "purpose": "Curated sales data for reporting and analytics"
  },
  "tags": ["sales", "analytics"],
  "inputPorts": [
    {
      "name": "erp.orders",
      "version": "warehouse.erp.orders",
      "contractId": "755ab0e4-f54b-5cf4-8eaf-96eb84c9966a",
      "tags": ["source"]
    }
  ],
  "outputPorts": [
    {
      "name": "demo.retail.customer_orders_enriched",
      "version": "1.2.0",
      "contractId": "5870a08e-db16-5a48-8638-23cea2f93fce",
      "description": "Enriched customer orders for sales reporting",
      "type": "full",
      "tags": ["sales"]
    }
  ],
  "team": {
    "members": [
      {
        "username": "sales-product-owner",
        "role": "product_owner"
      }
    ]
  }
}
```

**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:**

{% code title="Power BI export" %}

```bash
curl -o powerbi.zip https://$BASE_URL/api/v1/metadata/exports/powerbi \
  -H "Authorization: Bearer $TOKEN"
```

{% endcode %}

**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:**

{% code title="Tableau export" %}

```bash
curl -o tableau.zip https://$BASE_URL/api/v1/metadata/exports/tableau \
  -H "Authorization: Bearer $TOKEN"
```

{% endcode %}

**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.

```json
{
  "server_address": "https://10ax.online.tableau.com",
  "site_id": "sales-site",
  "project_name": "Data Products",
  "token_name": "vulcan-publisher",
  "personal_access_token": "<personal-access-token>"
}
```

**cURL:**

{% code title="Publish to Tableau" %}

```bash
curl -s -X POST https://$BASE_URL/api/v1/metadata/exports/tableau/publish \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server_address": "https://10ax.online.tableau.com",
    "site_id": "sales-site",
    "project_name": "Data Products",
    "token_name": "vulcan-publisher",
    "personal_access_token": "<personal-access-token>"
  }'
```

{% endcode %}

**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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/discover.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
