Endpoints

Versia defines an API for server-to-server communication, mainly fetching and sending entities. It is namespaced and versioned, to avoid confusion with implementations’ existing HTTP APIs.

Well-known

GET /.well-known/versia HTTP/1.1
Host: b.example
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
    "versions": [
        "0.7.0",
        "0.6.0"
    ]
}

Instance Metadata

GET /.versia/v0.7/instance HTTP/1.1
Host: b.example
Accept: application/vnd.versia+json

HTTP/1.1 200 OK
Content-Type: application/vnd.versia+json

{
    "type": "InstanceMetadata",
    "name": "Bob!!",
    // ...
}

Entity Data

GET /.versia/v0.7/entities/User/1234 HTTP/1.1
Host: b.example
Accept: application/vnd.versia+json

HTTP/1.1 200 OK
Content-Type: application/vnd.versia+json

{
    "type": "User",
    "id": "1234",
    // ...
}

Entity Collections

GET /.versia/v0.7/entities/User/1234/collections/subscribers HTTP/1.1
Host: b.example
Accept: application/vnd.versia+json

HTTP/1.1 200 OK
Content-Type: application/vnd.versia+json

{
    "total": 2,
    "items": [
        "a.example:0350q3easp004",
        "c.example:03441phjap000"
    ]
}

Pagination

Collections MUST support pagination, using the following URI parameters:

• offset: The number of items to skip before returning the first item. Defaults to 0.
• limit: The maximum number of items to return, from 1 to 40. Defaults to 40. Any other whole number MUST be clamped to that range.

A value that is not a whole number, or a negative offset, MUST be rejected with a 422 Unprocessable Entity status code. An offset past the end returns empty items and the true total.

Items MUST be in a stable order, oldest first, so that new items do not shift earlier pages. Removing an item can still shift later ones, so a request walking through a collection may see an item twice or miss one.

A collection lists only the items the requesting instance may fetch.

GET /.versia/v0.7/entities/User/1234/collections/subscribers?offset=10&limit=20 HTTP/1.1
Host: b.example
Accept: application/vnd.versia+json

Instance Collections

Instance Metadata has no ID, so its collections have their own path. They paginate like any other collection.

GET /.versia/v0.7/instance/collections/admins HTTP/1.1
Host: b.example
Accept: application/vnd.versia+json

HTTP/1.1 200 OK
Content-Type: application/vnd.versia+json

{
    "total": 2,
    "items": [
        // ...
    ]
}

Inbox

The inbox receives entities from other instances, for every user on the instance (also known as a shared inbox). See Inboxes for how delivery works.

POST /.versia/v0.7/inbox HTTP/1.1
Host: b.example
Content-Type: application/vnd.versia+json

{
    "type": "pub.versia:social/Note",
    "id": "1234",
    // ...
}