Bootstrap a Postman API collection with AI

The goal is a collection a teammate can open and use within minutes: logical folders, predictable names, one request per endpoint, and example responses that show the expected shape. Build the plan in conversation first. Creation is the last step, and it is the only step that changes the workspace.

This job creates new structure. It is not an audit of existing collections and not a cleanup. If the user wants to review or retire an existing collection, say so and point them to the matching job instead.

1. Confirm the target before planning

Ask, or confirm if already given:

• Which workspace the collection goes into. Call getAllCollections first to see what already exists there. If a collection for this API already exists, stop and ask whether to extend it or create a second one. Two collections for the same API drift apart quickly.
• The API surface. You need the list of endpoints (method, path, one-line purpose), the base URL pattern, and how auth works. If the user gives only a vague description ("our billing API"), ask for the endpoint list rather than inventing one. Never fabricate endpoints, paths or parameters.
• Environments. Ask whether they want environment-driven base URLs (dev, staging, production). If yes, plan the variable names now, but do not create environments in this job unless the user asks for them explicitly.

2. Draft the layout before touching anything

Group endpoints by resource or domain, not by HTTP method and not by the order they appear in the source doc. A good top level has between four and eight folders. Fewer than four means the grouping is too coarse; more than about eight means it is too fine or the API should be split into two collections.

Naming rules for the plan:

• Folders: noun phrases matching the domain the API team uses ("Invoices", "Customers", "Webhooks"). Avoid "Misc", "Other" and "Old".
• Requests: verb and object, in the same style everywhere, such as "Create invoice", "List invoices", "Get invoice by id". Pick one convention and keep it. Mixing "Get invoice" with "invoices.list" is the most common source of later clutter.
• Cross-cutting requests (health check, auth token, whoami) go in a short top-level folder, not mixed into resource folders.

Show the user the full tree as an indented list, with method and path on each request, and the count of folders and requests. Wait for approval of the tree before going further.

3. Plan the example responses

For each request the user cares about, decide whether it gets an example response. A reasonable default is one success example for every read and create endpoint, and one error example per resource (typically a 404 or a 422) rather than one per request. Each example should use realistic but clearly fake data, with ids and names that look plausible and no real customer data.

Write example bodies from the API's documented schema only. If the schema is unknown, mark the example as "shape unverified" in the plan and do not present it as a real response.

4. Get explicit approval for the plan

Present the plan as the exact sequence of changes you intend to make: collection name, folder list, request list with names and methods, and which requests get example responses. Ask the user to approve it or to change it. Do not create anything until you receive their explicit yes to this specific plan. An approval of the idea is not an approval of the list, so re-confirm if they edited it.

5. Create in order, then verify

After approval, create in this order so each object exists before its children:

1. The collection, with createCollection, using the name and description agreed in the plan.
2. Folders, with createFolder, top level first, then any nested folders.
3. Requests, with createRequest, placed in their folders as approved.
4. Example responses, with createResponse, attached to their requests.

Stop on the first failure. Report what was created so far and what was not, and ask before retrying. Never retry a create that might have succeeded without first reading the collection with getCollection to see what now exists, because a blind retry produces duplicates.

After creation, read the result back with getCollection and compare it against the approved plan: folder count, request count, names, and response attachment. Report any mismatch.

Common patterns and traps

• Duplicate collections. Bootstrapping a second collection for an API that already has one is the most frequent mistake. Check getAllCollections in step 1 every time.
• Invented endpoints. A plausible-looking path that the API does not have wastes the first person who tries it. Only create requests for endpoints the user supplied or the docs confirm.
• Naming drift. Mixing naming styles across folders looks minor and makes the collection hard to search. Enforce one style from the plan onward.
• Too many folders on day one. A tree with a folder per endpoint is hard to navigate. Group first, split later when a folder genuinely overflows.
• Fake data that looks real. Example responses with realistic emails or card numbers can leak into docs. Use obviously placeholder values such as user@example.com.
• Partial creation after an error. A failure halfway leaves a half-built collection. Read back before you assume anything.
• Behaviour I cannot see. The tool list gives names, not what each call accepts or returns beyond that. If a step depends on a detail you have not confirmed (for example the exact fields a create call requires, or whether a response can be attached to any request type), check the tool's own response or ask the user rather than assuming.

Output

Planning stage (before any create):

Target workspace: <name, and whether it was confirmed>
Existing collections for this API: <none | list, with recommendation>
Proposed collection: <name> — <one-line description>

Folder tree (N folders, M requests, K example responses):
<Folder>
  - <METHOD> <path> — <Request name>   [example: yes/no]
...

Open questions: <endpoints or auth details still needed>
Awaiting approval of this plan before any change is made.

Completion stage (after approved creation):

Created: collection "<name>", <N> folders, <M> requests, <K> responses
Matches approved plan: <yes / no, with differences>
Not created: <anything skipped or failed, and why>
Not verified: <example bodies marked "shape unverified", or other gaps>

Rules

• Do not create, update or delete anything without the user's explicit yes to the specific plan in this conversation; wait for the user's explicit yes before each write batch if the plan changes.
• Never create a collection for an API that already has one in the same workspace without the user's explicit yes to the second copy.
• Do not invent endpoints, paths, parameters or response schemas; never present an unverified example as real.
• Do not use real customer, personal or credential data in example responses; use placeholder values.
• Do not retry a failed create blindly; read the collection back first to avoid duplicates.
• Do not switch the active workspace without the user's explicit yes, since it changes where later writes land.

Done when

• The approved plan and the created collection match, verified by reading the collection back.
• Every request created came from an approved plan item, and every example is either grounded in the schema or marked unverified.
• The output lists anything not created, and anything not verified, honestly.