The operator events API is undocumented: absent from both public API specs and from the docs

[leggetter]

What

Operator events are configurable over the public API. The routes live on the Outpost API host and authenticate with the Outpost API key:

GET    /operator-events/destination-types
GET    /operator-events/destinations
POST   /operator-events/destinations
GET    /operator-events/destinations/{id}
PATCH  /operator-events/destinations/{id}
DELETE /operator-events/destinations/{id}
PUT    /operator-events/destinations/{id}/enable
PUT    /operator-events/destinations/{id}/disable
GET    /operator-events/events
GET    /operator-events/events/{id}
GET    /operator-events/events/{id}/attempts
GET    /operator-events/attempts
GET    /operator-events/attempts/{id}
POST   /operator-events/retry

Verified live: destination-types, events and attempts each answer 200 with the usual { models, pagination } shape.

None of this appears in any public specification or documentation.

Where someone would look, and what they find

• The operator events docs page tells managed users to configure it through the dashboard, and says topics are set "through Hookdeck Monitoring settings or Config API". No mention of these routes.
• The Config API rejects the keys with 422 "OPERATOR_EVENTS_TOPICS is managed by your operator event destinations and cannot be set directly." It names the owning resource but not where to find it.
• Hookdeck's live OpenAPI (GET /2025-07-01/openapi, 89 paths): absent.
• Outpost's docs/apis/openapi.yaml: absent. Its ManagedConfig also omits the OPERATOR_EVENTS_* keys that the live API returns.

Why it matters

Alerting is the part of an integration that has to be reproducible: version-controlled, repeatable across environments, and settable by a setup script or a Terraform provider. The capability is there — it is just not findable by anyone who does not already know the path.

For agents this is decisive. An agent has no source of truth other than the docs and the spec, so a working endpoint that appears in neither may as well not exist. That is not hypothetical: this endpoint was searched for across both specs, ten guessed path names, and four version prefixes before being found. The one probe that did hit the real route returned 404 "tenant not found" — because the tenant is created lazily on first POST — which reads like a missing route rather than an empty resource.

Suggested

1. Add the operator events routes to the public OpenAPI spec.
2. Document them on the operator events page, next to the dashboard instructions.
3. Consider whether GET /operator-events/destinations should answer an empty list rather than 404 "tenant not found" before the first destination exists. As it stands, the first call anyone makes against a fresh project looks like a 404 for the route itself.

Related: #32 — every env var name on that same docs page is wrong.

[leggetter]

Checked the canonical API reference as well: https://hookdeck.com/docs/outpost/api renders the spec inline (~9.2 MB) and contains zero occurrences of operator-events in any form. It does carry /tenants, /publish, /retry and the tenant destination-types endpoint, so the page itself is complete with respect to its source.

That source is docs/apis/openapi.yaml — the same file the routes are missing from. So the reference page, the OpenAPI file and the absence from Hookdeck's spec are one gap rather than three: adding the routes to that spec fixes the published reference at the same time.

The only public mention of operator events remains the prose feature page, which tells managed users to configure them in the dashboard.