--- name: postman-api-collection-bootstrap description: Build a new Postman collection for an API from a described surface, planning the folder layout, request naming and example responses first and creating nothing until the user approves the plan. Use when the user wants to set up a collection for a new or undocumented API, scaffold requests from an endpoint list, or turn an API description into a usable Postman collection. --- # Bootstrap an API collection 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: Existing collections for this API: Proposed collection: — Folder tree (N folders, M requests, K example responses): - — [example: yes/no] ... Open questions: Awaiting approval of this plan before any change is made. ``` Completion stage (after approved creation): ``` Created: collection "", folders, requests, responses Matches approved plan: Not created: Not verified: ``` ## 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.