Skip to content

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.

id
required
string format: uuid

Done. The body gives how many rows were cancelled, which can be 0.

object
peer_id
required

The id from the request path, returned as given.

string format: uuid
cancelled_count
required

How many rows this call changed from queued to cancelled.

integer

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Not returned as shipped: an unknown peer gets 200 with a count of 0.

object
error
required

Human-readable error summary

string
Example
the request could not be completed