> 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/getting-started/postman-collection.md).

# Postman collection

The DataOS Data Product API ships with a ready-to-use Postman collection that covers every endpoint — Health, Metadata, Data Quality, Activity, Data Query, Perspectives, Notifications, and Followers. Import it once, set two variables, and you can run any request against your data product without writing a line of code.

## Downloading the collection

1. Open your data product in the DataOS UI.
2. Go to **Activate → APIs**.
3. Click **Download Postman Collection** on the **Build on the APIs** page.

The downloaded file is a `.json` collection you import directly into Postman.

## Importing into Postman

1. Open Postman and click **Import** (top-left).
2. Drag-and-drop the downloaded `.json` file, or click **Choose Files** and select it.
3. Postman will create a new collection called **DataOS Data Product API**.

## Setting collection variables

The collection uses two variables that drive every request. Set them once at the collection level — you never need to touch individual requests.

<table><thead><tr><th width="135.2283935546875">Variable</th><th width="256.9073486328125">Value</th><th>Example</th></tr></thead><tbody><tr><td><code>base_url</code></td><td>Your data product's base URL (without <code>/api/v1</code>)</td><td><code>https://example.dataos.io/vulcan/tenants/public/data-products/public-b2b_saas</code></td></tr><tr><td><code>access_token</code></td><td>Your DataOS API token</td><td><code>dapi_abc123...</code></td></tr></tbody></table>

**To set the variables:**

1. Click the collection name in the left sidebar.
2. Open the **Variables** tab.
3. Enter `base_url` and `access_token` in the **Current Value** column.
4. Click **Save**.

> **Token expiry:** DataOS tokens are short-lived. If you receive a `401 Unauthorized` response, generate a new token and update `access_token` in the collection variables.

## Authentication

The collection uses Bearer token authentication at the collection level. Every request automatically includes:

```
Authorization: Bearer {{access_token}}
```

You do not need to set an `Authorization` header on individual requests. If you override auth on a specific request, remove the override to restore the collection-level default.

## Collection structure

Requests are organized into folders that map to the API groups:

<table><thead><tr><th width="158.92291259765625">Folder</th><th>What it contains</th></tr></thead><tbody><tr><td><strong>Health</strong></td><td><code>GET /livez</code> and <code>GET /readyz</code> — liveness and readiness probes</td></tr><tr><td><strong>Metadata</strong></td><td>Full product metadata, semantic schema, and BI export downloads (Power BI, Tableau)</td></tr><tr><td><strong>Data Quality</strong></td><td>Quality summary, rule catalog, and per-rule execution history</td></tr><tr><td><strong>Activity</strong></td><td>Deployment plans, git diffs, and execution run history</td></tr><tr><td><strong>Data Query</strong></td><td>Raw SQL, Semantic REST, Semantic SQL, GraphQL, named metrics, and usage analytics</td></tr><tr><td><strong>Perspectives</strong></td><td>Create, list, fetch, update, and delete saved query views</td></tr><tr><td><strong>Notifications</strong></td><td>Chronological event feed for the data product</td></tr><tr><td><strong>Followers</strong></td><td>Follow/unfollow, follower list, and adoption analytics</td></tr></tbody></table>

## Running your first request

1. Expand the **Health** folder and open `GET /readyz`.
2. Click **Send**.
3. A `200 OK` response with `{"status": "ready"}` confirms the worker is up. If you see `503`, wait a moment and retry — the worker may still be starting.

## Working with async queries

All query endpoints follow an asynchronous submit → poll → fetch pattern:

1. **Submit** — send a `POST` to a query endpoint (e.g. `POST /query/statement`). You receive a `202 Accepted` response with a `statement_id`.
2. **Poll** — send `GET /query/statement/{id}` repeatedly until `status` is `SUCCESS` or `FAILED`.
3. **Fetch** — once successful, send `GET /query/statement/{id}/result` to retrieve the data.

Postman's built-in **Tests** tab can automate the poll loop using `pm.sendRequest` with a recursive call, or you can use the [Postman Flows](https://learning.postman.com/docs/postman-flows/overview/) feature to chain requests visually.

> **Cache behaviour:** Identical queries are deduplicated. The `strategy` field in the poll response tells you whether the result came from `from_cache`, `await_primary` (waiting on a duplicate in-flight query), or `execute` (a fresh run).

## Using environments

For teams working across multiple DataOS instances (e.g. dev, staging, prod), create a Postman environment for each:

1. Click **Environments** in the left sidebar → **+** to create a new environment.
2. Add `base_url` and `access_token` with the values for that instance.
3. Select the environment from the dropdown in the top-right before sending requests.

This keeps credentials separate and makes switching contexts a one-click operation.

## Exporting requests as code

Postman can generate code snippets for any request in the collection:

1. Open a request.
2. Click the **\</>** (Code) icon in the right panel.
3. Choose your language (cURL, Python, JavaScript, etc.).

This is useful when you want to move from exploration in Postman to scripting with the [SDKs](/references/interfaces/apis/getting-started/sdks.md) or raw HTTP calls.

## Related pages

* [Authentication](/references/interfaces/apis/getting-started/authentication.md) — base URL construction and token usage
* [Error Codes](/references/interfaces/apis/getting-started/error-codes.md) — HTTP status codes returned by all endpoints
* [SDKs](/references/interfaces/apis/getting-started/sdks.md) — Python and TypeScript clients for programmatic access


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/references/interfaces/apis/getting-started/postman-collection.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.