# Endpoints

Every route in Versia's federation API.

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`

- [Signature](/signatures): Not required for requests or responses.

- Accept: `application/json`

- Response: A small JSON object with a single attribute:

  - `versions`: Supported Versia Protocol versions.
    - Versions marked as "Working Draft X" are represented as `0.X.Y`.

```http title="Example request"
GET /.well-known/versia HTTP/1.1
Host: b.example
Accept: application/json
```

```http title="Example response"
HTTP/1.1 200 OK
Content-Type: application/json

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

## Instance Metadata

`GET /.versia/v0.7/instance`

- [Signature](/signatures): Not required for requests or responses.
- Response: Instance's metadata, as defined in the [Instance Metadata](/entities/instance-metadata) document.

```http title="Example request"
GET /.versia/v0.7/instance HTTP/1.1
Host: b.example
Accept: application/vnd.versia+json
```

```http title="Example response"
HTTP/1.1 200 OK
Content-Type: application/vnd.versia+json

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

## Entity Data

`GET /.versia/v0.7/entities/{entity_type}/{id}`

- [Signature](/signatures): Required for requests and responses.

- Parameters:

  - `{entity_type}`: The type of the entity to fetch, [not percent-encoded](/federation/http#encoding).
  - `{id}`: The ID of the entity to fetch.

  Example: `GET /.versia/v0.7/entities/pub.versia:groups/Group/1234` fetches the [Group](/extensions/groups) entity with ID `1234`.

- Response: Entity data as JSON, as defined in its [Entity](/entities) definition document.

  `404` if there is no such entity, or if the requesting instance [may not fetch it](/federation#access). A deleted entity answers [`410` or `404`](/entities/delete#fetching-deleted-entities).

```http title="Example request"
GET /.versia/v0.7/entities/User/1234 HTTP/1.1
Host: b.example
Accept: application/vnd.versia+json
```

```http title="Example response"
HTTP/1.1 200 OK
Content-Type: application/vnd.versia+json

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

## Entity Collections

`GET /.versia/v0.7/entities/{entity_type}/{id}/collections/{collection_type}`

- [Signature](/signatures): Required for requests and responses.

- Parameters:

  - `{entity_type}`: The type of the entity to fetch, [not percent-encoded](/federation/http#encoding).
  - `{id}`: The ID of the entity to fetch.
  - `{collection_type}`: The type of the collection to fetch, [not percent-encoded](/federation/http#encoding).

  Example: `GET /.versia/v0.7/entities/User/1234/collections/subscribers` fetches the subscribers of the user with ID `1234`.

- Response: **MUST** be either a [Collection](/structures/collection) or a [ReferenceCollection](/structures/collection#reference-collection) as JSON.

```http title="Example request"
GET /.versia/v0.7/entities/User/1234/collections/subscribers HTTP/1.1
Host: b.example
Accept: application/vnd.versia+json
```

```http title="Example response"
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](/federation#access).

```http title="Example paginated collection request"
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](/entities/instance-metadata) has no ID, so its collections have their own path. They paginate like any other [collection](#pagination).

`GET /.versia/v0.7/instance/collections/{collection_type}`

- [Signature](/signatures): Required for requests and responses.

- Parameters:

  - `{collection_type}`: The type of the collection to fetch: `moderators` or `admins`.

  Example: `GET /.versia/v0.7/instance/collections/admins` fetches the administrators of the instance.

- Response: **MUST** be either a [Collection](/structures/collection) or a [ReferenceCollection](/structures/collection#reference-collection) as JSON.

```http title="Example request"
GET /.versia/v0.7/instance/collections/admins HTTP/1.1
Host: b.example
Accept: application/vnd.versia+json
```

```http title="Example response"
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](/federation#inboxes) for how delivery works.

`POST /.versia/v0.7/inbox`

- [Signature](/signatures): Required for requests and responses.
- Response: See [Status Codes](/federation/http#status-codes).

```http title="Example request"
POST /.versia/v0.7/inbox HTTP/1.1
Host: b.example
Content-Type: application/vnd.versia+json

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