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

# OpenAPI, Swagger & Postman

Single-source OpenAPI 3.1 contract, Swagger UI routes, generated Postman collection, Postman CLI installation and repository/CI synchronization rules.

SONIC uses **one machine-readable API contract** to drive Swagger, Postman, SDK/client generation, validation and GitBook API documentation.

## Canonical flow

```
OpenAPI 3.1 source
→ schema / operation validation
→ Swagger UI
→ generated Postman collection
→ SDK / API clients
→ contract tests
→ GitBook reference
```

Do not hand-maintain conflicting endpoint definitions in Swagger, Postman and docs.

## Runtime tooling routes

| Route                               | Purpose                                 | Auth                        |
| ----------------------------------- | --------------------------------------- | --------------------------- |
| `GET /api/swagger/`                 | Interactive Swagger UI                  | Public or environment-gated |
| `GET /api/swagger/openapi.json`     | Machine-readable OpenAPI 3.1 projection | Public sanitized spec       |
| `GET /api/postman/`                 | Postman import/instructions landing     | Public                      |
| `GET /api/postman/collection.json`  | Generated Postman Collection            | Public sanitized artifact   |
| `GET /api/postman/environment.json` | Environment template with no secrets    | Public sanitized artifact   |

The actual business routes remain under `/api/v1`.

## Repository ownership

Recommended source layout:

```
api/
├─ swagger/
│  ├─ sonic.yaml                 # canonical OpenAPI source
│  └─ generated/
│     └─ openapi.json
└─ postman/
   ├─ SONIC API.postman_collection.json
   ├─ SONIC Local.postman_environment.json
   └─ README.md

scripts/
└─ postman/
   ├─ generate.mjs
   └─ check-sync.mjs
```

If the monorepo already owns equivalent canonical paths, keep those paths and apply the same single-source rule rather than duplicating artifacts.

## Install Postman CLI

Postman documents npm installation as:

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

The desktop Postman application is optional for local exploration. CI only needs the CLI when cloud/native-Git synchronization or Postman collection execution is part of the pipeline.

## Collection generation

The repository-generated collection must be derived from the OpenAPI source. A developer may also import the OpenAPI URL directly into Postman.

```
/api/swagger/openapi.json
        ↓
Postman Spec / generated Collection
        ↓
collection sync check
```

Postman supports generating a Collection from OpenAPI and keeping generated collections synchronized with supported OpenAPI specifications. See [Postman: Generate collections from an API specification](https://learning.postman.com/docs/design-apis/specifications/generate-collections/).

## Cloud / Native Git sync

When a SONIC Postman workspace is configured, CI may authenticate with a **secret-managed** `POSTMAN_API_KEY` and publish prepared workspace changes:

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

Never commit `POSTMAN_API_KEY`, user tokens, session cookies, provider keys, RPC credentials or production wallet secrets to a Collection/environment.

If Postman cloud/native-Git sync is not configured, the repository-generated Collection remains the canonical portable artifact. GitBook publication must not falsely claim cloud synchronization.

## Sync gate

A public API change is complete only when:

```
runtime implementation
+ OpenAPI operation/schema
+ generated Postman artifact
+ SDK/client generation
+ contract tests
+ GitBook reference
= synchronized v1 API change
```

CI should fail if re-running the generator changes committed Postman artifacts unexpectedly.

## Token-sale contract projection

Token-sale planning/status fields must preserve policy versus deployment state:

```yaml
stage: PRE_SALE
targetWindow: "Q4 2026"
provider: null
providerCandidates: [PinkSale, Smithii]
allocationMinAtomic: "3000000000000000000"
allocationMaxAtomic: "5000000000000000000"
presalePriceUsd: "0.000002"
initialDexReferenceUsd: "0.0000025"
productionMint: null
status: PLANNED
```

`allocationMinAtomic` and `allocationMaxAtomic` use SONIC's 9-decimal atomic scale. These values describe a planning envelope and must not be interpreted as funded/claimable inventory until the source allocations and custody are approved and verified.

## Security rule

Only sanitized public examples are generated into Swagger/Postman. Example bearer tokens, API keys, wallet signatures and secrets must use obvious placeholders and must never resolve to real credentials.


---

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