Endpoints

Well-known

This endpoint is exempt from the signature requirement. No signatures are required for requests or responses to it.

The following Accept headers are also allowed for requests to this endpoint:

application/jrd+json
application/json

Name
endpoint
Description
Must be /.well-known/versia.
Name
method
Description
Must be GET.
Name
response
Description
A small JSON object with a single attribute:
- versions: Supported Versia Protocol versions.
  - Versions marked as "Working Draft X" are represented as 0.X.

Example request

GET /.well-known/versia
Host: b.social
Accept: application/jrd+json

Example response

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

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

Instance metadata

This endpoint is exempt from the signature requirement. No signatures are required for requests or responses to it.

Name
endpoint
Description
Must be /.versia/v0.6/instance.
Name
method
Description
Must be GET.
Name
response
Description
Instance's metadata, as defined in the Instance Metadata document.

Example request

GET /.versia/v0.6/instance
Host: b.social
Accept: application/vnd.versia+json

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.versia+json; charset=utf-8

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

Entity data

Name
endpoint
Description
Must be /.versia/v0.6/entities/{entity_type}/{id}.
- {entity_type}: The type of the entity to fetch, URL-encoded.
- {id}: The ID of the entity to fetch, URL-encoded.
Example: GET /.versia/v0.6/entities/pub.versia%3Agroups%2FGroup/1234 fetches the Group entity with ID 1234.
Name
method
Description
Must be GET.
Name
response
Description
Entity data as JSON, as defined in its Entity definition document.

Example request

GET /.versia/v0.6/entities/user/1234
Host: b.social
Accept: application/vnd.versia+json

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.versia+json; charset=utf-8

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

Entity collections

Name
endpoint
Description
Must be /.versia/v0.6/entities/{entity_type}/{id}/collections/{collection_type}.
- {entity_type}: The type of the entity to fetch, URL-encoded.
- {id}: The ID of the entity to fetch, URL-encoded.
- {collection_type}: The type of the collection to fetch, URL-encoded.
Example: GET /.versia/v0.6/entities/User/1234/collections/followers fetches the followers of the user with ID 1234.
Name
method
Description
Must be GET.
Name
response
Description
Must be either a Collection or a URICollection as JSON.

Example request

GET /.versia/v0.6/entities/user/1234/collections/followers
Host: b.social
Accept: application/vnd.versia+json

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.versia+json; charset=utf-8

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

Pagination

Collections MUST support pagination, using the following URI parameters:

offset: The number of items to skip before returning the first item. This is a zero-based index.
limit: The maximum number of items to return. This is a one-based index. Implementations MUST support a minimum of 1 and a maximum of 40 items.

Example paginated collection request

GET /.versia/v0.6/entities/user/1234/collections/followers?offset=10&limit=20
Host: b.social
Accept: application/vnd.versia+json

Inbox

The inbox endpoint is used for instances to send entities to each other. It is a single endpoint that can receive messages for every user (also known as a shared inbox).

The delivery mechanism is described further in the Federation document.

Name
endpoint
Description
Must be /.versia/v0.6/inbox.
Name
method
Description
Must be POST.

Example request

POST /.versia/v0.6/inbox
Host: b.social
Accept: application/vnd.versia+json
Content-Type: application/vnd.versia+json; charset=utf-8

{
    "type": "Note",
    "id": "1234",
    ...
}