Postman Monitors API

openapi: 3.1.0
info:
  title: Postman APIs API Comments Monitors 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: Monitors
  description: Operations for creating and managing Postman monitors.
paths:
  /monitors:
    get:
      tags:
      - Monitors
      summary: Postman Get all monitors
      operationId: getAllMonitors
      description: Gets all monitors accessible to the authenticated user. Returns metadata about each monitor including schedule, last run status, and associated collection.
      parameters:
      - name: workspace
        in: query
        description: Filter monitors by workspace ID.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response with list of monitors
          content:
            application/json:
              schema:
                type: object
                properties:
                  monitors:
                    type: array
                    items:
                      $ref: '#/components/schemas/MonitorListItem'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Monitors
      summary: Postman Create a monitor
      operationId: createMonitor
      description: Creates a new monitor that runs a collection on a specified schedule. You must specify the collection to run, the environment to use, and the schedule (cron expression or interval).
      parameters:
      - name: workspace
        in: query
        description: The workspace ID to create the monitor in.
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - monitor
              properties:
                monitor:
                  $ref: '#/components/schemas/MonitorInput'
      responses:
        '200':
          description: Successfully created monitor
          content:
            application/json:
              schema:
                type: object
                properties:
                  monitor:
                    $ref: '#/components/schemas/Monitor'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /monitors/{monitorId}:
    get:
      tags:
      - Monitors
      summary: Postman Get a monitor
      operationId: getMonitor
      description: Gets information about a single monitor, including its configuration, schedule, last run details, and notification settings.
      parameters:
      - $ref: '#/components/parameters/MonitorIdParam'
      responses:
        '200':
          description: Successful response with monitor details
          content:
            application/json:
              schema:
                type: object
                properties:
                  monitor:
                    $ref: '#/components/schemas/Monitor'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Monitors
      summary: Postman Update a monitor
      operationId: updateMonitor
      description: Updates an existing monitor's name, schedule, collection, or environment configuration.
      parameters:
      - $ref: '#/components/parameters/MonitorIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - monitor
              properties:
                monitor:
                  $ref: '#/components/schemas/MonitorInput'
      responses:
        '200':
          description: Successfully updated monitor
          content:
            application/json:
              schema:
                type: object
                properties:
                  monitor:
                    $ref: '#/components/schemas/Monitor'
        '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:
      - Monitors
      summary: Postman Delete a monitor
      operationId: deleteMonitor
      description: Deletes a monitor. This stops all scheduled runs and is irreversible.
      parameters:
      - $ref: '#/components/parameters/MonitorIdParam'
      responses:
        '200':
          description: Successfully deleted monitor
          content:
            application/json:
              schema:
                type: object
                properties:
                  monitor:
                    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'
  /monitors/{monitorId}/run:
    post:
      tags:
      - Monitors
      summary: Postman Run a monitor
      operationId: runMonitor
      description: Manually triggers a monitor run. The response includes the run results with test pass/fail status, response times, and any errors.
      parameters:
      - $ref: '#/components/parameters/MonitorIdParam'
      responses:
        '200':
          description: Successful monitor run with results
          content:
            application/json:
              schema:
                type: object
                properties:
                  run:
                    $ref: '#/components/schemas/MonitorRun'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
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:
    Monitor:
      type: object
      description: Full monitor details including schedule and run history.
      properties:
        id:
          type: string
          description: The monitor's unique ID
        name:
          type: string
          description: The monitor name
        uid:
          type: string
          description: The monitor's UID
        owner:
          type: string
          description: The owner ID
        collectionUid:
          type: string
          description: The UID of the collection being monitored
        environmentUid:
          type: string
          description: The UID of the environment used during runs
        distribution:
          type: array
          description: The regions from which the monitor runs
          items:
            type: string
        schedule:
          type: object
          description: The monitor's run schedule
          properties:
            cron:
              type: string
              description: The cron expression defining the schedule
              example: 0 0 * * *
            timezone:
              type: string
              description: The timezone for the schedule
              example: America/New_York
            nextRun:
              type: string
              format: date-time
              description: The next scheduled run time
        lastRun:
          type: object
          description: Details about the last monitor run
          properties:
            startedAt:
              type: string
              format: date-time
            finishedAt:
              type: string
              format: date-time
            status:
              type: string
              enum:
              - success
              - failure
              - error
              - abort
            stats:
              type: object
              properties:
                assertions:
                  type: object
                  properties:
                    total:
                      type: integer
                    failed:
                      type: integer
                requests:
                  type: object
                  properties:
                    total:
                      type: integer
        notifications:
          type: object
          properties:
            onError:
              type: array
              items:
                type: object
                properties:
                  email:
                    type: string
            onFailure:
              type: array
              items:
                type: object
                properties:
                  email:
                    type: string
        options:
          type: object
          properties:
            strictSSL:
              type: boolean
            followRedirects:
              type: boolean
            requestTimeout:
              type: integer
              description: Timeout in milliseconds
            requestDelay:
              type: integer
              description: Delay between requests in milliseconds
    MonitorInput:
      type: object
      description: Input format for creating or updating a monitor.
      required:
      - name
      - collection
      - schedule
      properties:
        name:
          type: string
          description: The monitor name
        collection:
          type: string
          description: The collection UID to monitor
        environment:
          type: string
          description: The environment UID to use
        schedule:
          type: object
          required:
          - cron
          properties:
            cron:
              type: string
              description: Cron expression for the schedule
            timezone:
              type: string
              description: Timezone for the schedule
    MonitorListItem:
      type: object
      description: Abbreviated monitor information returned in list responses.
      properties:
        id:
          type: string
          description: The monitor's unique ID
        name:
          type: string
          description: The monitor name
        uid:
          type: string
          description: The monitor's UID
        owner:
          type: string
          description: The owner ID
    MonitorRun:
      type: object
      description: Results of a monitor run.
      properties:
        info:
          type: object
          properties:
            jobId:
              type: string
            monitorId:
              type: string
            name:
              type: string
            collectionUid:
              type: string
            environmentUid:
              type: string
            status:
              type: string
              enum:
              - success
              - failure
              - error
              - abort
            startedAt:
              type: string
              format: date-time
            finishedAt:
              type: string
              format: date-time
        stats:
          type: object
          properties:
            assertions:
              type: object
              properties:
                total:
                  type: integer
                failed:
                  type: integer
            requests:
              type: object
              properties:
                total:
                  type: integer
        executions:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              item:
                type: object
                properties:
                  name:
                    type: string
              request:
                type: object
                properties:
                  url:
                    type: string
                  method:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
              response:
                type: object
                properties:
                  statusCode:
                    type: integer
                  responseTime:
                    type: integer
                    description: Response time in milliseconds
                  responseSize:
                    type: integer
                    description: Response size in bytes
              assertions:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    error:
                      type: string
        failures:
          type: array
          items:
            type: object
  parameters:
    MonitorIdParam:
      name: monitorId
      in: path
      required: true
      description: The monitor's unique ID or UID.
      schema:
        type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: x-api-key
      in: header
      description: Postman API key for authentication.