agentry-com Observability API

openapi: 3.2.0
info:
  title: Agentry Observability API
  description: AI Agent Registry and Discovery service — browse, search, and register AI agents. Machine-readable via /llms.txt, /.well-known/agents.json, and /api/agents/public (A2A).
  version: 0.4.0
tags:
- name: observability
paths:
  /api/observability/ping/{agent_id}:
    post:
      tags:
      - observability
      summary: Record Ping
      description: 'Record an uptime check result for an agent.


        Called by external monitors or peer agents after probing the target

        agent''s A2A endpoint (or any configured health URL). Persists the

        ping record and immediately fires two reputation events:


        - ``uptime_check`` with value 1.0 (up) or 0.0 (down) → *reliability* dimension

        - ``response_latency`` with value = latency_ms → *performance* dimension (if available)


        These reputation signals ensure that the reputation score reflects

        real observed behaviour, not just self-reported metadata.'
      operationId: record_ping_api_observability_ping__agent_id__post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PingResultRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Record Ping Api Observability Ping  Agent Id  Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/observability/status/{agent_id}:
    get:
      tags:
      - observability
      summary: Get Agent Status
      description: 'Get the current status and uptime percentages for an agent.


        Returns:

        - ``current_status``: the result of the most recent ping (''up'', ''down'', or ''unknown'')

        - ``uptime_24h``, ``uptime_7d``, ``uptime_30d``: availability percentages over each window

        - ``last_checked_at``: timestamp of the most recent ping

        - ``total_checks``: all-time ping count


        The uptime percentages are computed from raw ping history, so they

        always reflect the full recorded window rather than a pre-aggregated

        number that could drift from the underlying data.'
      operationId: get_agent_status_api_observability_status__agent_id__get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Agent Status Api Observability Status  Agent Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/observability/latency/{agent_id}:
    get:
      tags:
      - observability
      summary: Get Latency Stats
      description: 'Get latency statistics for an agent over the last 24 hours.


        Computes p50, p95, and p99 latency percentiles along with the

        simple arithmetic mean for the 24-hour window. Only pings with a

        recorded ``latency_ms`` value are included.


        These stats help consumers evaluate whether an agent meets their

        SLA requirements before initiating a transaction, and feed into

        the *performance* dimension of the reputation engine.'
      operationId: get_latency_stats_api_observability_latency__agent_id__get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Latency Stats Api Observability Latency  Agent Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/observability/history/{agent_id}:
    get:
      tags:
      - observability
      summary: Get Ping History
      description: 'Return historical ping records for an agent, newest first.


        Supports optional filtering by status (''up'' or ''down'') to quickly

        identify all outage windows or all successful checks. Limited to

        the last ``limit`` results (max 500) to keep response sizes manageable.


        Consumers can use this data to build custom uptime charts or audit

        the monitoring coverage frequency for a given agent.'
      operationId: get_ping_history_api_observability_history__agent_id__get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          description: Number of most recent pings to return.
          default: 100
          title: Limit
        description: Number of most recent pings to return.
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Optional filter: ''up'' or ''down''.'
          title: Status
        description: 'Optional filter: ''up'' or ''down''.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Ping History Api Observability History  Agent Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/observability/anomalies/{agent_id}:
    get:
      tags:
      - observability
      summary: Get Anomalies
      description: 'Detect and return anomalies in an agent''s monitoring data.


        Runs two anomaly detection algorithms against the stored ping history:


        1. **Consecutive downtime** — raises *critical* (5+ pings) or *high*

        (3–4 pings) severity if the most recent N pings are all ''down''.

        This pattern strongly suggests a real outage rather than a fluke.


        2. **Latency spike** — raises *medium* severity if the latest latency

        reading exceeds 3× the 24-hour average. A single spike may be

        noise, but combined with the reputation latency trend it indicates

        degraded performance.


        Returns an empty ``anomalies`` list when the agent appears healthy,

        so callers can use a simple ``if anomalies`` check.'
      operationId: get_anomalies_api_observability_anomalies__agent_id__get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Anomalies Api Observability Anomalies  Agent Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/observability/dashboard:
    get:
      tags:
      - observability
      summary: Observability Dashboard
      description: 'Platform-wide health overview for operator dashboards.


        Aggregates across all monitored agents to surface:

        - ``total_monitored``: agents that have at least one ping record

        - ``agents_up``, ``agents_down``: counts based on most recent ping

        - ``agents_unknown``: agents with no pings in the last 24 hours

        - ``avg_uptime_24h``: mean uptime percentage across all monitored agents

        - ``p95_latency_ms``: platform-wide p95 latency over the last 24 hours

        - ``agents_with_anomalies``: count of agents currently showing anomalies


        This endpoint intentionally returns aggregate data only — individual

        agent details require the per-agent endpoints above.'
      operationId: observability_dashboard_api_observability_dashboard_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Observability Dashboard Api Observability Dashboard Get
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PingResultRequest:
      properties:
        status:
          type: string
          title: Status
          description: 'Result of the check: ''up'' if the agent responded successfully, ''down'' otherwise.'
        latency_ms:
          anyOf:
          - type: number
            minimum: 0.0
          - type: 'null'
          title: Latency Ms
          description: Round-trip latency in milliseconds. Should be omitted or null when status is 'down' and no connection could be established.
        checked_by:
          type: string
          title: Checked By
          description: Identifier of the entity performing the check — 'system' for the platform monitor, or an agent_id for peer-to-peer health checks.
          default: system
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if status is 'down', e.g., timeout, connection refused.
        endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Endpoint
          description: Specific endpoint or URL that was probed, if relevant.
      type: object
      required:
      - status
      title: PingResultRequest
      description: Payload submitted by a monitor to record a single uptime check.