> ## Documentation Index
> Fetch the complete documentation index at: https://docs.building58.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Relay API

> The HTTP API of the relay, the local server that runs a room's sessions, tickets, tasks and reviews.

The relay is the local server that runs a room. The room page and `ticket.js` use this API. You can use it too, with curl or a script on the same computer.

The endpoint pages in this tab come from [`docs/openapi.json`](https://github.com/bfalkowski/Building58/blob/main/docs/openapi.json) in the Building58 repo, an OpenAPI 3.1 document. Its `info.version` is the API version. The description of each route comes from [The relay API and routes](https://building58.ai/docs/manual/relay.html) in the technical manual.

> [!NOTE]
>
> The relay answers your computer only, at `http://localhost:8787`, where `npm run office` starts it. So these pages show each request and response, but they have no button to send a request.

## Channels

All routes except `GET /health` are under `/channels/{channel}`. A channel joins callers to one world page on the relay. The room uses `office` by default. Each channel is a separate room, with its own sessions and tickets.

## Authentication

Most routes need one of these:

| Credential | How to send it | What it reaches |
| - | - | - |
| The relay key, `RELAY_KEY` | `Authorization: Bearer <key>`. The room page sends it in the address as `?key=`. | Every route. |
| A session's token, `OFFICE_TICKET_TOKEN` | `Authorization: Bearer <token>` | Only the routes that the session's role needs. The description of each route says which tokens it takes. |

`GET /health` needs no key.

The routes that can run commands answer only the room page on your computer, with the key. A tunnel, another website or another computer gets 403, even with the key. See [Safety and permissions](https://docs.building58.ai/architecture/safety.md).

## A first call

```bash Check that the relay is up theme={null}
curl -s http://localhost:8787/health
```

```bash List the tickets, with the relay key in RELAY_KEY theme={null}
curl -s -H "Authorization: Bearer $RELAY_KEY" \
  http://localhost:8787/channels/office/tickets
```

## Errors

A refused call returns JSON with `ok: false`, a short `error` code such as `bad_param`, `forbidden` or `not_found`, and a `message` in plain words.

| Status | Reason |
| - | - |
| 400 | A bad body. |
| 401 | No key. |
| 403 | A key or token that may not do this. |
| 404 | An unknown route or id. |
| 409 | A state that does not allow it. |
| 413 | A body over 256 KB. |
| 429 | Too soon. See [Limits](https://docs.building58.ai/architecture/safety.md#limits). |
| 503, 504 | No page answers. |

For events, webhooks, `ticket.js` and games, see [The relay API and routes](https://building58.ai/docs/manual/relay.html) in the technical manual.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.