# Discovery

How Versia instances can discover users, capabilities, and public keys.

A lot of the time, Versia instances may need to look up information about other instances, such as their users, capabilities, and public keys. This is done through a process called **discovery**.

## User Discovery

Discovering a user starts from [the user's address](/entities/user#addresses). With it, the [WebFinger](https://tools.ietf.org/html/rfc7033) protocol can be used to find the user's profile.

### User Discovery Example

To discover the profile of the user `@george@versia.example`, an instance would make a `GET` request to `https://versia.example/.well-known/webfinger?resource=acct:george@versia.example`.

```http title="Example Request"
GET /.well-known/webfinger?resource=acct:george@versia.example HTTP/1.1
Host: versia.example
Accept: application/jrd+json
```

```jsonc title="Example Response"
{
    "subject": "acct:george@versia.example",
    "aliases": [
        "https://versia.example/.versia/v0.7/entities/User/033p0g85e2000",
        "https://versia.example/@george"
    ],
    "links": [
        {
            "rel": "http://webfinger.net/rel/profile-page",
            "type": "text/html",
            "href": "https://versia.example/@george"
        },
        {
            "rel": "self",
            "type": "application/vnd.versia+json",
            "href": "https://versia.example/.versia/v0.7/entities/User/033p0g85e2000"
        },
        {
            "rel": "http://webfinger.net/rel/avatar",
            "type": "image/png",
            "href": "https://cdn.example.com/uploads/banana.png"
        }
    ]
}
```

## Instance Discovery

Instance metadata can be accessed in two steps:

1. Making a `GET` request to the instance's [`/.well-known/versia` endpoint](/federation/endpoints#well-known) to discover supported Versia Protocol versions.
2. [Choosing the protocol version](/federation/versions#choosing-a-version) to use, and then querying the instance metadata endpoint as documented in the [Endpoints](/federation/endpoints#instance-metadata) document.

### Instance Discovery Example

To discover the metadata of the instance `versia.example`, an instance would first make a `GET` request to `https://versia.example/.well-known/versia`.

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

```jsonc title="Example Response"
{
    "versions": [
        "0.7.0",
        "0.6.0"
    ]
}
```

Then, it:

- Picks `0.7`, the highest `0.X` that both instances support
- Makes a `GET` request to `https://versia.example/.versia/v0.7/instance`.

This endpoint will return an [InstanceMetadata](/entities/instance-metadata) entity.

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

```jsonc title="Example Response"
{
    "type": "InstanceMetadata",
    "name": "Example Instance",
    "software": {
        "name": "Versia Server",
        "version": "0.7.0"
    },
    "compatibility": {
        "extensions": [
            "pub.versia:social@1",
            "pub.versia:reactions@1",
            "pub.versia:polls@1",
            "pub.versia:reports@1"
        ]
    },
    "domain": "versia.example",
    "public_key": {
        "algorithm": "ed25519",
        "key": "MCowBQYDK2VwAyEA9zhEMtQZetRl4QrLcz99i7jOa6ZVjX7aLfRUsMuKByI="
    },
    "created_at": "2021-07-01T00:00:00Z"
}
```