hubbub

POST /v1/notify bearer key required

Send a notification to the caller's channels.

Enqueues the notification for every target channel, waits out the server's response window, and reports what is known by then: attempts that finished are reported concretely, anything still in flight as queued.

Request body

Try it

Responses

• 200 Delivered: every target channel completed successfully inside the response window.
  example body

  {
    "channels": {
      "ntfy": "ok"
    },
    "requestId": "r_cc519c9a3ee79f270c4e9823cd56f2f3",
    "result": "delivered"
  }

• 202 Queued: nothing finished inside the response window. The message is durably spooled and will be retried; the outcome lands in the delivery log under this requestId.
  example body

  {
    "channels": {
      "ntfy": "queued"
    },
    "requestId": "r_cc519c9a3ee79f270c4e9823cd56f2f3",
    "result": "queued"
  }

• 207 Partial: channels disagreed — some combination of delivered, queued, failed or disabled. Inspect channels per id.
  example body

  {
    "channels": {
      "ntfy": "ok",
      "parked": "disabled"
    },
    "requestId": "r_cc519c9a3ee79f270c4e9823cd56f2f3",
    "result": "partial"
  }

• 400 Malformed request: bad JSON, an unknown field, an unparseable priority, an over-length body, or "channels": [] (omit the field instead — an empty list is a caller that computed no targets, and must not fan out to everything).
• 401 Missing or unknown bearer key.
• 403 The request named a channel this key is not permitted to use. A channel the key is permitted but which is currently disabled is not a 403 — it comes back as a per-channel disabled result.
• 429 Global rate cap reached. Not a 202: a cap has to look like an error so standard retry machinery honours it rather than reading it as success.
• 502 Every target channel failed permanently.

Response body

GET /docs no auth

Browsable API reference.

This document rendered as a page, with a panel for firing a real request against this hub. Generated from the spec on every load rather than maintained beside it, so it cannot describe an endpoint that isn't here.

Try it

Responses

• 200 The reference page.

GET /health no auth

Liveness.

200 if the process is serving. Liveness only — no outbound probes and no channel state, so a healthy response says nothing about whether deliveries are succeeding.

Try it

Responses

• 200 The process is up.
  example body

  {
    "status": "ok",
    "uptime": "3h14m0s",
    "version": "0.1.0"
  }

Response body

GET /llms.txt no auth

This contract, condensed, as markdown.

The llms.txt convention (llmstxt.org): what this hub is and how to call it, written for an agent that was handed the host and nothing else. Unauthenticated, and a strict subset of this document — read the spec instead if you can parse it.

Try it

Responses

• 200 Markdown, served as text/plain so it renders wherever it is fetched.

GET /openapi.json no auth

This document.

Unauthenticated by design: it exposes the API's shape, which is not a secret, so an agent can be pointed at the base URL and discover the contract before it holds a key. The channels enum and the server URL reflect this deployment.

Try it

Responses

• 200 The OpenAPI document.

GET /v1/recent bearer key required

Recent deliveries, newest first.

A read of the hub's delivery log: what came in, which channel it went to and how it ended up. One item per notification per channel — a fan-out to two channels is two items sharing a requestId. Outcomes are reported as settled as the log knows them, so a notification that answered 202 queued appears here with whatever its delivery eventually was. *Admin-scoped, and holding a valid key is not enough.* The log carries every caller's titles and caller ids, so reading it takes a key granted recent = true in keys.toml — or, from a browser, an operator identity this hub's admin allowlist permits. A key that can only send gets a 403. Every read, refused or served, is recorded in the log it reads. *To poll: send since set to the newest ts you already hold, and check truncated — when it is true the answer was cut to limit and the oldest* matching rows were dropped, so raise limit and ask again before advancing your cursor. An item resurfaces if its outcome settles after you last saw it, keeping its original ts and gaining a settledAt. The read covers the tail of the log, not its whole history; older entries stay in the file for grep. Unknown query parameters are rejected rather than ignored, so a misspelled filter cannot silently return everything.

Query parameters

Try it

Responses

• 200 The matching deliveries. An empty log is a 200 with items: [], never a 404.
  example body

  {
    "count": 2,
    "items": [
      {
        "caller": "cron",
        "channel": "ntfy",
        "outcome": "ok",
        "priority": "high",
        "requestId": "r_cc519c9a3ee79f270c4e9823cd56f2f3",
        "settledAt": "",
        "title": "Backup failed",
        "ts": "2026-08-08T09:31:02.418Z"
      },
      {
        "caller": "cron",
        "channel": "email",
        "outcome": "failed: smtp: 550 mailbox unavailable",
        "priority": "high",
        "requestId": "r_cc519c9a3ee79f270c4e9823cd56f2f3",
        "settledAt": "2026-08-08T09:33:44.902Z",
        "title": "Backup failed",
        "ts": "2026-08-08T09:31:02.418Z"
      }
    ],
    "truncated": false
  }

• 400 An unknown query parameter, an unparseable since, or a limit outside 1–500.
• 401 Missing or unknown bearer key, and no permitted admin identity on the request.
• 403 The key is valid but not granted delivery-log access. Sending and reading are separate permissions on purpose: a send key that leaks must not also expose every other caller's notifications.
• 500 The delivery log could not be read.

Response body

GET / no auth

Human-readable landing page.

A short HTML page for a person who opened the base URL: what this is, one copy-pasteable request, and the response contract. Also served at /index.html. It documents the API and never the deployment behind it, so it names no channel, caller or ops endpoint.

Try it

Responses

• 200 The landing page.