Instance Messaging Extension • Versia API Reference

This extension lets instances send each other simple federation debug messages. It is not intended for general-purpose messaging.

The name of this extension is pub.versia:instance_messaging. Instances that support it list this name in compatibility.extensions of their InstanceMetadata.

Federation often fails silently. For example, if joe.example cannot process a User fetched from jane.example because of an invalid username, jane.example has no way of knowing what went wrong.

Behavior

To send a federation debug message, instances SHOULD make a POST request to the /.versia/v0.7/extensions/pub.versia:instance_messaging/messaging endpoint with a text body. The body SHOULD name the sending instance and what failed, as nothing else in the request identifies the sender.

The request has a Content-Type of text/plain, and needs no Accept. No signatures are required (either on the request or response), so that a message can still arrive when signing is what is broken. No response body is expected.

A receiver MUST treat the sender as unverified and the text as untrusted. It MAY answer 429 Too Many Requests, or 413 Content Too Large for a message it finds too long.

From joe.example: validation failed for https://jane.example/.versia/v0.7/entities/User/nkGEd8eI98.
Reasons:
    - `username` contains the invalid character `@`.

A message like this one does not help:

Federation failed.