I got our API into the Postman network in one evening — and didn't hand-write a single request

About a quarter of our users access the API with a key. The main barrier isn't code, it's the first half hour: open the docs, figure out which endpoints you need, put together the first request, find where the key goes. The Postman network skips most of that. You get ready-made collections you can fork into your workspace and run with your own key. We're in there now, next to Notion, Stripe, and Twilio — and getting listed took one evening. Here's how I did it, and why I decided not to build the collection by hand.

First, a pleasant surprise. Getting listed anywhere usually means sitting in someone's review queue — Chrome, Edge, and LinkedIn have all made us wait. Postman doesn't work that way: it's self-serve, publishing is free, and there's no application or moderation. So the whole thing really did fit into an evening.

You can build a collection for the network by hand: create the requests, type in the paths, fields, and headers. Plenty of people do. The problem is that a hand-built collection is a snapshot of your API on the day you made it. Add an endpoint or rename a field a month later, and now the collection is out of date.

So I didn't write ours. I imported our OpenAPI spec. Ours is public and has 29 paths:

https://docs.publora.com/openapi.json

The import is one call to the Postman API:

curl --location 'https://api.getpostman.com/import/openapi' \
  --header 'X-Api-Key: PMAK-YOUR-KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "json",
    "options": { "folderStrategy": "Path" },
    "input": <contents of openapi.json>
  }'

That means the paths, fields, and types come straight from the spec and match the actual API. When the API changes, you can regenerate the collection from the latest spec instead of manually syncing everything again.

There's one thing to watch for. Notice folderStrategy: "Path" — Postman organizes the imported requests by URL path. That's technically correct, but not particularly nice to browse: you end up with a wall of paths instead of useful groups. So importing was only half the job. I reorganized the collection through PUT /collections/{uid} into something a person can actually navigate:

Connections   3   connected accounts, platform limits, connection test
Posts         6   create, schedule, get, update, delete, logs
Media         5   three-step file upload, Reels cover, YouTube thumbnail
LinkedIn      9   analytics, followers, comments, reactions, repost
Webhooks      5   notifications instead of polling
Workspace     6   managing client accounts

A note about keys, since this is a public catalog rather than my private workspace. Authentication came from the spec automatically: the x-publora-key header gets its value from an apiKey variable, and that variable is empty. Anyone who forks the collection adds their own key. I checked the published version to make sure mine wasn't there. And if you're doing this yourself, don't put your Postman key (PMAK-…) in the collection either. You need it for the import call, not for the public collection.

Instead of writing a long introduction, I added a short "first post in 60 seconds" and a "where everyone trips" section. That felt more useful than repeating the docs. It covers the things we see people get wrong: copy the platformId exactly or the post can go to the wrong account; Instagram and TikTok don't accept text-only posts; leave out the publish time and you get a draft rather than a published post; comments are LinkedIn-only; and you can test the whole flow without publishing anything by using the publora-playground target.

Two things tripped me up, so they're worth mentioning.

Workspace visibility can't be changed through the API. You can do almost everything else in code, but switching the workspace from Internal to Public has to be done manually in settings — in the same place where you rename the team. Not a big deal once you know, but I spent some time looking for an API setting that doesn't exist.

And one more general lesson: trust the machine-readable spec over the overview page. Overview docs can lag behind the API. The spec is much more likely to reflect what's actually implemented. If I'm wiring up an integration against someone else's API, that's where I'd look first.

The short version: getting into the Postman network can take an evening, and the useful shortcut is not writing the collection by hand. Generate it from the spec, clean up the structure, leave the key field empty, and regenerating it after API changes becomes much easier.

If you're in Postman and want to have a look, here's our collection: Publora API on Postman.

For those publishing your own APIs: do you generate collections from the spec or still build them by hand? And how often do you find your overview docs have drifted from the actual spec?