postman

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 10, 2026 License: MIT Imports: 38 Imported by: 0

README

Postman-Go API Client SDK

Go CI Go Lint Go SAST Docs Docs Visualization License

A Go SDK for the Postman API.

This SDK follows the standard grokify SDK pipeline: an OpenAPI 3.0 specification drives an internal client generated with ogen, with hand-written, domain-oriented wrapper packages on top. Postman does not publish a downloadable OpenAPI document, so the spec in openapi/openapi.yaml is reconstructed and maintained in-repo by scripts/gen-openapi, which parses Postman's official TypeScript SDK (the authoritative machine-readable source, in the absence of a published spec) and the public API reference.

Status

All 31 Postman API service areas (196 endpoints) have a hand-written Go wrapper package with plain Go types, typed errors, and unit tests.

Service Package Endpoints
Analytics analytics 2
API Security apisecurity 1
Audit Logs auditlogs 2
Billing billing 2
Collection Access Keys collectionaccesskeys 2
Collection Folders (comments) collectionfolders 4
Collection Items collectionitems 12
Collection Requests (comments) collectionrequests 4
Collection Responses (comments) collectionresponses 4
Collections collections 31
Comments comments 1
Components (API Spec Hub) components 9
Environments environments 10
Groups groups 2
Import imports 1
Mocks mocks 13
Monitors monitors 8
OAuth 2.0 oauth2 2
Postbot postbot 1
Private API Network privateapinetwork 6
Pull Requests pullrequests 3
SDK Generation sdkgen 10
Search search 1
Secret Scanner secretscanner 4
Service Accounts serviceaccounts 1
Specs (API Spec Hub) specs 22
Tags tags 5
Teams teams 10
Users users 3
Webhooks webhooks 1
Workspaces workspaces 19

Each service is reachable from a single *postman.Client — see Usage.

Documentation

The full guide site — installation, authentication, error handling, rate limiting, and a usage page per service — is published at grokify.github.io/postman-go, built with MkDocs + Material from docs/ and mkdocs.yml. Preview it locally:

pip install mkdocs-material
mkdocs serve   # http://127.0.0.1:8000

For the raw, endpoint-level API reference (not Go-specific usage), see API Reference below. For GoDoc, see the badge at the top of this file.

API Reference

docs/api-reference.html renders openapi/openapi.yaml as a browsable API reference with Scalar. It's a static page with no build step — open it directly:

open docs/api-reference.html   # macOS; xdg-open on Linux

The page fetches the spec from main on GitHub, so it works whether you open it locally, host it via GitHub Pages, or serve it from any static file server. To preview local edits to openapi/openapi.yaml before pushing, run a local server from the repo root (python3 -m http.server) and point the page's url config at ../openapi/openapi.yaml instead.

Installation

go get github.com/grokify/postman-go

Authentication

All requests authenticate with a Postman API key sent in the X-API-Key header. Provide it via WithAPIKey or the POSTMAN_API_KEY environment variable.

Note: Some services (e.g. Secret Scanner, Private API Network) require a Postman Enterprise plan with the relevant add-on enabled.

Usage

package main

import (
	"context"
	"fmt"
	"log"

	postman "github.com/grokify/postman-go"
	"github.com/grokify/postman-go/secretscanner"
)

func main() {
	client, err := postman.NewClient(postman.WithAPIKey("PMAK-..."))
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()

	// List supported secret types.
	types, err := client.SecretScanner().SecretTypes(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%d secret types supported\n", types.Total)

	// Query detected secrets.
	result, err := client.SecretScanner().Query(ctx, &secretscanner.QueryInput{
		Limit:        50,
		IncludeTotal: true,
	})
	if err != nil {
		log.Fatal(err)
	}
	for _, s := range result.Secrets {
		fmt.Printf("%s in %s: %s\n", s.SecretType, s.WorkspaceID, s.Resolution)
	}

	// Mark a secret as a false positive.
	_, err = client.SecretScanner().UpdateResolution(ctx, "SECRET_ID",
		&secretscanner.UpdateResolutionInput{
			Resolution:  secretscanner.ResolutionFalsePositive,
			WorkspaceID: "WORKSPACE_ID",
		})
	if err != nil {
		log.Fatal(err)
	}

	// Every other service follows the same shape, e.g.:
	workspaces, err := client.Workspaces().List(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	_ = workspaces
}

See examples/ for runnable programs.

Error handling

Non-2xx responses are returned as *postman.APIError (an alias for postmanerr.APIError), carrying the RFC 9457 problem-details fields Postman returns:

result, err := client.SecretScanner().Query(ctx, nil)
if err != nil {
	var apiErr *postman.APIError
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.StatusCode, apiErr.Title, apiErr.Detail)
	}
}

