> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/sonic-api-reference/openapi-swagger-and-postman/postman-installation-and-sync.md).

# Postman Installation & Sync

Postman CLI installation, OpenAPI import, generated Collection ownership, secret-safe environments and CI/cloud synchronization for SONIC API v1.

## Install

Official Postman CLI npm installation:

```bash
npm install -g postman-cli
postman --version
```

For local development, import the SONIC OpenAPI document from:

```
https://api.sonicai.works/api/swagger/openapi.json
```

or import the generated Collection from:

```
https://api.sonicai.works/api/postman/collection.json
```

Until those runtime routes are explicitly `Live`, use the repository artifacts rather than assuming the public URL is available.

## Environment template

A committed Postman environment may contain only non-secret defaults:

```json
{
  "baseUrl": "http://localhost:3000",
  "apiBasePath": "/api/v1",
  "apiKey": "",
  "accessToken": ""
}
```

Real values are local/CI secrets and must not be committed.

## Sync modes

### Repository-only

```
OpenAPI source
→ generate collection
→ check git diff
→ commit OpenAPI + generated collection together
```

This is the minimum supported mode.

### Postman cloud / Native Git

Where a Postman workspace is explicitly configured:

```bash
postman login --with-api-key "$POSTMAN_API_KEY"
postman workspace push -y
```

The API key belongs in the CI secret manager. The command must run only from trusted branches/workflows.

## Pull-request gate

```
1. validate OpenAPI 3.1
2. regenerate Postman collection
3. fail if generated output is stale
4. run contract tests
5. build SDK/client artifacts
6. publish/sync after merge
```

A manually edited Collection that cannot be regenerated from canonical OpenAPI is treated as drift.

## Postman source precedence

```
OpenAPI 3.1 source
> generated repository Collection
> optional Postman cloud mirror
> examples/screenshots
```

Cloud state never overrides a reviewed OpenAPI contract silently.


---

# 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://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/sonic-api-reference/openapi-swagger-and-postman/postman-installation-and-sync.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.