Prometheus Metrics API

openapi: 3.1.0
info:
  title: Prometheus Alertmanager Admin Metrics API
  description: The Prometheus Alertmanager HTTP API v2 provides endpoints for querying active alert status, creating and managing silences, retrieving receiver configurations, and checking cluster peer status. Alertmanager deduplicates, groups, and routes alert notifications to receivers such as email, PagerDuty, Slack, and OpsGenie. The API base path is /api/v2.
  version: v0.28.0
  contact:
    name: Prometheus Project
    url: https://prometheus.io/community/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://{host}:{port}
  description: Alertmanager server
  variables:
    host:
      default: localhost
      description: Alertmanager server hostname
    port:
      default: '9093'
      description: Alertmanager server port
tags:
- name: Metrics
  description: Endpoints for pushing, replacing, and deleting metric groups. Metrics are grouped by job and optional additional labels.
paths:
  /metrics/job/{job}:
    put:
      operationId: replaceJobMetrics
      summary: Prometheus Replace all metrics for a job
      description: Replaces all metrics for the specified job with the metrics in the request body. The entire group of metrics for the job is atomically replaced. Use PUT when you want to fully overwrite the existing metric set for a job.
      tags:
      - Metrics
      parameters:
      - $ref: '#/components/parameters/Job'
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              description: Metrics in Prometheus text exposition format or OpenMetrics format.
              example: '# HELP batch_job_duration_seconds Duration of a batch job.

                # TYPE batch_job_duration_seconds gauge

                batch_job_duration_seconds 42.0

                '
          application/openmetrics-text:
            schema:
              type: string
              description: Metrics in OpenMetrics text format.
      responses:
        '200':
          description: Metrics replaced successfully
        '400':
          description: Bad request — invalid metric format or labels
    post:
      operationId: pushJobMetrics
      summary: Prometheus Add or update metrics for a job
      description: Adds new metrics for the specified job or updates existing metrics. Unlike PUT, POST only updates the metrics that are present in the request body while leaving other metrics in the group untouched.
      tags:
      - Metrics
      parameters:
      - $ref: '#/components/parameters/Job'
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              description: Metrics in Prometheus text exposition format.
          application/openmetrics-text:
            schema:
              type: string
              description: Metrics in OpenMetrics text format.
      responses:
        '200':
          description: Metrics added or updated successfully
        '400':
          description: Bad request — invalid metric format or labels
    delete:
      operationId: deleteJobMetrics
      summary: Prometheus Delete all metrics for a job
      description: Deletes all metrics for the specified job from the Pushgateway. After deletion, Prometheus will no longer scrape any metrics for this job label combination.
      tags:
      - Metrics
      parameters:
      - $ref: '#/components/parameters/Job'
      responses:
        '202':
          description: Metrics deletion accepted
        '400':
          description: Bad request — invalid job label value
  /metrics/job/{job}/{labels}:
    put:
      operationId: replaceGroupedMetrics
      summary: Prometheus Replace metrics for a job with grouping labels
      description: Replaces all metrics for the specified job and grouping label combination. Grouping labels are additional key-value pairs appended to the path as alternating label name and value segments (e.g., /metrics/job/myjob/instance/myinstance).
      tags:
      - Metrics
      parameters:
      - $ref: '#/components/parameters/Job'
      - $ref: '#/components/parameters/Labels'
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              description: Metrics in Prometheus text exposition format.
          application/openmetrics-text:
            schema:
              type: string
              description: Metrics in OpenMetrics text format.
      responses:
        '200':
          description: Metrics replaced successfully
        '400':
          description: Bad request — invalid metric format or label names
    post:
      operationId: pushGroupedMetrics
      summary: Prometheus Add or update metrics for a job with grouping labels
      description: Adds or updates metrics for the specified job and grouping label combination. Only metrics included in the request body are changed; other metrics in the group are preserved.
      tags:
      - Metrics
      parameters:
      - $ref: '#/components/parameters/Job'
      - $ref: '#/components/parameters/Labels'
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              description: Metrics in Prometheus text exposition format.
      responses:
        '200':
          description: Metrics added or updated successfully
        '400':
          description: Bad request
    delete:
      operationId: deleteGroupedMetrics
      summary: Prometheus Delete metrics for a job with grouping labels
      description: Deletes all metrics for the specified job and grouping label combination. Only metrics with the exact label set specified in the path are deleted.
      tags:
      - Metrics
      parameters:
      - $ref: '#/components/parameters/Job'
      - $ref: '#/components/parameters/Labels'
      responses:
        '202':
          description: Metrics deletion accepted
        '400':
          description: Bad request
  /api/v1/metrics:
    get:
      operationId: listAllMetrics
      summary: Prometheus List all pushed metrics
      description: Returns all currently stored metric families in JSON format, grouped by job and grouping labels. This endpoint provides a structured view of all metrics available for Prometheus to scrape.
      tags:
      - Metrics
      responses:
        '200':
          description: All pushed metrics returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsResponse'
components:
  schemas:
    MetricsResponse:
      type: object
      description: All currently stored metric groups in the Pushgateway.
      properties:
        status:
          type: string
          enum:
          - success
          - error
        data:
          type: array
          items:
            $ref: '#/components/schemas/MetricGroup'
    MetricGroup:
      type: object
      description: A group of metrics sharing the same job and grouping labels.
      properties:
        labels:
          type: object
          additionalProperties:
            type: string
          description: The grouping labels for this metric group including job.
        lastPushedAt:
          type: string
          format: date-time
          description: Timestamp of the last push to this group.
        metricFamilies:
          type: object
          description: Map of metric family names to their metric family objects.
          additionalProperties:
            $ref: '#/components/schemas/MetricFamily'
    MetricFamily:
      type: object
      description: A family of metrics with the same name.
      properties:
        name:
          type: string
          description: Metric family name.
        help:
          type: string
          description: Help text describing the metric.
        type:
          type: string
          enum:
          - COUNTER
          - GAUGE
          - SUMMARY
          - HISTOGRAM
          - UNTYPED
          description: Metric type.
        metric:
          type: array
          items:
            $ref: '#/components/schemas/Metric'
          description: Individual metric instances in this family.
    Metric:
      type: object
      description: An individual metric with labels and value.
      properties:
        label:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Label name.
              value:
                type: string
                description: Label value.
          description: Labels attached to this metric.
        gauge:
          type: object
          properties:
            value:
              type: number
              description: Gauge value.
        counter:
          type: object
          properties:
            value:
              type: number
              description: Counter value.
        timestampMs:
          type: integer
          description: Metric timestamp in milliseconds.
  parameters:
    Labels:
      name: labels
      in: path
      required: true
      description: Additional grouping labels as alternating label-name/label-value path segments (e.g., instance/host1/datacenter/eu).
      schema:
        type: string
        example: instance/server01
    Job:
      name: job
      in: path
      required: true
      description: The job label value for this metric group. This is the primary grouping key for pushed metrics.
      schema:
        type: string
        example: batch-importer
externalDocs:
  description: Alertmanager Documentation
  url: https://prometheus.io/docs/alerting/latest/alertmanager/