HookPulse S API

openapi: 3.2.0
info:
  title: HookPulse S API
  version: 2d690e87
  description: 'Dead-man switch for webhooks/cron. Index: GET /api/.'
servers:
- url: https://hookpulse.net
tags:
- name: S
paths:
  /s/{token}.json:
    get:
      operationId: get_s_by_token_json
      summary: The status dashboard as JSON, with no header at all — the token in the path is…
      description: '`summary.all_ok` is the field for an external monitor to check without understanding the rest. The `id` of each row is a label of this dashboard, not the ingest id — rotating the feed changes both.

        Returns: { generated_at, summary{total,ok,overdue,waiting_first_ping,inactive,all_ok}, endpoints[{id,name,status,healthy,overdue,interval_sec,last_event_at,miss_count,alerts}], _links }'
      security: []
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ generated_at, summary{total,ok,overdue,waiting_first_ping,inactive,all_ok}, endpoints[{id,name,status,healthy,overdue,interval_sec,last_event_at,miss_count,alerts}], _links }'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedStatus'
        '404':
          description: Unknown feed token.
      tags:
      - S
  /s/{token}.rss:
    get:
      operationId: get_s_by_token_rss
      summary: The same dashboard as RSS 2.0, for a feed reader, a chat bot or a status page
      description: 'The `guid` of each item changes when the STATE changes, not on every generation — with a fixed guid the reader would never re-notify.

        Returns: `application/rss+xml` — one item per monitor, with the state in the title.'
      security: []
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '`application/rss+xml` — one item per monitor, with the state in the title.'
        '404':
          description: Unknown feed token.
      tags:
      - S
components:
  schemas:
    FeedStatus:
      type: object
      properties:
        generated_at:
          type: string
          description: When this dashboard was built (UTC).
        summary:
          allOf:
          - $ref: '#/components/schemas/ResumoStatus'
          description: The number you look at first.
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/LinhaStatus'
          description: One row per monitor, with no secret at all.
        _links:
          type: object
          description: This dashboard as JSON, as RSS and the API index.
      required:
      - generated_at
      - summary
      - endpoints
      - _links
      description: The owner's whole status dashboard, addressable by URL. The token in the path IS the credential — whoever has the link, reads.
    ResumoStatus:
      type: object
      properties:
        total:
          type: integer
          description: Monitors on the dashboard.
        ok:
          type: integer
          description: Active and healthy.
        overdue:
          type: integer
          description: Active and silent beyond the interval.
        waiting_first_ping:
          type: integer
          description: Active ones that never pinged.
        inactive:
          type: integer
          description: Deactivated.
        all_ok:
          type: boolean
          description: '`true` only with at least one monitor, none overdue and none waiting for the first ping — one that never pinged does not count as healthy.'
      required:
      - total
      - ok
      - overdue
      - waiting_first_ping
      - inactive
      - all_ok
      description: The set in numbers. `all_ok` is the field for an external monitor to check without understanding the rest.
    LinhaStatus:
      type: object
      properties:
        id:
          type: string
          description: 'Stable label of THIS dashboard, derived from the pair (feed token, monitor) — it is not the ingest id, and it changes when the owner rotates the token. The real id does not leave here because `GET /in/:id` asks for no credential: publishing it would give whoever only reads the power to reset the silence counter.'
        name:
          type: string
          description: Name given by the owner.
        status:
          type: string
          description: State in one word.
        healthy:
          type: boolean
          description: Whether it is healthy now.
        overdue:
          type: boolean
          description: Whether it is silent beyond the interval.
        interval_sec:
          type: integer
          description: Tolerated silence, in seconds.
        last_event_at:
          type: string
          description: Last ping (UTC).
          nullable: true
        miss_count:
          type: integer
          description: How many misses have happened.
        alerts:
          type: object
          description: 'Which alert channels are on: `{ email, url }` — booleans, never the address.'
      required:
      - id
      - name
      - status
      - healthy
      - overdue
      - interval_sec
      - last_event_at
      - miss_count
      - alerts
      description: 'A monitor on the public dashboard: enough to know the state, with no token, no e-mail and no ingest id.'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Guest token (`POST /api/guest`) in `X-Guest-Token: hp_…` or `Authorization: Bearer hp_…`. A `sess_…` session also works.'