Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: APIs.io Engineering Platform Postman API Security API
description: "The Postman API enables you to programmatically access data stored in your Postman account.\n\n> Certain endpoints may be unavailable depending on your region and/or Postman plan.\n\nFor a comprehensive set of examples of requests and responses, see the [**Postman API** collection](https://www.postman.com/postman/workspace/postman-public-workspace/documentation/12959542-c8142d51-e97c-46b6-bd77-52bb66712c9a).\n\n## Getting started\n\nYou can get started with the Postman API by creating a copy of this definition in your workspace.\n\n### EU users\n\nFor users in the EU with [**Enterprise** plans](https://www.postman.com/pricing/), the Postman API uses the `http://api.eu.postman.com` subdomain. This is available in the definition's list of servers. You can change this by selecting the `http://api.eu.postman.com` subdomain in the **Server** dropdown list below.\n\n## About the Postman API\n\n- You must use a valid API Key to send requests to the API endpoints.\n- The API has [rate and usage limits](https://learning.postman.com/docs/developer/postman-api/postman-api-rate-limits/).\n- The API only responds to HTTPS-secured communications. Any requests sent via HTTP return an HTTP `301` redirect to the corresponding HTTPS resources.\n- The API returns requests responses in JSON format. When an API request returns an error, it is sent in the JSON response as an error key.\n- The request method (verb) determines the nature of action you intend to perform. A request made using the `GET` method implies that you want to fetch something from Postman. The `POST` method implies you want to save something new to Postman.\n- For all requests, API calls respond with their corresponding [HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). In the Postman client, the status code also provides help text that details the possible meaning of the response code.\n- When calling the API Builder endpoints, you must send an `Accept` header with the `application/vnd.api.v10+json` value.\n\n### IDs and UIDs\n\nAll items in Postman, such as collections, workspaces, and APIs, have IDs and UIDs:\n\n- An ID is the unique ID assigned to a Postman item. For example, `ec29121c-5203-409f-9e84-e83ffc10f226`.\n- The UID is the **full** ID of a Postman item. This value is the item's unique ID concatenated with the user ID. For example, in the `12345678-ec29121c-5203-409f-9e84-e83ffc10f226` UID:\n - `12345678` is the user's ID.\n - `ec29121c-5203-409f-9e84-e83ffc10f226` is the item's ID.\n\n### Enum values\n\nAny documented enum values should be considered partial lists and may change over time.\n\n### 403 response for unavailable features\n\nDepending on your region and/or Postman [plan](https://www.postman.com/pricing/), some endpoints will return an HTTP `403 Forbidden` response with the \"This feature isn't available in your region.\" detail.\n\n### 503 response\n\nAn HTTP `503 Service Unavailable` response from our servers indicates there is an unexpected spike in API access traffic. The server is usually operational within the next five minutes.\n\nIf the outage persists or you receive any other form of an HTTP `5XX` error, [contact support](https://support.postman.com/hc/en-us/requests/new/).\n\n## Authentication\n\nPostman uses API keys for authentication. The API key tells the API server that the request came from you. Everything that you have access to in Postman is accessible with your API key. You can [generate](https://learning.postman.com/docs/developer/postman-api/authentication/#generate-a-postman-api-key) a Postman API key in the [**API keys**](https://postman.postman.co/settings/me/api-keys) section of your Postman account settings.\n\nYou must include an API key in each request to the Postman API with the `X-API-Key` request header. In Postman, you can store your API key as a [vault secret](https://learning.postman.com/docs/sending-requests/postman-vault/postman-vault-secrets/) or an [environment variable](https://www.getpostman.com/docs/environments). The Postman API [collection](https://www.getpostman.com/docs/collections) will use it to make API calls.\n\n### SCIM authentication\n\nWhile all other endpoints in this collection require a Postman API key, the SCIM endpoints require a [SCIM API key](https://learning.postman.com/docs/administration/scim-provisioning/scim-provisioning-overview/#generating-scim-api-key).\n\n### Authentication error response\n\nIf an API key is missing, malformed, or invalid, you will receive an HTTP `401 Unauthorized` response code.\n\n## Rate and usage limits\n\nAPI access [rate limits](https://learning.postman.com/docs/developer/postman-api/postman-api-rate-limits/) apply at a per-user basis in unit time. The limit is **300 requests per minute**. Postman Monitors, the GET `/collections`, and the GET `/workspaces` endpoint have a rate limit of **10 calls in 10 seconds**. Depending on your [plan](https://www.postman.com/pricing/), you may also have [usage limits](https://learning.postman.com/docs/billing/resource-usage/).\n\nWhen you reach your rate or usage limits, the API returns the following HTTP `429 Too Many Requests` status code with one of the following error responses:\n\n- `rateLimited` — Rate limits reached. The response returns the time after which you can resume calls to the Postman API.\n- `serviceLimitExhausted` — Postman API service limits reached. You will need to contact your Postman Team Admin for assistance.\n\n## Support\n\nFor help regarding accessing the Postman API, you can:\n\n- Visit [Postman Support](https://support.postman.com/hc/en-us) or our [Community and Support](https://www.postman.com/community/) sites.\n- Reach out to the [Postman community](https://community.postman.com/).\n- Submit a help request to [Postman support](https://support.postman.com/hc/en-us/requests/new/).\n\n## Policies\n\n- [Postman Terms of Service](http://www.postman.com/legal/terms/)\n- [Postman Privacy Policy](https://www.postman.com/legal/privacy-policy/)\n"
version: '1.0'
termsOfService: https://www.postman.com/legal/terms/
contact:
name: Postman Support
email: help@postman.com
url: https://www.postman.com/community/
servers:
- url: https://api.getpostman.com
- url: https://api.eu.postman.com
security:
- PostmanApiKey: []
- scimApiKey: []
tags:
- name: API Security
description: The **API Security** endpoints enable you to manage the [security of your API](https://learning.postman.com/docs/api-governance/api-definition/api-definition-warnings/). API security includes ensuring you follow security and format warnings and schema validation.
paths:
/security/api-validation:
post:
summary: APIs.io Engineering Platform API definition security validation
description: 'Performs an analysis on the given definition and returns any issues based on your [predefined rulesets](https://learning.postman.com/docs/api-governance/configurable-rules/configurable-rules-overview/). This endpoint can help you understand the violations'' impact and offers solutions to help you resolve any errors. You can include this endpoint to your CI/CD process to automate schema validation.
For more information, see [Track governance and security rule violations in the API definition](https://learning.postman.com/docs/api-governance/api-definition/api-definition-warnings/).
**Note:**
- The maximum allowed size of the definition is 10 MB.
- You must [import and enable](https://learning.postman.com/docs/api-governance/configurable-rules/configuring-api-security-rules/) Postman''s [OWASP security rules](https://postman.postman.co/api-governance/libraries/postman_owasp/view) for this endpoint to return any security rule violations.
'
operationId: schemaSecurityValidation
tags:
- API Security
requestBody:
$ref: '#/components/requestBodies/schemaSecurityValidation'
responses:
'200':
$ref: '#/components/responses/schemaSecurityValidation'
'400':
$ref: '#/components/responses/schemaSecurityValidation400Error'
'401':
$ref: '#/components/responses/common401Error'
'403':
$ref: '#/components/responses/featureUnavailable403Error'
'500':
$ref: '#/components/responses/common500ErrorServerError'
components:
responses:
featureUnavailable403Error:
description: Feature Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/featureUnavailable403Error'
example:
value:
type: https://api.postman.com/problems/forbidden
title: Forbidden
detail: This feature isn't available in your region.
status: 403
schemaSecurityValidation:
description: Successful Response
content:
application/json:
schema:
type: object
properties:
warnings:
type: array
description: 'Information about each issue discovered in the analysis. Each object includes the violation''s severity and category, the location of the issue, data paths, and other information. This returns an empty object if there are no issues present in the schema.
If there are issues, this returns the `possibleFixUrl` response in each warning object. This provides a link to documentation you can use to resolve the warning.
'
items:
type: object
additionalProperties: true
examples:
No Warnings Found:
$ref: '#/components/examples/schemaSecurityValidationNoWarnings'
Successful Response with Governance Warnings:
$ref: '#/components/examples/schemaSecurityValidationGovernanceWarnings'
Successful Response with Security Warnings:
$ref: '#/components/examples/schemaSecurityValidationSecurityWarnings'
schemaSecurityValidation400Error:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/schemaSecurityValidation400Error'
examples:
Invalid Schema:
$ref: '#/components/examples/schemaSecurityValidation400Error'
common401Error:
description: Unauthorized
content:
application/problem+json:
schema:
type: object
properties:
type:
type: string
format: uri-reference
description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
example: https://api.postman.com/problems/unauthorized
title:
type: string
description: A short summary of the problem.
example: Unauthorized
detail:
type: string
description: Information about the error.
example: Unauthorized
status:
type: integer
format: http-status-code
description: The error's HTTP status code.
example: 401
example:
type: https://api.postman.com/problems/unauthorized
title: Unauthorized
detail: Unauthorized
status: 401
common500ErrorServerError:
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
name:
type: string
description: The error name.
example: serverError
message:
type: string
description: The error message.
example: An error has occurred on the server.
example:
error:
name: serverError
message: An error has occurred on the server.
schemas:
schemaSecurityValidation400Error:
title: Invalid Schema
type: object
properties:
error:
type: object
properties:
name:
type: object
properties:
name:
type: string
description: The error name.
example: Invalid schema
message:
type: string
description: The error message.
example: Provided schema type is not supported.
schemaSecurityValidationRequest:
title: Schema Validation Request Body
type: object
properties:
schema:
type: object
required:
- language
- schema
- type
properties:
language:
type: string
description: The definition format.
enum:
- json
- yaml
example: json
schema:
type: string
description: The stringified API definition.
example: '{"openapi":"3.0.0","info":{"version":"1","title":"temp","license":{"name":"MIT"}},"servers":[{"url":"https://petstore.swagger.io/v1"}],"paths":{"/user":{"get":{"summary":"Details about a user","operationId":"listUser","tags":["user"],"parameters":[{"name":"id","in":"query","description":"ID of the user","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"Details about a user","headers":{"x-next":{"description":"A link to the next page of responses","schema":{"type":"string"}}},"content":{"application/json":{"schema":{$ref:"#/components/schemas/User"}}}},"default":{"description":"unexpected error","content":{"application/json":{"schema":{$ref:"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"User":{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"tag":{"type":"string"}}},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}}},"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}}},"security":[{"BasicAuth":[]}]}'
type:
type: string
description: The definition type.
enum:
- openapi3
- openapi2
example: openapi3
featureUnavailable403Error:
title: Feature Unavailable
type: object
properties:
type:
type: string
format: uri-reference
description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
example: https://api.postman.com/problems/forbidden
title:
type: string
description: A short summary of the problem.
example: Forbidden
detail:
type: string
description: Information about the error.
example: This feature isn't available in your region.
status:
type: integer
format: http-status-code
description: The error's HTTP status code.
example: 403
examples:
schemaSecurityValidationSecurityWarnings:
value:
warnings:
- slug: POSTMAN_OWASP_GOVERNANCE_RULE_0005
severity: WARN
message: Security field is not defined
location:
start:
line: 1
column: 0
end:
line: 75
column: 21
dataPath: []
possibleFixUrl: https://go.pstmn.io/openapi3-security-warnings#security-field-is-not-defined
category:
name: governance
slug: governance
vulnerability:
name: Security field is not defined
slug: POSTMAN_OWASP_GOVERNANCE_VULNERABILITY_0005
type: governance
checksum: ff10236473b8bc137ecdb94c282de9375503772beffffd02eb7aa957e1a3e873
- slug: POSTMAN_OWASP_GOVERNANCE_RULE_0017
severity: WARN
message: Operation does not enforce any security scheme.
location:
start:
line: 16
column: 8
end:
line: 36
column: 50
dataPath:
- paths
- /spacecrafts/{spacecraftId}
- get
possibleFixUrl: https://go.pstmn.io/openapi3-security-warnings#operation-does-not-enforce-any-security-scheme
category:
name: governance
slug: governance
vulnerability:
name: Operation does not enforce any security scheme.
slug: POSTMAN_OWASP_GOVERNANCE_VULNERABILITY_0017
type: governance
checksum: 7760d7354c85b925141d708e14ecaef6512ef20a5b89ba8c722d1fc16c1e5b02
schemaSecurityValidationRequest:
value:
schema:
type: openapi3
language: json
schema: '{"openapi":"3.0.0","info":{"version":"1","title":"temp","license":{"name":"MIT"}},"servers":[{"url":"https://petstore.swagger.io/v1"}],"paths":{"/user":{"get":{"summary":"Details about a user","operationId":"listUser","tags":["user"],"parameters":[{"name":"id","in":"query","description":"ID of the user","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"Details about a user","headers":{"x-next":{"description":"A link to the next page of responses","schema":{"type":"string"}}},"content":{"application/json":{"schema":{$ref:"#/components/schemas/User"}}}},"default":{"description":"unexpected error","content":{"application/json":{"schema":{$ref:"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"User":{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"tag":{"type":"string"}}},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}}},"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}}},"security":[{"BasicAuth":[]}]}'
schemaSecurityValidationNoWarnings:
value:
warnings: []
schemaSecurityValidation400Error:
value:
error:
name:
name: Invalid Schema
reason: Provided schema type is not supported.
schemaSecurityValidationGovernanceWarnings:
value:
warnings:
- slug: OPENAPI_SPECTRAL_6_RULE_1027
severity: WARN
message: A schema property should have a $ref property referencing a reusable schema
location:
start:
line: 55
column: 26
end:
line: 58
column: 17
dataPath:
- components
- parameters
- userId
- schema
possibleFixUrl: https://go.pstmn.io/openapi3-security-warnings#a-schema-property-should-reference-a-reusable-schema
category:
name: governance
slug: governance
vulnerability:
name: A schema property should have a $ref property.
slug: OPENAPI_SPECTRAL_6_schema_reference_reusable
type: governance
checksum: 2fc9df0e8ccbcdb610ab1694651bb68731fc5add4ebb44da0e5f15faf634b035
requestBodies:
schemaSecurityValidation:
content:
application/json:
schema:
$ref: '#/components/schemas/schemaSecurityValidationRequest'
examples:
Request Body:
$ref: '#/components/examples/schemaSecurityValidationRequest'
securitySchemes:
PostmanApiKey:
type: apiKey
in: header
name: x-api-key
scimApiKey:
type: apiKey
in: header
name: Authorization
description: A valid [SCIM API key](https://learning.postman.com/docs/administration/scim-provisioning/scim-provisioning-overview/#generating-scim-api-key) for calls to SCIM endpoints.