# Odyssey Public API

This document describes the only Odyssey API endpoints intended for public third-party
builder use (as documented herein and served from `https://builders.odyssey-api.com`, the
"Service").

## Stability

Odyssey intends to provide the Service for third-party builders to use in good faith and
under reasonable usage patterns, but Odyssey does not provide any support, uptime,
availability, or continuation warranties or guarantees of any kind related to the Service
or any usage thereof.

Other than the Service, every other endpoint across Odyssey properties is explicitly
intended for internal consumption only, and should be treated as unstable and unauthorized
for third-party usage. Any suspected third-party usage of undocumented endpoints is likely
to be blocked without warning or notice.

## Disclaimer

THE SERVICE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SERVICE OR ANY USAGE THEREOF.

## Base Path

All documented endpoints are under:

```text
/public/v0
```

Responses are JSON unless otherwise noted.

## GET /public/v0/room-id-by-contract-address/{chain_id}/{contract_address}

Returns the public Odyssey room id associated with a Base mainnet room-token contract
address.

Request path parameters:

```json
{
	"chain_id": 8453,
	"contract_address": "0x0000000000000000000000000000000000000000"
}
```

Success response:

```json
{
	"api_version": "v0",
	"chain_id": 8453,
	"contract_address": "0x0000000000000000000000000000000000000000",
	"room_id": "room_abc"
}
```

## GET /public/v0/room-info-by-room-id/{room_id}

Returns public centralized room metadata for a public Odyssey room id.

Request path parameters:

```json
{
	"room_id": "room_abc"
}
```

Success response:

```json
{
	"api_version": "v0",
	"room_info": {
		"id": "room_abc",
		"title": "Example Room",
		"description": "Optional public room description."
	}
}
```

Nullable fields may be `null`.

## Error Response

Errors use this shape:

```json
{
	"api_version": "v0",
	"error": {
		"code": "not_found",
		"message": "resource not found"
	}
}
```

Current error codes:

- `invalid_request`
- `unsupported_chain`
- `not_found`
- `method_not_allowed`
- `upstream_unavailable`