How to Keep Your Postman Collections Up to Date Using Copilot and Git

Not long ago, Postman introduced Git version tracking for your work. This makes your life easier when tracking your changes.  

With the git tracking they also added an AI option to track your changes in the API and automatically update the requests inside Postman. Of course, this requires a paid subscription.

A workaround is to use your existing AI subscription, like Copilot, Claude, or others. Let’s see how to do it.  

Create a Git environment in Postman

First, we need to create a Git environment in Postman. Choose Create → From Git repository  and select the folder inside your code.  

This will create two folders:  

.postman

postman

This is where all your requests and keys will be stored.  

NOTE: Keep in mind that environment files will probably contain secrets. Add them to .gitignore if necessary.  

Define Postman instructions

First, define the instructions for how to create each item. You can get the complete file in:  

Let’s review the structure of the file:  

Folder description: Inside the postman folder, define what kind of information goes inside each subfolder.
For example, environments are stored as YAML files inside /environments.

Items description: Once you know where each file goes, define the steps to create them.
Using the environments example: to create one YAML file, you need a name and keys. The keys are mostly self-explanatory, but you can add details for each line if necessary.

Example:  

name: PRO
values:
  - key: base_url
    value: "https://api.example.com"
    enabled: true

Add any extra instructions: key usage, errors, etc.

Configure main instructions

One way to use it is creating either an agent or configure in the main instructions of Copilot. Any time the agent makes a change in a controller, it should make the proper changes in Postman:  

An example you can use is:

Whenever a controller is added, modified, or removed, the Postman collection must be updated to reflect that change.

Use `postman/instructions.md` as the instructions for how to read, edit, and create Postman collections, folders, requests, and environment files.

If a request requires secrets or environment-specific values, retrieve them from the `.deploy` folder and reference them through environment variables when possible.

Every request must include at least one minimal validation using Postman scripts. At minimum, add a basic response validation such as a status code check.

In essence you need to specify where to get the information on how to do it, and what do you want your agent to do, basically that means what to do and how to do it.

Other use case

With the postman instructions available you can use it anytime without creating a specific agent, in my use case, I want to be able to activate the process every once in a while.  

For that, I just add this in my request when I need it:  

Use `postman/instructions.md` as the instructions for how to read, edit, and create Postman collections, folders, requests, and environment files.
....
Here I describe what I want to do.

Conclusion

Although I'm familiar with other tools in the market, I especially like Postman, and these instructions for Copilot even though are simple they help me keep my projects up to date without wasting time on this repetitive tasks.

Above all, it has helped me create a Postman collection where I didn't have one before, or where the existing ones were very outdated

This is an easy way to create and modify your Postman collections using Copilot. If you want to explore other methods, I recommend reading about how to sync Postman collections via OpenAPI

Postman Guide

Here you have all the information of the postman git structure

Repository Structure

postman/
collections/
    <CollectionName>/
      .resources/
        definition.yaml          # Collection definition
      <FolderName>/
        .resources/
          definition.yaml        # Folder definition
        <RequestName>.request.yaml
      <RequestName>.request.yaml
environments/
    <EnvName>.environment.yaml
Component Definitions

Collection and Folder

Collections and folders have the same kind. Location: postman/collections/<CollectionName>/.resources/definition.yaml Location: postman/collections/<CollectionName>/<FolderName>/.resources/definition.yaml

$kind: collection
name: <CollectionName>
Request

Location: <RequestName>.request.yaml (inside collection or folder)

Minimum structure:

$kind: http-request
name: <RequestName>
url: "[base_url]/path"
method: GET|POST|PUT|DELETE|PATCH
Complete example:

$kind: http-request
name: Get Articles
url: "[base_url]/api/v1/articles"
method: GET
headers:
x-api-key: "[api_key]"
Content-Type: application/json
queryParams:
customerId: "[customerId]"
page: "1"
body:
type: json
content: |+
    {
      "orderNumber": "ORDER-123"
    }
scripts:
- type: afterResponse
    code: |-
      pm.test("Status code is 200", function () {
        pm.response.to.have.status(200);
      });
    language: text/javascript
order: 2000
Request Fields Reference

Required

$kind: http-request

name: Request name

url: Request URL

method: HTTP method

Optional

headers: Map or list format

queryParams: Query string parameters

body: Request body (json, formdata, raw, etc.)

auth: Authorization definition

scripts: Pre-request or post-response scripts

order: UI ordering value

Headers Formats

Map format:

headers:
x-api-key: "[api_key]"
Content-Type: application/json
List format:

headers:
- key: Accept
value: application/json
enabled: true
Body Types

JSON:

body:
type: json
content: |+
    {
      "field": "value"
    }
Form-data:

body:
type: formdata
content:
    - key: field1
      value: value1
    - key: file
      type: file
      src: ./path/to/file.txt
Environment Variables

Variables use the syntax [variable_name]. They must be defined in postman/environments/<EnvName>.environment.yaml:

Do not use in <EnvName> the word DEV.

name: PRO
values:
- key: base_url
    value: "https://api.example.com"
    enabled: true
- key: api_key
    value: "secret_key_value"
    enabled: true
- key: customerId
    value: "12345"
    enabled: true
Critical Rules

Always use [variable_name] for:

Base URLs

API keys

Environment-specific values

Reusable values

Never hardcode:

Secrets or credentials

Environment-specific URLs

Customer IDs or similar data

YAML requirements:

Valid YAML syntax

Correct indentation (2 spaces)

Proper string quoting for URLs and values

Structure requirements:

Every collection must have .resources/definition.yaml

Every folder must have .resources/definition.yaml

Request filenames must end with .request.yaml

Variable validation:

Verify all [variables] exist in environment files

Check variable names match exactly (case-sensitive)

Editing Instructions

Edit collection name: Modify name in collection's .resources/definition.yaml

Edit folder name: Modify name in folder's .resources/definition.yaml

Edit request: Modify the .request.yaml file directly

Add/remove fields: Update YAML maintaining proper structure

Change environment variables: Edit files in postman/environments/

Best Practices & Common Mistakes

All Variables Must Be Declared

Problem: Using [variableName] in URLs or parameters without declaring them in the environment file.

Checklist for New Collections

When creating or updating Postman collections:

[ ] Environments: Create environment files for ALL deployment environments

[ ] Variables: Declare ALL variables used in URLs, headers, and bodies

[ ] Consistency: Use same variable names across all requests

[ ] Tests: Add minimum status code validation to every request and model validation if posible

[ ] Model validation: Add response structure tests for GET endpoints

[ ] Authentication: Include required headers (e.g., X-Api-Key, Authorization) for all protected endpoints

[ ] Sample bodies: Provide realistic example JSON bodies for POST/PUT requests

[ ] Documentation: Add comments in complex request bodies explaining field purposes

Menu