Add to an endpoint's scope without re-vending it (additive only)
POST/api/v1/endpoints/:ref/scope/widen
Widens the grant of an active endpoint you own by adding to it: queues its webhooks may route to, ingest source types its agents may create webhooks for, MCP verbs, and a larger ceiling on self-managed webhooks (ADR-0049). It exists because a webhook belongs to the endpoint that created it, so a re-vend to add one route would mint a new ingest URL and signing secret and need an edit in the producer's hook configuration — for a change that cannot break a route that works today.
The request can only add. Arrays are unioned, so a removal has no spelling here, and any key other
than the five below — including a bare webhook_queues, which would be a replacement — is refused
with 400. webhook_max is a ceiling to raise: a value below the endpoint's current one is refused,
never clamped, because lowering it strands webhooks that already exist.
Without confirm: true this is a preview: the response reports before, after, the fields
that would move and requires_confirmation: true, and nothing is written. The endpoint's
credential is never read or changed — the token revealed at vend keeps working, which is the point.
Draws from the per-human write bucket (429 with Retry-After when spent). Every field that
actually moves is recorded in endpoint_scope_widenings in the same transaction as the change.
Request
Responses
- 200
- 400
- 401
- 404
- 409
- 413
- 429
The before and after scope; applied says whether the widen was written.
invalid_argument: an unknown or removal key, an empty addition, an unknown queue, source type or verb, a webhook_max that lowers the ceiling, or a body that does not decode.
Missing, expired, revoked, or non-operator bearer.
not_found: no endpoint by that slug or id belongs to the caller (unknown and another human's are the same answer).
conflict: the endpoint is revoked; state says so.
The body is over 64 KiB.
rate_limited: the per-human write bucket is spent.