OpenAPI Specification
openapi: 3.1.0
info:
title: Postman APIs API Comments API Versions API
description: 'The Postman APIs API enables you to manage your API definitions in Postman''s
API Builder. You can create APIs, manage versions, add schemas (OpenAPI,
GraphQL, etc.), and link collections, environments, mock servers, monitors,
and documentation to your API definitions.
## Authentication
All requests require an API key passed in the `x-api-key` header.
## Rate Limits
Standard Postman API rate limits apply.
'
version: 1.0.0
contact:
name: Postman Developer Support
url: https://learning.postman.com/docs/developer/postman-api/intro-api/
email: help@postman.com
license:
name: Postman Terms of Service
url: https://www.postman.com/legal/terms/
servers:
- url: https://api.getpostman.com
description: Postman Production API Server
security:
- apiKeyAuth: []
tags:
- name: API Versions
description: Operations for managing API versions.
paths:
/apis/{apiId}/versions:
get:
tags:
- API Versions
summary: Postman Get all API versions
operationId: getApiVersions
description: Gets all versions of an API. Each version can have its own schema and linked resources.
parameters:
- $ref: '#/components/parameters/ApiIdParam'
- name: cursor
in: query
schema:
type: string
- name: limit
in: query
schema:
type: integer
default: 10
responses:
'200':
description: Successful response with API versions
content:
application/json:
schema:
type: object
properties:
versions:
type: array
items:
$ref: '#/components/schemas/ApiVersion'
meta:
type: object
properties:
total:
type: integer
nextCursor:
type: string
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/RateLimitError'
post:
tags:
- API Versions
summary: Postman Create an API version
operationId: createApiVersion
description: Creates a new version of an API. You can optionally create the version from an existing version to copy its schema and relations.
parameters:
- $ref: '#/components/parameters/ApiIdParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- version
properties:
version:
type: object
required:
- name
properties:
name:
type: string
description: The version name (e.g., "1.0.0", "v2")
source:
type: object
description: Copy from an existing version
properties:
id:
type: string
description: The source version ID to copy from
responses:
'200':
description: Successfully created API version
content:
application/json:
schema:
$ref: '#/components/schemas/ApiVersion'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/RateLimitError'
/apis/{apiId}/versions/{versionId}:
get:
tags:
- API Versions
summary: Postman Get an API version
operationId: getApiVersion
description: Gets information about a specific version of an API.
parameters:
- $ref: '#/components/parameters/ApiIdParam'
- $ref: '#/components/parameters/VersionIdParam'
responses:
'200':
description: Successful response with API version details
content:
application/json:
schema:
$ref: '#/components/schemas/ApiVersion'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/RateLimitError'
put:
tags:
- API Versions
summary: Postman Update an API version
operationId: updateApiVersion
description: Updates the name of an API version.
parameters:
- $ref: '#/components/parameters/ApiIdParam'
- $ref: '#/components/parameters/VersionIdParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- version
properties:
version:
type: object
properties:
name:
type: string
responses:
'200':
description: Successfully updated API version
content:
application/json:
schema:
$ref: '#/components/schemas/ApiVersion'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/RateLimitError'
delete:
tags:
- API Versions
summary: Postman Delete an API version
operationId: deleteApiVersion
description: Deletes an API version and its schema.
parameters:
- $ref: '#/components/parameters/ApiIdParam'
- $ref: '#/components/parameters/VersionIdParam'
responses:
'200':
description: Successfully deleted API version
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/RateLimitError'
components:
responses:
NotFoundError:
description: The requested resource was not found
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
name:
type: string
message:
type: string
UnauthorizedError:
description: Authentication credentials are missing or invalid
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
name:
type: string
message:
type: string
RateLimitError:
description: Too many requests - rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
BadRequestError:
description: Bad request - invalid input
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
name:
type: string
message:
type: string
parameters:
VersionIdParam:
name: versionId
in: path
required: true
description: The API version's unique ID.
schema:
type: string
ApiIdParam:
name: apiId
in: path
required: true
description: The API's unique ID.
schema:
type: string
schemas:
ApiVersion:
type: object
description: A version of an API definition.
properties:
id:
type: string
name:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
schemas:
type: array
items:
type: string
collections:
type: array
items:
type: string
securitySchemes:
apiKeyAuth:
type: apiKey
name: x-api-key
in: header
description: Postman API key for authentication.