> 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/concepts/foundations/activation/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 — Discover, Query, GraphQL, Perspectives, Engagement, and Quality & Activity. 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 **Vulcan API — \[your data product name]**.

## 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 six top-level folders:

<table><thead><tr><th width="195">Folder</th><th width="220">Subfolder</th><th>What it contains</th></tr></thead><tbody><tr><td><strong>Discover</strong></td><td>Metadata</td><td>Full product metadata and semantic schema</td></tr><tr><td></td><td>Exports</td><td>Download Power BI and Tableau artifacts</td></tr><tr><td><strong>Query</strong></td><td>Query Result</td><td>Poll statement status; fetch results as JSON or Parquet</td></tr><tr><td></td><td>Semantic REST</td><td>Submit a semantic REST query</td></tr><tr><td></td><td>Semantic SQL</td><td>Submit a semantic SQL query</td></tr><tr><td></td><td>Semantic Metrics</td><td>Run named metric queries with or without filters</td></tr><tr><td></td><td>Data Model Query</td><td>Submit a raw SQL query directly against the data model</td></tr><tr><td></td><td>Usage Metrics</td><td>Retrieve query usage analytics</td></tr><tr><td><strong>GraphQL</strong></td><td>Semantic GraphQL</td><td>Execute a semantic GraphQL query</td></tr><tr><td><strong>Perspectives</strong></td><td>—</td><td>Create, list, fetch, update, delete saved query views; check slug availability; retrieve perspective results</td></tr><tr><td><strong>Engagement</strong></td><td>Followers</td><td>Follow/unfollow a data product; list followers; get follow status and adoption analytics</td></tr><tr><td></td><td>Notifications</td><td>Chronological event feed for the data product</td></tr><tr><td><strong>Quality &#x26; Activity</strong></td><td>Data Quality</td><td>Quality summary, rule catalog, and per-rule detail</td></tr><tr><td></td><td>Plans</td><td>Deployment plans and git diffs</td></tr><tr><td></td><td>Runs</td><td>Execution run history, model runs, and latest model state</td></tr><tr><td></td><td>Health</td><td>Liveness probe, readiness probe, and Prometheus metrics</td></tr></tbody></table>

## Running your first request

1. Expand **Quality & Activity → Health** 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](/concepts/foundations/activation/apis/getting-started/sdks.md) or raw HTTP calls.

## Related pages

* [Authentication](/concepts/foundations/activation/apis/getting-started/authentication.md) — base URL construction and token usage
* [Error Codes](/concepts/foundations/activation/apis/getting-started/error-codes.md) — HTTP status codes returned by all endpoints
* [SDKs](/concepts/foundations/activation/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/concepts/foundations/activation/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.