Postman Environments API
The Environments API enables programmatic management of Postman environments and global variables, including secret variables stored in the Postman Vault, so you can scope work to dev/staging/prod environments.
The Environments API enables programmatic management of Postman environments and global variables, including secret variables stored in the Postman Vault, so you can scope work to dev/staging/prod environments.
openapi: 3.1.0
info:
title: Postman Environments API
version: 1.0.0
description: 'Operations tagged environments across 2 of this provider''s published API definitions: postman-api-openapi.yml, postman-environments-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
tags:
- name: environments
paths:
/environments:
get:
operationId: getEnvironments
summary: Get all environments
description: Gets information about all of your [environments](https://learning.postman.com/docs/sending-requests/managing-environments/).
tags:
- environments
parameters:
- name: workspace
in: query
description: The workspace's ID.
required: false
schema:
$ref: '#/components/schemas/workspaceId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/getEnvironments'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/GetEnvironmentsRequestUnauthorizedError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/GetEnvironmentsRequestNotFoundError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetEnvironmentsRequestInternalServerError'
post:
operationId: createEnvironment
summary: Create an environment
description: 'Creates an environment.
**Note:**
- The request body size cannot exceed the maximum allowed size of 30MB.
- If you receive an HTTP `411 Length Required` error response, manually pass the `Content-Length` header and its value in the request header.
- If you do not include the `workspace` query parameter, the system creates the environment in the oldest personal Internal workspace you own.
- Only [shared variable](https://learning.postman.com/docs/use/send-requests/variables/variables/#share-variable-values) values can be modified through the Postman API. A shared variable is an environment variable with its value synced and stored in the Postman cloud, and can be accessed by your teammates in the environment''s workspace.
'
tags:
- environments
parameters:
- name: workspace
in: query
description: The workspace's ID.
required: true
schema:
$ref: '#/components/schemas/workspaceId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/createEnvironmentResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEnvironmentRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEnvironmentRequestUnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEnvironmentRequestForbiddenError'
'411':
description: Length Required
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'413':
description: Payload Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEnvironmentRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createEnvironment'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/environments/{environmentId}:
get:
operationId: getEnvironment
summary: Get an environment
description: Gets information about an environment.
tags:
- environments
parameters:
- name: environmentId
in: path
description: The environment's ID.
required: true
schema:
$ref: '#/components/schemas/environmentId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/getEnvironment'
'400':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/GetEnvironmentRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/GetEnvironmentRequestUnauthorizedError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetEnvironmentRequestInternalServerError'
put:
operationId: putEnvironment
summary: Replace an environment's data
description: 'Replaces all the contents of an environment with the given information.
**Note:**
- The request body size cannot exceed the maximum allowed size of 30MB.
- If you receive an HTTP `411 Length Required` error response, manually pass the `Content-Length` header and its value in the request header.
- Only [shared variable](https://learning.postman.com/docs/use/send-requests/variables/variables/#share-variable-values) values can be modified through the Postman API. A shared variable is an environment variable with its value synced and stored in the Postman cloud, and can be accessed by your teammates in the environment''s workspace.
'
tags:
- environments
parameters:
- name: environmentId
in: path
description: The environment's ID.
required: true
schema:
$ref: '#/components/schemas/environmentId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/putEnvironmentResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/PutEnvironmentRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/PutEnvironmentRequestUnauthorizedError'
'411':
description: Length Required
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'413':
description: Payload Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/PutEnvironmentRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/putEnvironment'
delete:
operationId: deleteEnvironment
summary: Delete an environment
description: Deletes an environment.
tags:
- environments
parameters:
- name: environmentId
in: path
description: The environment's ID.
required: true
schema:
$ref: '#/components/schemas/environmentId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/deleteEnvironment'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteEnvironmentRequestUnauthorizedError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteEnvironmentRequestNotFoundError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteEnvironmentRequestInternalServerError'
patch:
operationId: patchEnvironment
summary: Update an environment
description: 'Updates specific environment properties, such as its name and variables.
**Note:**
- You can only perform one type of operation at a time. For example, you cannot perform an `add` and `replace` operation in the same call.
- The request body size cannot exceed the maximum allowed size of 30MB.
- If you receive an HTTP `411 Length Required` error response, manually pass the `Content-Length` header and its value in the request header.
- To add a description to an existing variable, use the `add` operation.
- Only [shared variable](https://learning.postman.com/docs/use/send-requests/variables/variables/#share-variable-values) values can be modified through the Postman API. A shared variable is an environment variable with its value synced and stored in the Postman cloud, and can be accessed by your teammates in the environment''s workspace.
'
tags:
- environments
parameters:
- name: environmentId
in: path
description: The environment's ID.
required: true
schema:
$ref: '#/components/schemas/environmentId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/patchEnvironmentResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/patchEnvironment400Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/PatchEnvironmentRequestNotFoundError'
'411':
description: Length Required
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'413':
description: Payload Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/PatchEnvironmentRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Environments_patchEnvironment_Request'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/environments/{environmentId}/forks:
get:
operationId: getEnvironmentForks
summary: Get an environment's forks
description: Gets all of an environment's forked environments.
tags:
- environments
parameters:
- name: environmentId
in: path
description: The environment's unique ID.
required: true
schema:
$ref: '#/components/schemas/environmentUid'
- name: cursor
in: query
description: The pointer to the first record of the set of paginated results. To view the next response, use the `nextCursor` value for this parameter.
required: false
schema:
$ref: '#/components/schemas/cursor'
- name: direction
in: query
description: Sort results in ascending (`asc`) or descending (`desc`) order.
required: false
schema:
$ref: '#/components/schemas/ascDesc'
- name: limit
in: query
description: The maximum number of rows to return in the response.
required: false
schema:
$ref: '#/components/schemas/limit'
default: 10
- name: sort
in: query
description: Sort the results by the date and time of creation.
required: false
schema:
$ref: '#/components/schemas/sortByCreatedAt'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/getEnvironmentForks'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetail'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/GetEnvironmentForksRequestUnauthorizedError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetEnvironmentForksRequestInternalServerError'
post:
operationId: forkEnvironment
summary: Create a fork
description: Creates a [fork](https://learning.postman.com/docs/collaborating-in-postman/using-version-control/forking-elements/) of an existing environment.
tags:
- environments
parameters:
- name: environmentId
in: path
description: The environment's unique ID.
required: true
schema:
$ref: '#/components/schemas/environmentUid'
- name: workspaceId
in: query
description: The workspace's ID.
required: true
schema:
$ref: '#/components/schemas/workspaceId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/forkEnvironmentResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ForkEnvironmentRequestUnauthorizedError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ForkEnvironmentRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/forkEnvironment'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/environments/{environmentId}/merges:
post:
operationId: mergeEnvironmentFork
summary: Merge a fork
description: '[Merges](https://learning.postman.com/docs/collaborating-in-postman/using-version-control/forking-elements/#merge-changes-from-a-fork) a forked environment back into its parent environment.
'
tags:
- environments
parameters:
- name: environmentId
in: path
description: The environment's unique ID.
required: true
schema:
$ref: '#/components/schemas/environmentUid'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/mergeEnvironmentForkResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetail'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/MergeEnvironmentForkRequestUnauthorizedError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/MergeEnvironmentForkRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/mergeEnvironmentFork'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/environments/{environmentUid}/pulls:
post:
operationId: pullEnvironment
summary: Pull source changes
description: '[Pulls](https://learning.postman.com/docs/collaborating-in-postman/using-version-control/forking-elements/#pull-updates-from-a-parent-element) the changes from a parent (source) environment into the forked environment.
'
tags:
- environments
parameters:
- name: environmentUid
in: path
description: The destination environment's unique ID.
required: true
schema:
$ref: '#/components/schemas/environmentUid'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/pullEnvironmentResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetail'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/PullEnvironmentRequestUnauthorizedError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/PullEnvironmentRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/pullEnvironment'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
components:
schemas:
GetEnvironmentsRequestInternalServerError:
oneOf:
- $ref: '#/components/schemas/commonErrorTypeTitleDetail'
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
- $ref: '#/components/schemas/commonErrorNameMessage'
title: GetEnvironmentsRequestInternalServerError
patchEnvironmentReplace:
type: array
items:
$ref: '#/components/schemas/PatchEnvironmentReplaceItems'
title: patchEnvironmentReplace
commonErrorNameMessageDetails:
type: object
properties:
error:
$ref: '#/components/schemas/CommonErrorNameMessageDetailsError'
title: commonErrorNameMessageDetails
CommonErrorTypeTitleDetailStatusType:
oneOf:
- type: string
format: uri-reference
- type: string
title: CommonErrorTypeTitleDetailStatusType
GetEnvironmentRequestBadRequestError:
oneOf:
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
- $ref: '#/components/schemas/commonErrorNameMessage'
title: GetEnvironmentRequestBadRequestError
PullEnvironmentResponseEnvironment:
type: object
properties:
uid:
type: string
format: uid
description: The merged environment's unique ID.
description: Information about the merged environment.
title: PullEnvironmentResponseEnvironment
CreateEnvironmentResponseEnvironment:
type: object
properties:
id:
type: string
description: The environment's ID.
name:
type: string
description: The environment's name.
uid:
type: string
format: uid
description: The environment's unique ID.
description: Information about the environment.
title: CreateEnvironmentResponseEnvironment
commonErrorTypeTitleDetail:
type: object
properties:
type:
type: string
description: The type of error.
title:
type: string
description: A short summary of the problem.
detail:
$ref: '#/components/schemas/CommonErrorTypeTitleDetailDetail'
description: Information about the error.
title: commonErrorTypeTitleDetail
patchEnvironmentAdd:
type: array
items:
$ref: '#/components/schemas/PatchEnvironmentAddItems'
title: patchEnvironmentAdd
environmentVariableSource:
type: object
properties:
postman:
$ref: '#/components/schemas/EnvironmentVariableSourcePostman'
description: Information about the Postman-specific source of the variable's value.
provider:
$ref: '#/components/schemas/EnvironmentVariableSourceProvider'
description: The secret's provider.
description: Information about the source of the variable's value.
title: environmentVariableSource
PullEnvironmentRequestUnauthorizedError:
oneOf:
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
- $ref: '#/components/schemas/commonErrorNameMessage'
title: PullEnvironmentRequestUnauthorizedError
GetEnvironmentForksRequestInternalServerError:
oneOf:
- $ref: '#/components/schemas/commonErrorTypeTitleDetail'
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
- $ref: '#/components/schemas/commonErrorNameMessage'
title: GetEnvironmentForksRequestInternalServerError
GetEnvironmentsRequestUnauthorizedError:
oneOf:
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
- $ref: '#/components/schemas/commonErrorNameMessage'
title: GetEnvironmentsRequestUnauthorizedError
limit:
type: integer
default: 10
title: limit
PutEnvironmentRequestUnauthorizedError:
oneOf:
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
- $ref: '#/components/schemas/commonErrorNameMessage'
title: PutEnvironmentRequestUnauthorizedError
GetEnvironmentRequestUnauthorizedError:
oneOf:
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
- $ref: '#/components/schemas/commonErrorNameMessage'
title: GetEnvironmentRequestUnauthorizedError
PatchEnvironmentRequestInternalServerError:
oneOf:
- $ref: '#/components/schemas/commonErrorTypeTitleDetail'
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
- $ref: '#/components/schemas/commonErrorNameMessage'
title: PatchEnvironmentRequestInternalServerError
GetEnvironmentForksRequestUnauthorizedError:
oneOf:
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
- $ref: '#/components/schemas/commonErrorNameMessage'
title: GetEnvironmentForksRequestUnauthorizedError
patchEnvironmentName:
type: array
items:
$ref: '#/components/schemas/PatchEnvironmentNameItems'
title: patchEnvironmentName
EnvironmentVariablesType:
type: string
enum:
- secret
- default
description: 'The variable''s type:
- `secret` — The variable value is masked.
- `default` — The variable value is visible in plain text.
'
title: EnvironmentVariablesType
EnvironmentVariableSourcePostman:
type: object
properties:
secretId:
type: string
description: The variable's secret ID.
type:
$ref: '#/components/schemas/EnvironmentVariableSourcePostmanType'
description: 'The variable''s type:
- `cloud` — The variable value is synced and stored in the Postman Cloud.
'
vaultId:
type: string
description: The variable's ID in the Postman Vault.
description: Information about the Postman-specific source of the variable's value.
title: EnvironmentVariableSourcePostman
patchEnvironmentInfo:
type: object
properties:
id:
type: string
description: The environment's ID.
name:
type: string
description: The environment's name.
owner:
type: string
description: The ID of environment's owner.
createdAt:
type: string
format: date-time
description: The date and time at which the environment was created.
updatedAt:
type: string
format: date-time
description: The date and time at which the environment was last updated.
values:
type: array
items:
$ref: '#/components/schemas/PatchEnvironmentInfoValuesItems'
description: Information about the environment's variables.
uid:
type: string
format: uid
description: The environment's unique ID.
description: Information about the environment.
title: patchEnvironmentInfo
EnvironmentVariableSourceProvider:
type: string
enum:
- postman
description: The secret's provider.
title: EnvironmentVariableSourceProvider
EnvironmentVariableSourcePostmanType:
type: string
enum:
- cloud
description: 'The variable''s type:
- `cloud` — The variable value is synced and stored in the Postman Cloud.
'
title: EnvironmentVariableSourcePostmanType
GetEnvironmentsRequestNotFoundError:
oneOf:
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
- $ref: '#/components/schemas/commonErrorNameMessage'
title: GetEnvironmentsRequestNotFoundError
CreateEnvironmentRequestUnauthorizedError:
oneOf:
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
- $ref: '#/components/schemas/commonErrorNameMessage'
title: CreateEnvironmentRequestUnauthorizedError
getEnvironments:
type: object
properties:
environments:
type: array
items:
$ref: '#/components/schemas/getEnvironmentsInfo'
description: A list of environments.
title: getEnvironments
DeleteEnvironmentEnvironment:
type: object
properties:
id:
type: string
description: The deleted environment's ID.
uid:
type: string
format: uid
description: The deleted environment's unique ID.
description: Information about the environment.
title: DeleteEnvironmentEnvironment
environmentId:
type: string
title: environmentId
PutEnvironmentResponseEnvironment:
type: object
properties:
id:
type: string
description: The environment's ID.
name:
type: string
description: The environment's name.
uid:
type: string
format: uid
description: The environment's unique ID.
description: Information about the environment.
title: PutEnvironmentResponseEnvironment
deleteEnvironment:
type: object
properties:
environment:
$ref: '#/components/schemas/DeleteEnvironmentEnvironment'
description: Information about the environment.
title: deleteEnvironment
CommonErrorNameMessageError:
type: object
properties:
name:
type: string
description: The error name.
message:
type: string
description: The error message.
description: Information about the error.
title: CommonErrorNameMessageError
CreateEnvironmentRequestInternalServerError:
oneOf:
- $ref: '#/components/schemas/commonErrorTypeTitleDetail'
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
- $ref: '#/components/schemas/commonErrorNameMessage'
title: CreateEnvironmentRequestInternalServerError
environmentSecret:
type: boolean
description: If true, the variable is marked as secret and its value is retrieved from the mentioned provider in the source field.
title: environmentSecret
pullEnvironmentResponse:
type: object
properties:
environment:
$ref: '#/components/schemas/PullEnvironmentResponseEnvironment'
description: Information about the merged environment.
title: pullEnvironmentResponse
PatchEnvironmentInfoValuesItems:
oneOf:
- $ref: '#/components/schemas/environmentVariables'
- $ref: '#/components/schemas/environmentVaultVariables'
title: PatchEnvironmentInfoValuesItems
forkEnvironmentResponse:
type: object
properties:
environment:
$ref: '#/components/schemas/ForkEnvironmentResponseEnvironment'
description: Information about the forked environment.
title: forkEnvironmentResponse
CreateEnvironmentEnvironment:
type: object
properties:
name:
type: s
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/postman/refs/heads/main/openapi/postman-environments-api-openapi.yml