export const metadata = {
    title: 'HTTP',
    description:
        'How Versia uses the HTTP protocol for all communications between instances.',
}

# HTTP

Versia uses the HTTP protocol for all communications between instances. HTTP requests must conform to certain standards to ensure compatibility between different implementations, as well as to ensure the security and integrity of the data being exchanged.

ALL kinds of HTTP requests/responses between instances **MUST** include a [Signature](/signatures), signed with either the relevant [User](/entities/user)'s private key or the [instance's private key](/entities/instance-metadata).

## Requests

<Row>
    <Col>
        <Properties>
            <Property name="Accept" type="string" required={true}>
                Must include `application/json`.
            </Property>
            <Property name="Content-Type" type="string" required={true}>
                Must include `application/json; charset=utf-8`, if the request has a body.
            </Property>
            <Property name="Versia-Signature" type="string" required={false}>
                See [Signatures](/signatures) for more information.
            </Property>
            <Property name="Versia-Signed-By" type="URI" required={false} typeLink="/types#uri">
                See [Signatures](/signatures).
            </Property>
            <Property name="Versia-Signed-At" type="string" required={false}>
                See [Signatures](/signatures).
            </Property>
            <Property name="User-Agent" type="string" required={false}>
                A string identifying the software making the request.
            </Property>
        </Properties>
    </Col>
    <Col sticky>
        ```http {{ 'title': 'Example Request' }}
        POST https://bob.com/users/1/inbox HTTP/1.1
        Accept: application/json
        User-Agent: CoolServer/1.0 (https://coolserver.com)
        Versia-Signature: /CjB2L9bcvRg+uP19B4/rqy7Ji9/cqMFPlL3GVCIndnQjYyOpBzJEAl9weDnXm7Jrqa3y6sBC+EYWKThO2r9Bw==
        Versia-Signed-By: https://example.com/users/1
        Versia-Signed-At: 1729241687
        ```
    </Col>
</Row>

## Responses

<Row>
    <Col>
        <Properties>
            <Property name="Content-Type" type="string" required={true}>
                Must include `application/json; charset=utf-8`.
            </Property>
            <Property name="Versia-Signature" type="string" required={false}>
                See [Signatures](/signatures) for more information.
            </Property>
            <Property name="Versia-Signed-By" type="URI" required={false} typeLink="/types#uri">
                See [Signatures](/signatures).
            </Property>
            <Property name="Versia-Signed-At" type="string" required={false}>
                See [Signatures](/signatures).
            </Property>
        </Properties>
    </Col>
    <Col sticky>
        ```http {{ 'title': 'Example Response' }}
        HTTP/1.1 200 OK
        Content-Type: application/json; charset=utf-8
        Versia-Signature: /CjB2L9bcvRg+uP19B4/rqy7Ji9/cqMFPlL3GVCIndnQjYyOpBzJEAl9weDnXm7Jrqa3y6sBC+EYWKThO2r9Bw==+7BvnWKITyGyTwHbb6fVYwRx1I
        Versia-Signed-By: https://example.com/users/1
        Versia-Signed-At: 1729241717
        ```
    </Col>
</Row>