Cancel queued deliveries to a peer
POST /admin/federation/peers/{id}/cancel-pending
Cancels the deliveries still waiting in the outbox for one peer:
every queued row for it becomes cancelled. It doesn’t cancel a
pairing request, change the peer or touch anything already sent.
Each cancelled row gets last_error set to peer defederation cascade; rows in any other state stay as they are. Cancelled rows
can’t be retried, because POST /admin/federation/outbox/{id}/requeue takes only failed ones. The
peer isn’t looked up, so an unknown id also gets 200, with a count
of 0.
This doesn’t stop new deliveries: the call doesn’t disable the peer
or change its enabled setting, so if the peer is enabled, new
activity can be queued for it straight away. A delivery the worker
has already picked up can still reach the peer even though its row
now says cancelled. To stop traffic, disable the peer first with
PATCH /admin/federation/peers/{id} ("enabled": false). Nothing
already delivered is recalled.
After the change, the server tries to record a
federation.peer.cascade_cancelled audit event with the count; if
that fails, the failure is only logged and the cancellation still
stands. As shipped, this endpoint checks only that you’re signed in:
any signed-in user can cancel any peer’s queued deliveries.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Responses
Section titled “ Responses ”Done. The body gives how many rows were cancelled, which can be 0.
object
The id from the request path, returned as given.
How many rows this call changed from queued to cancelled.
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedNot returned as shipped: an unknown peer gets 200 with a count of 0.
object
Human-readable error summary
Example
the request could not be completed