openapi: "3.0.3"

info:
  title: SentryAgent.ai — Prometheus Metrics Endpoint
  version: 1.0.0
  description: |
    Internal Prometheus metrics endpoint for the SentryAgent.ai AgentIdP platform.

    This endpoint returns metrics in **Prometheus text exposition format** (v0.0.4).
    It is intended exclusively for internal Prometheus scraping.

    **Security notice:** This endpoint is **unauthenticated** and MUST NOT be
    exposed on a public-facing network interface. Restrict access via network
    policy, firewall rules, or a reverse-proxy that only allows Prometheus
    scraper IP ranges to reach `/metrics`.

    Metrics exported include:
    - HTTP request counts and latencies (by route and status code)
    - Token issuance, introspection, and revocation counters
    - Agent registration and decommission counters
    - Active registered agent gauge
    - Database connection pool metrics
    - Process memory and CPU metrics (via `prom-client` defaults)

servers:
  - url: http://localhost:3000
    description: Local development server (internal only)
  - url: https://api.sentryagent.ai
    description: Production server (restrict to Prometheus scraper)

tags:
  - name: Metrics
    description: Prometheus metrics scrape endpoint

components:
  schemas:
    PrometheusMetrics:
      type: string
      description: |
        Metrics in Prometheus text exposition format (v0.0.4).
        Each metric family is preceded by `# HELP` and `# TYPE` comment lines.
      example: |
        # HELP process_cpu_user_seconds_total Total user CPU time spent in seconds.
        # TYPE process_cpu_user_seconds_total counter
        process_cpu_user_seconds_total 0.123456
        # HELP http_requests_total Total number of HTTP requests.
        # TYPE http_requests_total counter
        http_requests_total{method="POST",route="/api/v1/token",status_code="200"} 4201
        http_requests_total{method="GET",route="/api/v1/agents",status_code="200"} 987

    ErrorResponse:
      type: object
      description: Standard error response envelope.
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: "INTERNAL_SERVER_ERROR"
        message:
          type: string
          example: "An unexpected error occurred. Please try again later."

paths:
  /metrics:
    get:
      operationId: scrapeMetrics
      tags:
        - Metrics
      summary: Prometheus metrics scrape endpoint
      description: |
        Returns all registered metrics in Prometheus text exposition format.

        The `Content-Type` header in the response is set to the value reported
        by the `prom-client` registry (`text/plain; version=0.0.4; charset=utf-8`).

        This endpoint is **unauthenticated** and is intended for internal
        Prometheus scraping only. Do not expose on public interfaces.
      security: []
      responses:
        '200':
          description: Metrics in Prometheus text exposition format.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/PrometheusMetrics'
              example: |
                # HELP process_cpu_user_seconds_total Total user CPU time spent in seconds.
                # TYPE process_cpu_user_seconds_total counter
                process_cpu_user_seconds_total 0.123456
                # HELP sentryagent_tokens_issued_total Total tokens issued.
                # TYPE sentryagent_tokens_issued_total counter
                sentryagent_tokens_issued_total 4201
                # HELP sentryagent_agents_registered_total Total agents registered.
                # TYPE sentryagent_agents_registered_total counter
                sentryagent_agents_registered_total 120
        '500':
          description: Unexpected error while collecting metrics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: INTERNAL_SERVER_ERROR
                message: "An unexpected error occurred. Please try again later."