APIs.io Engineering Platform Monitors API

openapi: 3.2.0
info:
  title: APIs.io Engineering Platform Postman Monitors 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: Monitors
  description: The **Monitors** endpoints enable you to manage your [monitors](https://learning.postman.com/docs/monitoring-your-api/intro-monitors/).
paths:
  /monitors:
    get:
      summary: APIs.io Engineering Platform Get all monitors
      description: Gets all monitors.
      operationId: getMonitors
      tags:
      - Monitors
      responses:
        '200':
          $ref: '#/components/responses/getMonitors'
        '401':
          $ref: '#/components/responses/common401Error'
        '403':
          $ref: '#/components/responses/featureUnavailable403Error'
        '500':
          $ref: '#/components/responses/common500ErrorServerError'
      parameters:
      - $ref: '#/components/parameters/workspaceResultsQuery'
    post:
      summary: APIs.io Engineering Platform Create a monitor
      description: 'Creates a monitor.


        **Note:**


        You cannot create monitors for collections added to an API definition.

        '
      operationId: createMonitor
      tags:
      - Monitors
      requestBody:
        $ref: '#/components/requestBodies/createMonitor'
      responses:
        '200':
          $ref: '#/components/responses/createMonitor'
        '400':
          $ref: '#/components/responses/monitors400CreateErrors'
        '401':
          $ref: '#/components/responses/common401Error'
        '403':
          $ref: '#/components/responses/common403ErrorAndFeatureUnavailable'
        '500':
          $ref: '#/components/responses/common500ErrorServerError'
      parameters:
      - $ref: '#/components/parameters/workspaceQuery'
  /monitors/{monitorId}:
    parameters:
    - $ref: '#/components/parameters/monitorId'
    get:
      summary: APIs.io Engineering Platform Get a monitor
      description: Gets information about a monitor.
      operationId: getMonitor
      tags:
      - Monitors
      responses:
        '200':
          $ref: '#/components/responses/getMonitor'
        '401':
          $ref: '#/components/responses/common401Error'
        '403':
          $ref: '#/components/responses/featureUnavailable403Error'
        '404':
          $ref: '#/components/responses/instanceNotFoundMonitor'
        '500':
          $ref: '#/components/responses/common500ErrorServerError'
    put:
      summary: APIs.io Engineering Platform Update a monitor
      description: Updates a monitor.
      operationId: updateMonitor
      tags:
      - Monitors
      requestBody:
        $ref: '#/components/requestBodies/updateMonitor'
      responses:
        '200':
          $ref: '#/components/responses/updateMonitor'
        '400':
          $ref: '#/components/responses/monitors400ErrorInvalidCronPattern'
        '401':
          $ref: '#/components/responses/common401Error'
        '403':
          $ref: '#/components/responses/featureUnavailable403Error'
        '404':
          $ref: '#/components/responses/instanceNotFoundMonitor'
        '500':
          $ref: '#/components/responses/common500ErrorServerError'
    delete:
      summary: APIs.io Engineering Platform Delete a monitor
      description: Deletes a monitor.
      operationId: deleteMonitor
      tags:
      - Monitors
      responses:
        '200':
          $ref: '#/components/responses/deleteMonitor'
        '401':
          $ref: '#/components/responses/common401Error'
        '403':
          $ref: '#/components/responses/featureUnavailable403Error'
        '500':
          $ref: '#/components/responses/common500ErrorServerError'
  /monitors/{monitorId}/run:
    parameters:
    - $ref: '#/components/parameters/monitorId'
    - $ref: '#/components/parameters/async'
    post:
      summary: APIs.io Engineering Platform Run a monitor
      description: 'Runs a monitor and returns its run results.


        **Note:**


        If you pass the `async=true` query parameter, the response does not return the `stats`, `executions`, and `failures` responses. To get this information for an asynchronous run, call the GET `/monitors/{id}` endpoint.

        '
      operationId: runMonitor
      tags:
      - Monitors
      responses:
        '200':
          $ref: '#/components/responses/runMonitor'
        '401':
          $ref: '#/components/responses/common401Error'
        '403':
          $ref: '#/components/responses/featureUnavailable403Error'
        '500':
          $ref: '#/components/responses/common500ErrorServerError'
components:
  parameters:
    async:
      name: async
      in: query
      description: If true, runs the monitor asynchronously from the created monitor run task. By default, the server will not respond until the task finishes (`false`).
      schema:
        type: boolean
        default: false
        example: false
    monitorId:
      name: monitorId
      in: path
      required: true
      description: The monitor's ID.
      schema:
        type: string
        example: 1e6b6cc1-c760-48e0-968f-4bfaeeae9af1
    workspaceQuery:
      name: workspace
      in: query
      description: The workspace's ID.
      schema:
        $ref: '#/components/schemas/workspaceId'
    workspaceResultsQuery:
      name: workspace
      in: query
      description: Return only results found in the given workspace.
      schema:
        $ref: '#/components/schemas/workspaceId'
  examples:
    monitors400ErrorMissingParameter:
      value:
        error:
          name: paramMissingError
          message: Parameter is missing in the request.
          details:
            param:
            - name
    monitors400ErrorInvalidEnvironmentUid:
      value:
        error:
          name: invalidUidError
          message: The specified uid is invalid.
          details:
            param: environment
            uid: 5daabc50-8451-43f6-922d-96b403b4f28e
    monitors400ErrorInvalidTimezone:
      value:
        error:
          name: invalidParamsError
          message: The request had invalid parameters
          details:
            param: schedule.timezone
    monitors400ErrorInvalidCronPattern:
      value:
        error:
          name: cronPatternNotAllowedError
          message: Invalid cron pattern. Enter a valid cron pattern, such as "0 17 * * *"
          details:
            pattern: '* * * * *'
    monitors400ErrorInvalidCollectionUid:
      value:
        error:
          name: invalidUidError
          message: The specified uid is invalid.
          details:
            param: collection
            uid: 12ece9e1-2abf-4edc-8e34-de66e74114d2
  schemas:
    monitors400ParamMissing:
      title: Missing Parameter
      type: object
      properties:
        error:
          type: object
          properties:
            name:
              type: string
              description: The error name.
              example: paramMissingError
            message:
              type: string
              description: The error message.
              example: Parameter is missing in the request.
            details:
              type: object
              description: Information about the error.
              properties:
                param:
                  type: array
                  description: A list of the missing parameters.
                  items:
                    type: string
                    example: name
    workspaceId:
      type: string
      example: 1f0df51a-8658-4ee8-a2a1-d2567dfa09a9
    monitors400ErrorInvalidUid:
      title: Invalid UID
      type: object
      properties:
        error:
          type: object
          properties:
            name:
              type: string
              description: The error name.
              example: invalidUidError
            message:
              type: string
              description: The error message.
              example: The specified uid is invalid.
            details:
              type: object
              description: Information about the error.
              properties:
                param:
                  type: string
                  description: The invalid parameter.
                  example: collection
                uid:
                  type: string
                  format: uid
                  description: The invalid UID.
                  example: 5daabc50-8451-43f6-922d-96b403b4f28e
    monitors400ErrorInvalidCronPattern:
      title: Invalid Cron Pattern
      type: object
      properties:
        error:
          type: object
          properties:
            name:
              type: string
              description: The error name.
              example: cronPatternNotAllowedError
            message:
              type: string
              description: The error message.
              example: Invalid cron pattern. Enter a valid cron pattern, such as "0 17 * * *"
            details:
              type: object
              description: Information about the error.
              properties:
                pattern:
                  type: string
                  description: The invalid cron pattern.
                  example: '* * * * *'
    monitors400ErrorInvalidTimezone:
      title: Invalid Timezone
      type: object
      properties:
        error:
          type: object
          properties:
            name:
              type: string
              description: The error name.
              example: invalidParamsError
            message:
              type: string
              description: The error message.
              example: The request had invalid parameters
            details:
              type: object
              description: Information about the error.
              properties:
                param:
                  type: string
                  description: The invalid parameter.
                  example: schedule.timezone
    common403Error:
      title: Forbidden
      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: Forbidden
        status:
          type: integer
          format: http-status-code
          description: The error's HTTP status code.
          example: 403
    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
  responses:
    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
    updateMonitor:
      description: Successful Response
      content:
        application/json:
          schema:
            type: object
            properties:
              monitor:
                type: object
                properties:
                  id:
                    type: string
                    description: The monitor's ID.
                    example: 1e6b6cc1-c760-48e0-968f-4bfaeeae9af1
                  name:
                    type: string
                    description: The monitor's name.
                    example: Test Monitor
                  uid:
                    type: string
                    format: uid
                    description: The monitor's unique ID.
                    example: 12345678-1e6b6cc1-c760-48e0-968f-4bfaeeae9af1
          example:
            monitor:
              id: 1e6b6cc1-c760-48e0-968f-4bfaeeae9af1
              name: Test Monitor
              uid: 12345678-1e6b6cc1-c760-48e0-968f-4bfaeeae9af1
    createMonitor:
      description: Successful Response
      content:
        application/json:
          schema:
            type: object
            properties:
              monitor:
                type: object
                properties:
                  id:
                    type: string
                    description: The monitor's ID.
                    example: 1e6b6cc1-c760-48e0-968f-4bfaeeae9af1
                  name:
                    type: string
                    description: The monitor's name.
                    example: Test Monitor
                  uid:
                    type: string
                    format: uid
                    description: The monitor's unique ID.
                    example: 12345678-1e6b6cc1-c760-48e0-968f-4bfaeeae9af1
          example:
            monitor:
              id: 1e6b6cc1-c760-48e0-968f-4bfaeeae9af1
              name: Test Monitor
              uid: 12345678-1e6b6cc1-c760-48e0-968f-4bfaeeae9af1
    runMonitor:
      description: Successful Response
      content:
        application/json:
          schema:
            type: object
            properties:
              run:
                type: object
                description: Information about the monitor run. If you pass the `async=true` query parameter, the response does not return the `stats`, `executions`, and `failures` responses. To get this information for an asynchronous run, call the GET `/monitors/{id}` endpoint.
                properties:
                  info:
                    type: object
                    description: Information about the monitor.
                    properties:
                      jobId:
                        type: string
                        description: The monitor's run job ID.
                        example: 1ecee76a-e14e-47c0-bddc-256bf690c407
                      collectionUid:
                        type: string
                        format: uid
                        description: The unique ID of the monitor's associated collection.
                        example: 12345678-12ece9e1-2abf-4edc-8e34-de66e74114d2
                      environmentUid:
                        type: string
                        format: uid
                        description: The unique ID of the monitor's associated environment.
                        example: 12345678-5daabc50-8451-43f6-922d-96b403b4f28e
                      monitorId:
                        type: string
                        description: The monitor's ID.
                        example: 1e6b6cc1-c760-48e0-968f-4bfaeeae9af1
                      name:
                        type: string
                        description: The monitor's name.
                        example: Test Monitor
                      status:
                        type: string
                        description: The monitor run's status.
                        example: success
                      startedAt:
                        type: string
                        format: date-time
                        description: The date and time at which the monitor run began.
                        example: '2022-06-17T19:50:04.019Z'
                      finishedAt:
                        type: string
                        format: date-time
                        description: The date and time at which the monitor's run completed.
                        example: '2022-06-17T19:50:06.439Z'
                  stats:
                    type: object
                    description: Information about the monitor run's stats.
                    properties:
                      assertions:
                        type: object
                        description: The monitor run's assertions stats.
                        properties:
                          total:
                            type: number
                            description: The total number of tests performed.
                            example: 0
                          failed:
                            type: number
                            description: The total number of test failures.
                            example: 0
                      requests:
                        type: object
                        description: The monitor run's request stats.
                        properties:
                          total:
                            type: number
                            description: The total number of requests.
                            example: 1
                          failed:
                            type: number
                            description: The number of request failures.
                            example: 0
                  executions:
                    type: array
                    description: Information about the monitor run's executions.
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                          description: The execution ID.
                          example: 1
                        item:
                          type: object
                          description: Information about the executed item.
                          properties:
                            name:
                              type: string
                              description: The executed item's name.
                              example: Sample POST Request
                        request:
                          type: object
                          description: Information about the monitor run's requests.
                          properties:
                            method:
                              type: string
                              description: The request method.
                              example: POST
                            url:
                              type: string
                              format: url
                              description: The request's URL.
                              example: http://echo.getpostman.com/post
                            body:
                              type: object
                              description: Information about the request body, such as Content-Length.
                              additionalProperties: true
                            headers:
                              type: object
                              description: Information about the request headers, such as Content-Type, Accept, encoding, and other information.
                              additionalProperties: true
                            timestamp:
                              type: string
                              description: The date and time of the request.
                              example: '2016-12-04T14:30:26.025Z'
                        response:
                          type: object
                          description: Information about the monitor run's response.
                          properties:
                            body:
                              type: object
                              description: Information about the request body, such as Content-Length.
                              additionalProperties: true
                            code:
                              type: number
                              description: The response's HTTP status code.
                              example: 200
                            headers:
                              type: object
                              description: Information about the response headers, such as Content-Type, Accept, encoding, and other information.
                              additionalProperties: true
                            responseSize:
                              type: number
                              description: The response size, in bytes.
                              example: 298
                            responseTime:
                              type: number
                              description: The response time, in milliseconds.
                              example: 26
                  failures:
                    type: array
                    description: If the monitor run failed, information about the run's failures.
                    items:
                      type: object
                    example: []
          examples:
            Successful Response:
              value:
                run:
                  info:
                    jobId: 1ecee76a-e14e-47c0-bddc-256bf690c407
                    monitorId: 1e6b6cc1-c760-48e0-968f-4bfaeeae9af1
                    name: Test Monitor
                    collectionUid: 12345678-12ece9e1-2abf-4edc-8e34-de66e74114d2
                    environmentUid: 12345678-5daabc50-8451-43f6-922d-96b403b4f28e
                    status: success
                    startedAt: '2022-06-17T19:50:04.019Z'
                    finishedAt: '2022-06-17T19:50:06.439Z'
                  stats:
                    assertions:
                      total: 0
                      failed: 0
                    requests:
                      total: 1
                      failed: 0
                  executions:
                  - id: 1
                    item:
                      name: Sample POST Request
                    request:
                      method: POST
                      url: http://echo.getpostman.com/post
                      headers:
                        Content-Type: application/json
                        User-Agent: PostmanRuntime/7.29.0
                        Accept: '*/*'
                        Cache-Control: no-cache
                        Postman-Token: null
                        Host: echo.getpostman.com
                        Accept-Encoding: gzip, deflate, br
                        Connection: keep-alive
                        Content-Length: '0'
                      body:
                        contentLength: 0
                      timestamp: '2022-06-17T19:50:06.186Z'
                    response:
                      code: 200
                      body:
                        contentLength: 50
                      responseTime: 49
                      responseSize: 50
                      headers:
                        Date: Fri, 17 Jun 2022 19:50:06 GMT
                        Content-Type: text/plain
                        Content-Length: '50'
                        Connection: keep-alive
                        Server: null
                  failures: []
            Run With async Parameter:
              value:
                run:
                  info:
                    jobId: 1ecee76a-e14e-47c0-bddc-256bf690c407
                    monitorId: 1e6b6cc1-c760-48e0-968f-4bfaeeae9af1
                    name: Test Monitor
                    collectionUid: 12345678-12ece9e1-2abf-4edc-8e34-de66e74114d2
                    environmentUid: 12345678-5daabc50-8451-43f6-922d-96b403b4f28e
                    status: success
                    startedAt: '2022-06-17T19:50:04.019Z'
                    finishedAt: '2022-06-17T19:50:06.439Z'
    instanceNotFoundMonitor:
      description: Instance Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  name:
                    type: string
                    description: The error name.
                    example: instanceNotFoundError
                  message:
                    type: string
                    description: The error message.
                    example: The specified monitor does not exist.
          example:
            error:
              name: instanceNotFoundError
              message: The specified monitor does not exist.
    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.
    deleteMonitor:
      description: Successful Response
      content:
        application/json:
          schema:
            type: object
            properties:
              monitor:
                type: object
                properties:
                 

# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/engineering-platform/refs/heads/main/openapi/engineering-platform-monitors-api-openapi.yml