Skip to content

v0.1.0

Release Date: 2026-08-10

Initial release. postman-go is a Go SDK for the Postman API, covering all 31 service areas (196 endpoints) through a single *postman.Client.

Highlights

  • Full API coverage — all 31 Postman service areas, 196 endpoints
  • Reconstructed OpenAPI spec — Postman publishes no downloadable spec, so scripts/gen-openapi builds one from Postman's official TypeScript SDK
  • Hand-written, idiomatic wrappers — plain Go types and typed errors on top of the generated client, not raw Opt* wrappers
  • Documentation site — this site, plus a Scalar-rendered API reference

Why a Reconstructed Spec

Most of grokify's Go SDKs are generated from a provider's published OpenAPI document. Postman doesn't publish one — the spec that generates its own official TypeScript SDK lives in a private bucket. To keep the SDK-generation pipeline consistent across providers (source the spec when it exists, otherwise author or derive our own), scripts/gen-openapi parses the TypeScript SDK — the next-best authoritative, machine-readable source — with ts-morph and reconstructs an OpenAPI 3.0.3 document. That spec then drives an ogen-generated internal client (internal/api/), which every hand-written service package wraps.

Services

Every service area has a dedicated package with plain Go input/result types, string-const enums, and *postman.APIError-based error handling:

client, err := postman.NewClient(postman.WithAPIKey("PMAK-..."))

// Query detected secrets.
result, err := client.SecretScanner().Query(ctx, &secretscanner.QueryInput{
    Limit:        50,
    IncludeTotal: true,
})

// List workspaces.
workspaces, err := client.Workspaces().List(ctx, nil)

See Quick Start and the Services section for every package.

Error Handling

Non-2xx responses come back as *postman.APIError, carrying the RFC 9457 problem-details fields Postman returns (status code, type, title, detail, instance) — see Error Handling.

Known Limitations

  • A handful of Postman error responses (notably many services' 403 Forbidden) are modeled as TypeScript unions the reconstructed OpenAPI spec can't resolve to a concrete schema, so only the HTTP status code is recoverable there — no title/detail body. Documented per-service where it applies.
  • *postman.APIError doesn't yet expose Postman's rate-limit response headers (RateLimit-*, Retry-After) — only the 429 status code is available today. See Rate Limiting.
  • The SDK has no built-in retry or backoff logic; every call is a single attempt.

Fixes Found During Development

  • collectionitems.CreateResponseInput/UpdateResponseInput embedded an unexported struct that silently broke composite-literal construction (&Input{Field: value}) — the one idiom used everywhere else in the SDK. Found and fixed while writing and compiling the Collection Items documentation examples against the real module.
  • Several golangci-lint false positives (gosec G101 on identifier names, dupl on sibling wrapper methods over distinct generated types) were resolved with documented nolint suppressions rather than forced abstractions — see grokify/mogo's lintfix package for the reusable patterns.

Full Changelog

See CHANGELOG.md for the complete, commit-linked list of changes.