> 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.md).

# API reference

Endpoint specifications for integrating with the Data Product API.

The Data Product API exposes governed metadata, query interfaces, reusable results, quality and activity history, engagement features, and operational health through one consistent HTTP interface.

Use this reference when implementing an integration. Each page explains why an endpoint exists, when to use it, its parameters and payloads, expected responses, and relevant errors.

### Before you begin

Define the Data Product root, versioned API URL, and access token:

```bash
export PRODUCT_BASE_URL="https://<DATAOS_FQDN>/vulcan/tenants/<TENANT_ID>/data-products/<TENANT_ID>-<RESOURCE_NAME>"
export API_BASE_URL="$PRODUCT_BASE_URL/api/v1"
export DATAOS_TOKEN="<dataos-access-token>"
```

All endpoints under `/api/v1` require a DataOS Bearer token:

```http
Authorization: Bearer <dataos-access-token>
```

Health endpoints are mounted at `PRODUCT_BASE_URL` and do not require authentication.

### Endpoint groups

Use these pages to find the exact endpoint group you need.

<table data-card-size="large" data-view="cards"><thead><tr><th>Endpoint group</th><th data-card-target data-type="content-ref">Reference</th></tr></thead><tbody><tr><td><strong>Discover</strong><br>Read metadata, semantic definitions, ODCS/ODPS contracts, and BI artifacts.</td><td><a href="https://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/discover.md">Discover</a></td></tr><tr><td><strong>Query</strong><br>Run raw SQL, Semantic REST, Semantic SQL, and metric queries; poll and retrieve results.</td><td><a href="https://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/query.md">Query</a></td></tr><tr><td><strong>GraphQL</strong><br>Query the semantic layer and receive GraphQL-shaped results inline.</td><td><a href="https://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/graphql.md">GraphQL</a></td></tr><tr><td><strong>Perspectives</strong><br>Save, share, refresh, update, and delete reusable query results.</td><td><a href="https://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/perspectives.md">Perspectives</a></td></tr><tr><td><strong>Engagement</strong><br>Follow a Data Product, inspect adoption, and read notifications.</td><td><a href="https://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/engagement.md">Engagement</a></td></tr><tr><td><strong>Quality &#x26; Activity</strong><br>Inspect quality rules, deployment plans, execution runs, model history, and run SQL.</td><td><a href="https://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/quality-and-activity.md">Quality &amp; Activity</a></td></tr><tr><td><strong>Health</strong><br>Monitor process liveness, service readiness, and Prometheus metrics.</td><td><a href="https://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/health.md">Health</a></td></tr></tbody></table>

### Common conventions

#### Request and response formats

Send `Content-Type: application/json` with JSON request bodies. Most endpoints return JSON. Downloads and special endpoints use the following content types:

| Response                     | Content type                              |
| ---------------------------- | ----------------------------------------- |
| Usage agreement              | `text/plain`                              |
| Power BI or Tableau artifact | `application/zip`                         |
| Query result                 | JSON, YAML, CSV, or a redirect to Parquet |
| Prometheus metrics           | `text/plain`                              |

#### Pagination

List endpoints generally accept `limit` and `offset`. Paginated responses can include `pagination.limit`, `pagination.offset`, and `pagination.has_more`.

When paging through query results, apply deterministic query ordering so rows do not move between pages.

#### Timestamps

Filter parameters such as `start_ts`, `end_ts`, and `as_of_ts` use Unix timestamps in seconds unless an endpoint states otherwise. Date-only parameters use `YYYY-MM-DD`.

#### Errors

| Status | Meaning                                            | Client action                                               |
| ------ | -------------------------------------------------- | ----------------------------------------------------------- |
| `400`  | Invalid SQL or request semantics.                  | Correct the request; do not retry it unchanged.             |
| `401`  | Token is missing, malformed, invalid, or expired.  | Obtain a valid token and retry.                             |
| `403`  | Authenticated caller lacks access or ownership.    | Request access or use an authorized identity.               |
| `404`  | Requested resource or result does not exist.       | Verify the identifier and environment.                      |
| `406`  | Requested result format is unsupported.            | Use `json`, `yaml`, `csv`, or `parquet`.                    |
| `409`  | Request conflicts with existing state.             | Resolve the conflict, such as selecting another slug.       |
| `422`  | Input validation failed.                           | Correct fields, types, required values, or constraints.     |
| `429`  | Request was rate-limited.                          | Respect `Retry-After` and retry with backoff.               |
| `500`  | Unexpected server failure.                         | Retry safe reads; report persistent failures.               |
| `501`  | Configured backend does not support the operation. | Use a supported backend or contact the owner.               |
| `502`  | An upstream integration failed.                    | Retry transient failures or correct upstream configuration. |
| `503`  | A required service is unavailable.                 | Wait for readiness and retry with backoff.                  |
| `504`  | An upstream request timed out.                     | Follow endpoint-specific retry guidance.                    |

Endpoint-specific response descriptions on the following pages take precedence over this general table.

### Related guides

* Start with [Getting started](https://v2.dataos.info/references/interfaces/apis/data-product-apis/getting-started.md) for authentication, your first request, and error handling.
* Use [Querying Data Products](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products.md) to choose an interface before consulting its endpoint contract.


---

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