openapi: 3.1.0
info:
  title: Postman Mock Servers API
  description: |
    The Postman Mock Servers API enables you to create and manage mock servers
    that simulate API behavior. Mock servers generate responses based on examples
    saved in your Postman collections, allowing frontend and backend teams to
    work in parallel during API development.

    ## Authentication
    All requests require an API key passed in the `x-api-key` header.

    ## Rate Limits
    Mock server calls have separate usage limits based on your Postman plan.
    Free plans include 1,000 mock server calls per month.
  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
tags:
  - name: Mocks
    description: Operations for creating and managing mock servers.
  - name: Server Responses
    description: Operations for managing mock server responses and examples.
security:
  - apiKeyAuth: []
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}/serverResponses:
    get:
      tags:
        - Server Responses
      summary: Postman Get mock server responses
      operationId: getMockServerResponses
      description: >-
        Gets all server responses configured for a mock server. Server responses
        are custom responses that override the default collection-based responses.
      parameters:
        - $ref: '#/components/parameters/MockIdParam'
      responses:
        '200':
          description: Successful response with list of server responses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServerResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
    post:
      tags:
        - Server Responses
      summary: Postman Create a server response
      operationId: createServerResponse
      description: >-
        Creates a new server response for a mock server. Server responses
        allow you to define custom responses for specific request patterns.
      parameters:
        - $ref: '#/components/parameters/MockIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServerResponseInput'
      responses:
        '200':
          description: Successfully created server response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
  /mocks/{mockId}/serverResponses/{serverResponseId}:
    put:
      tags:
        - Server Responses
      summary: Postman Update a server response
      operationId: updateServerResponse
      description: >-
        Updates an existing server response for a mock server.
      parameters:
        - $ref: '#/components/parameters/MockIdParam'
        - name: serverResponseId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServerResponseInput'
      responses:
        '200':
          description: Successfully updated server response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
    delete:
      tags:
        - Server Responses
      summary: Postman Delete a server response
      operationId: deleteServerResponse
      description: >-
        Deletes a server response from a mock server.
      parameters:
        - $ref: '#/components/parameters/MockIdParam'
        - name: serverResponseId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully deleted server response
        '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:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: x-api-key
      in: header
      description: Postman API key for authentication.
  parameters:
    MockIdParam:
      name: mockId
      in: path
      required: true
      description: The mock server's unique ID or UID.
      schema:
        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
    ServerResponse:
      type: object
      description: A custom server response configured on a mock server.
      properties:
        id:
          type: string
        name:
          type: string
        statusCode:
          type: integer
        headers:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
        body:
          type: string
        language:
          type: string
          enum: [text, json, xml, html, javascript]
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ServerResponseInput:
      type: object
      required:
        - name
        - statusCode
      properties:
        name:
          type: string
        statusCode:
          type: integer
        headers:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
        body:
          type: string
        language:
          type: string
          enum: [text, json, xml, html, javascript]
    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]
  responses:
    BadRequestError:
      description: Bad request - invalid input
      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
    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
    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