Some Postman error responses are typed unions the source TypeScript SDK cannot resolve to a concrete shape; in those cases only the HTTP status code is recoverable (no title/detail body). This is documented per-method where it applies — see scripts/gen-openapi/README.md's "Known approximations".

Regenerating the SDK

The OpenAPI spec is reconstructed from the Postman TypeScript SDK, and the internal client is generated from that spec:

# 1. Regenerate openapi/openapi.yaml from the TS SDK
node scripts/gen-openapi/index.mjs

# 2. Regenerate internal/api/ from openapi/openapi.yaml
./generate.sh

See scripts/gen-openapi/README.md for how the reconstruction works and its documented approximations. The hand-written service packages (secretscanner/, collections/, etc.) are not generated and may need updates if the spec's operation IDs or schemas change.

Layout

postman-go/
├── client.go              # top-level Client, options, auth, service accessors
├── openapi/openapi.yaml   # reconstructed OpenAPI 3.0 spec (source of truth)
├── scripts/gen-openapi/   # TS SDK -> OpenAPI spec generator
├── internal/api/          # ogen-generated client (do not edit)
├── postmanerr/            # shared error types (leaf package)
├── secretscanner/         # one wrapper package per Postman service area
├── collections/
├── workspaces/
├── ...
├── mkdocs.yml             # guide site config (see Documentation above)
├── docs/
│   ├── index.md, getting-started/, guides/  # guide site source
│   ├── services/*.md      # one usage page per service, mirrors nav below
│   └── api-reference.html # Scalar-rendered API reference (see openapi.yaml)
└── examples/              # runnable examples

License

MIT

Documentation

Overview

Package postman provides a Go client for the Postman API.

It wraps an internal ogen-generated API client with a higher-level, hand- written surface that handles authentication and exposes convenient, domain-oriented services covering the Postman API.

Example: 

client, err := postman.NewClient(postman.WithAPIKey("PMAK-..."))
if err != nil {
    log.Fatal(err)
}
types, err := client.SecretScanner().SecretTypes(ctx)

Index

Constants

View Source 
const (
	// DefaultBaseURL is the default (US region) Postman API base URL.
	DefaultBaseURL = "https://api.postman.com"
	// EUBaseURL is the EU region Postman API base URL.
	EUBaseURL = "https://api.eu.postman.com"

	// EnvAPIKey is the environment variable read for the API key when one is not
	// supplied via WithAPIKey.
	EnvAPIKey = "POSTMAN_API_KEY" //nolint:gosec // G101: This is an environment variable name, not a credential
)
View Source 
const Version = "0.1.0"

Version is the SDK version.

Variables

View Source 
var ErrNoAPIKey = errors.New("postman: API key is required")

ErrNoAPIKey is returned by NewClient when no API key is configured.

Functions

This section is empty.

Types

type APIError 

type APIError = postmanerr.APIError

APIError is an error returned by the Postman API. It is an alias for postmanerr.APIError so callers can type-assert against a single type regardless of which service produced the error.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the top-level Postman API client.

func NewClient 

func NewClient(opts ...Option) (*Client, error)

NewClient creates a new Postman client. The API key may be supplied via WithAPIKey or the POSTMAN_API_KEY environment variable.

func (*Client) API 

func (c *Client) API() *api.Client

API returns the underlying ogen-generated client for advanced use cases not covered by the high-level services.

func (*Client) APISecurity 

func (c *Client) APISecurity() *apisecurity.Service

APISecurity returns the API Security validation service.

func (*Client) Analytics 

func (c *Client) Analytics() *analytics.Service

Analytics returns the Analytics service.

func (*Client) AuditLogs 

func (c *Client) AuditLogs() *auditlogs.Service

AuditLogs returns the Audit Logs service.

func (*Client) BaseURL 

func (c *Client) BaseURL() string

BaseURL returns the base URL the client is configured to use.

func (*Client) Billing 

func (c *Client) Billing() *billing.Service

Billing returns the Billing service.

func (*Client) CollectionAccessKeys 

func (c *Client) CollectionAccessKeys() *collectionaccesskeys.Service

CollectionAccessKeys returns the Collection Access Keys service.

func (*Client) CollectionFolders 

func (c *Client) CollectionFolders() *collectionfolders.Service

CollectionFolders returns the Collection Folders comments service.

func (*Client) CollectionItems 

func (c *Client) CollectionItems() *collectionitems.Service

CollectionItems returns the Collection Items (folders/requests/responses) service.

func (*Client) CollectionRequests 

func (c *Client) CollectionRequests() *collectionrequests.Service

CollectionRequests returns the Collection Requests comments service.

func (*Client) CollectionResponses 

func (c *Client) CollectionResponses() *collectionresponses.Service

CollectionResponses returns the Collection Responses comments service.

func (*Client) Collections 

func (c *Client) Collections() *collections.Service

Collections returns the Collections service.

func (*Client) Comments 

func (c *Client) Comments() *comments.Service

Comments returns the Comments service.

func (*Client) Components 

func (c *Client) Components() *components.Service

Components returns the API Spec Hub Components service.

func (*Client) Environments 

func (c *Client) Environments() *environments.Service

Environments returns the Environments service.

func (*Client) Groups 

func (c *Client) Groups() *groups.Service

Groups returns the Groups service.

func (*Client) Imports 

func (c *Client) Imports() *imports.Service

Imports returns the Import (OpenAPI definition import) service.

func (*Client) Mocks 

func (c *Client) Mocks() *mocks.Service

Mocks returns the Mock Servers service.

func (*Client) Monitors 

func (c *Client) Monitors() *monitors.Service

Monitors returns the Monitors service.

func (*Client) OAuth2 

func (c *Client) OAuth2() *oauth2.Service

OAuth2 returns the OAuth 2.0 token service.

func (*Client) Postbot 

func (c *Client) Postbot() *postbot.Service

Postbot returns the Postbot AI test-generation service.

func (*Client) PrivateAPINetwork 

func (c *Client) PrivateAPINetwork() *privateapinetwork.Service

PrivateAPINetwork returns the Private API Network service.

func (*Client) PullRequests 

func (c *Client) PullRequests() *pullrequests.Service

PullRequests returns the Pull Requests service.

func (*Client) SDKGen 

func (c *Client) SDKGen() *sdkgen.Service

SDKGen returns the SDK Generation service.

func (*Client) Search 

func (c *Client) Search() *search.Service

Search returns the Search service.

func (*Client) SecretScanner 

func (c *Client) SecretScanner() *secretscanner.Service

SecretScanner returns the Secret Scanner service.

func (*Client) ServiceAccounts 

func (c *Client) ServiceAccounts() *serviceaccounts.Service

ServiceAccounts returns the Service Accounts service.

func (*Client) Specs 

func (c *Client) Specs() *specs.Service

Specs returns the API Spec Hub service.

func (*Client) Tags 

func (c *Client) Tags() *tags.Service

Tags returns the Tags service.

func (*Client) Teams 

func (c *Client) Teams() *teams.Service

Teams returns the Teams service.

func (*Client) Users 

func (c *Client) Users() *users.Service

Users returns the Users service.

func (*Client) Webhooks 

func (c *Client) Webhooks() *webhooks.Service

Webhooks returns the Webhooks service.

func (*Client) Workspaces 

func (c *Client) Workspaces() *workspaces.Service

Workspaces returns the Workspaces service.

type Option 

type Option func(*clientOptions)

Option configures a Client.

func WithAPIKey 

func WithAPIKey(apiKey string) Option

WithAPIKey sets the Postman API key used for authentication.

func WithBaseURL 

func WithBaseURL(baseURL string) Option

WithBaseURL sets a custom API base URL (e.g. EUBaseURL).

func WithHTTPClient 

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets a custom HTTP client.

func WithTimeout 

func WithTimeout(timeout time.Duration) Option

WithTimeout sets the request timeout used when no custom HTTP client is set.

Source Files

View all Source files

Directories

Path Synopsis
Package analytics provides a high-level client for Postman's Analytics API.
 Package analytics provides a high-level client for Postman's Analytics API.
Package apisecurity provides a high-level client for Postman's API Security service.
 Package apisecurity provides a high-level client for Postman's API Security service.
Package auditlogs provides a high-level client for Postman's Audit Logs API.
 Package auditlogs provides a high-level client for Postman's Audit Logs API.
Package billing provides a high-level client for Postman's Billing API.
 Package billing provides a high-level client for Postman's Billing API.
Package collectionaccesskeys provides a high-level client for Postman's Collection Access Keys API.
 Package collectionaccesskeys provides a high-level client for Postman's Collection Access Keys API.
Package collectionfolders provides a high-level client for managing comments on folders within a Postman collection.
 Package collectionfolders provides a high-level client for managing comments on folders within a Postman collection.
Package collectionitems provides a high-level client for managing the individual items (folders, requests, and responses) nested inside a Postman collection.
 Package collectionitems provides a high-level client for managing the individual items (folders, requests, and responses) nested inside a Postman collection.
Package collectionrequests provides a high-level client for managing comments on requests within a Postman collection.
 Package collectionrequests provides a high-level client for managing comments on requests within a Postman collection.
Package collectionresponses provides a high-level client for managing comments on saved responses (examples) within a Postman collection.
 Package collectionresponses provides a high-level client for managing comments on saved responses (examples) within a Postman collection.
Package collections provides a high-level client for Postman's Collections API.
 Package collections provides a high-level client for Postman's Collections API.
Package comments provides a high-level client for Postman's Comments API.
 Package comments provides a high-level client for Postman's Comments API.
Package components provides a high-level client for Postman's API Spec Hub Components API.
 Package components provides a high-level client for Postman's API Spec Hub Components API.
Package environments provides a high-level client for Postman's Environments API.
 Package environments provides a high-level client for Postman's Environments API.
examples
secretscanner command
Command secretscanner demonstrates the Postman Secret Scanner SDK.
 Command secretscanner demonstrates the Postman Secret Scanner SDK.
Package groups provides a high-level client for Postman's Groups API.
 Package groups provides a high-level client for Postman's Groups API.
Package imports provides a high-level client for Postman's Import API.
 Package imports provides a high-level client for Postman's Import API.
internal
api
Code generated by ogen, DO NOT EDIT.
 Code generated by ogen, DO NOT EDIT.
Package mocks provides a high-level client for Postman's Mock Server API.
 Package mocks provides a high-level client for Postman's Mock Server API.
Package monitors provides a high-level client for Postman's Monitors API.
 Package monitors provides a high-level client for Postman's Monitors API.
Package oauth2 provides a high-level client for Postman's OAuth 2.0 API.
 Package oauth2 provides a high-level client for Postman's OAuth 2.0 API.
Package postbot provides a high-level client for Postman's Postbot API.
 Package postbot provides a high-level client for Postman's Postbot API.
Package postmanerr defines error types shared across the postman-go SDK service packages.
 Package postmanerr defines error types shared across the postman-go SDK service packages.
Package privateapinetwork provides a high-level client for Postman's Private API Network API.
 Package privateapinetwork provides a high-level client for Postman's Private API Network API.
Package pullrequests provides a high-level client for Postman's Pull Requests API.
 Package pullrequests provides a high-level client for Postman's Pull Requests API.
Package sdkgen provides a high-level client for Postman's SDK Generation API.
 Package sdkgen provides a high-level client for Postman's SDK Generation API.
Package search provides a high-level client for Postman's Search API.
 Package search provides a high-level client for Postman's Search API.
Package secretscanner provides a high-level client for Postman's Secret Scanner API.
 Package secretscanner provides a high-level client for Postman's Secret Scanner API.
Package serviceaccounts provides a high-level client for Postman's Service Accounts API.
 Package serviceaccounts provides a high-level client for Postman's Service Accounts API.
Package specs provides a high-level client for Postman's API Spec Hub.
 Package specs provides a high-level client for Postman's API Spec Hub.
Package tags provides a high-level client for Postman's Tags API.
 Package tags provides a high-level client for Postman's Tags API.
Package teams provides a high-level client for Postman's Teams API.
 Package teams provides a high-level client for Postman's Teams API.
Package users provides a high-level client for retrieving information about the authenticated user and users on a Postman team.
 Package users provides a high-level client for retrieving information about the authenticated user and users on a Postman team.
Package webhooks provides a high-level client for Postman's Webhooks API.
 Package webhooks provides a high-level client for Postman's Webhooks API.
Package workspaces provides a high-level client for Postman's Workspaces API.
 Package workspaces provides a high-level client for Postman's Workspaces API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.