Skip to content

List the federation inbox

GET
/admin/federation/inbox

Lists federation activities that other instances delivered to yours, newest first, with what your instance did with each one.

A row starts pending and the inbox dispatcher then marks it processed, rejected (with a reject_reason) or failed. processed doesn’t mean anything changed: only likes and comments are applied today, and every other type, aa:Share included, is marked processed without being acted on.

Only deliveries that passed the inbox’s checks are stored. One refused on arrival, for example for a bad signature, an unknown or disconnected peer, or an object that isn’t on your instance, never gets a row; most such refusals are recorded in the audit log as federation.activity.rejected, and the sending instance’s outbox usually shows them as failed.

Inbox rows can’t be retried. A sender that delivers the same activity again gets an OK, and the existing row is left as it was, so a failed row isn’t run again.

Filters combine, and since is a lower bound on when a row was received. Paging and limit work as in GET /admin/federation/outbox.

As shipped, this endpoint doesn’t check who is calling: any request that reaches the API gets the list, whether or not it’s signed in.

peer_id
string format: uuid
status
string
Allowed values: pending processed rejected failed
activity_type
string
since
string format: date-time
limit
integer
default: 100 >= 1 <= 500
cursor
string

Inbox rows matching the filter.

object
items
required
Array<object>

One activity a peer delivered to your inbox, and how your instance handled it. Delivering the same activity again doesn’t add a row or change this one.

object
id
required
string format: uuid
activity_uri
required

The activity’s ID. Each one appears in the inbox once.

string
peer_id
required
string format: uuid
actor_uri
required

The user on the peer the activity says sent it. That user’s own signature isn’t verified yet; only the instance’s HTTP signature is.

string
activity_type
required

The activity’s type, such as Like, Create or aa:Share.

string
object_kind

The kind of object on your instance the activity is about. Left out when it doesn’t name one.

string
nullable
object_id
string format: uuid
nullable
http_sig_key

The key ID of the delivery’s HTTP signature, which was checked against the key saved for the peer.

string
status
required
string
Allowed values: pending processed rejected failed
reject_reason

Why the row was rejected, as one of the protocol’s reject reasons, such as unknown_object or encryption_required. Set only when status is rejected.

string
nullable
dispatch_attempts
required

How many times the dispatcher has tried to handle the row, the last try included. A row is marked failed after five tries that fail, or at once if it can’t be handled at all.

integer
last_attempt_at
string format: date-time
nullable
last_error

What went wrong on the last try. Cleared when the row is processed.

string
nullable
received_at
required
string format: date-time
processed_at
string format: date-time
nullable
correlation_activity_id

Meant to link the local activity created when this was applied. Nothing sets it yet, so it’s always left out.

string format: uuid
nullable
next_cursor

Pass this as cursor to get the next page. It’s included whenever the page is full.

string
nullable

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

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