Postman Mocks API

openapi: 3.1.0
info:
  title: Postman APIs API Comments Mocks 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: Mocks
  description: Operations for creating and managing mock servers.
paths:
  /mocks:
    get:
      tags:
      - Mocks
      summary: Postman Get all mock servers
      operationId: getAllMocks
      description: Gets all mock servers accessible to the authenticated user. Returns metadata about each mock server including its URL, associated collection, and environment.
      parameters:
      - name: workspace
        in: query
        description: Filter by workspace ID.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response with list of mock servers
          content:
            application/json:
              schema:
                type: object
                properties:
                  mocks:
                    type: array
                    items:
                      $ref: '#/components/schemas/MockServer'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Mocks
      summary: Postman Create a mock server
      operationId: createMock
      description: Creates a new mock server from an existing collection. The mock server will serve responses based on the examples defined in the collection. You can optionally associate an environment.
      parameters:
      - name: workspace
        in: query
        description: The workspace ID to create the mock server in.
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - mock
              properties:
                mock:
                  $ref: '#/components/schemas/MockServerInput'
      responses:
        '200':
          description: Successfully created mock server
          content:
            application/json:
              schema:
                type: object
                properties:
                  mock:
                    $ref: '#/components/schemas/MockServer'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /mocks/{mockId}:
    get:
      tags:
      - Mocks
      summary: Postman Get a mock server
      operationId: getMock
      description: Gets information about a single mock server including its configuration, URL, associated collection, and environment.
      parameters:
      - $ref: '#/components/parameters/MockIdParam'
      responses:
        '200':
          description: Successful response with mock server details
          content:
            application/json:
              schema:
                type: object
                properties:
                  mock:
                    $ref: '#/components/schemas/MockServer'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Mocks
      summary: Postman Update a mock server
      operationId: updateMock
      description: Updates an existing mock server configuration including its name, description, associated environment, and privacy settings.
      parameters:
      - $ref: '#/components/parameters/MockIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - mock
              properties:
                mock:
                  $ref: '#/components/schemas/MockServerInput'
      responses:
        '200':
          description: Successfully updated mock server
          content:
            application/json:
              schema:
                type: object
                properties:
                  mock:
                    $ref: '#/components/schemas/MockServer'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Mocks
      summary: Postman Delete a mock server
      operationId: deleteMock
      description: Deletes a mock server. This action is irreversible.
      parameters:
      - $ref: '#/components/parameters/MockIdParam'
      responses:
        '200':
          description: Successfully deleted mock server
          content:
            application/json:
              schema:
                type: object
                properties:
                  mock:
                    type: object
                    properties:
                      id:
                        type: string
                      uid:
                        type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /mocks/{mockId}/publish:
    post:
      tags:
      - Mocks
      summary: Postman Publish a mock server
      operationId: publishMock
      description: Publishes a mock server, making it publicly accessible without requiring authentication.
      parameters:
      - $ref: '#/components/parameters/MockIdParam'
      responses:
        '200':
          description: Successfully published mock server
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
  /mocks/{mockId}/unpublish:
    delete:
      tags:
      - Mocks
      summary: Postman Unpublish a mock server
      operationId: unpublishMock
      description: Unpublishes a mock server, making it private and requiring authentication to access.
      parameters:
      - $ref: '#/components/parameters/MockIdParam'
      responses:
        '200':
          description: Successfully unpublished mock server
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
  /mocks/{mockId}/call-logs:
    get:
      tags:
      - Mocks
      summary: Postman Get mock server call logs
      operationId: getMockCallLogs
      description: Gets the call logs for a mock server. Call logs show requests that have been made to the mock server, including the request details, matched response, and timestamps.
      parameters:
      - $ref: '#/components/parameters/MockIdParam'
      - name: limit
        in: query
        description: Maximum number of call logs to return.
        schema:
          type: integer
          default: 100
      - name: cursor
        in: query
        description: Pagination cursor for the next page of results.
        schema:
          type: string
      - name: since
        in: query
        description: Return call logs since this timestamp (ISO 8601).
        schema:
          type: string
          format: date-time
      - name: until
        in: query
        description: Return call logs until this timestamp (ISO 8601).
        schema:
          type: string
          format: date-time
      - name: include
        in: query
        description: Include request and/or response body in the call logs.
        schema:
          type: string
          enum:
          - request.body
          - response.body
          - request.headers
          - response.headers
      - name: sort
        in: query
        description: Sort order for call logs.
        schema:
          type: string
          enum:
          - servedAt
      - name: direction
        in: query
        description: Sort direction.
        schema:
          type: string
          enum:
          - asc
          - desc
      responses:
        '200':
          description: Successful response with call logs
          content:
            application/json:
              schema:
                type: object
                properties:
                  callLogs:
                    type: array
                    items:
                      $ref: '#/components/schemas/MockCallLog'
                  meta:
                    type: object
                    properties:
                      nextCursor:
                        type: string
                      total:
                        type: integer
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
components:
  responses:
    BadRequestError:
      description: Bad request - invalid input
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string
    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
    InternalServerError:
      description: An unexpected error occurred on the server
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string
  schemas:
    MockServer:
      type: object
      description: A Postman mock server that simulates API responses.
      properties:
        id:
          type: string
          description: The mock server's unique ID
        name:
          type: string
          description: The mock server name
        uid:
          type: string
          description: The mock server's UID
        owner:
          type: string
          description: The owner ID
        collection:
          type: string
          description: The associated collection ID
        environment:
          type: string
          description: The associated environment ID
        mockUrl:
          type: string
          format: uri
          description: The URL for making requests to this mock server
        config:
          type: object
          properties:
            delay:
              type: object
              description: Response delay configuration
              properties:
                type:
                  type: string
                  enum:
                  - fixed
                preset:
                  type: string
                  enum:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                duration:
                  type: integer
                  description: Delay in milliseconds
            headers:
              type: array
              items:
                type: string
            matchBody:
              type: boolean
              description: Whether to match request body when selecting responses
            matchQueryParams:
              type: boolean
              description: Whether to match query parameters when selecting responses
            matchWildcards:
              type: boolean
              description: Whether to support wildcard variables in URLs
        isPublic:
          type: boolean
          description: Whether the mock server is publicly accessible
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    MockServerInput:
      type: object
      description: Input format for creating or updating a mock server.
      required:
      - collection
      properties:
        name:
          type: string
          description: The mock server name
        collection:
          type: string
          description: The collection ID to mock
        environment:
          type: string
          description: The environment ID to use with the mock
        description:
          type: string
        private:
          type: boolean
          description: Whether the mock server should be private
          default: true
        config:
          type: object
          properties:
            matchBody:
              type: boolean
            matchQueryParams:
              type: boolean
            matchWildcards:
              type: boolean
    MockCallLog:
      type: object
      description: A log entry for a request made to a mock server.
      properties:
        id:
          type: string
        responseId:
          type: string
        servedAt:
          type: string
          format: date-time
        request:
          type: object
          properties:
            method:
              type: string
            path:
              type: string
            headers:
              type: object
              additionalProperties:
                type: string
            body:
              type: string
        response:
          type: object
          properties:
            statusCode:
              type: integer
            headers:
              type: object
              additionalProperties:
                type: string
            body:
              type: string
            type:
              type: string
              enum:
              - default
              - serverResponse
              - collectionExample
  parameters:
    MockIdParam:
      name: mockId
      in: path
      required: true
      description: The mock server's unique ID or UID.
      schema:
        type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: x-api-key
      in: header
      description: Postman API key for authentication.