http://localhost:1337
```typescript
## Endpoints
<CardGroup cols={2}>
<Card title="State Management" icon="database" href="#state-endpoints">
Get and update overlay state
</Card>
<Card title="Configuration" icon="gear" href="#configuration-endpoints">
Get and update application config
</Card>
<Card title="Assets" icon="flag" href="#asset-endpoints">
List available country and state flags
</Card>
<Card title="Integrations" icon="plug" href="/api/startgg">
Tournament and livestream connections
</Card>
</CardGroup>
## State Endpoints
### GET /state
Returns the current overlay state including tournament info, players, commentators, and connection status.
**Response**
Returns a [BoofState](/api/state) object.
```json
{
"tournament": {
"name": "My Local #42",
"match": "Winners Finals",
"phase": "Top 8",
"bestOf": 5
},
"player1": {
"name": "Mango",
"sponsor": "C9",
"score": 2,
"character": 2,
"characterColor": 0,
"pronouns": "he/him",
"country": "us",
"state": "CA",
"seed": 1,
"losers": false
},
"player2": { /* ... */ },
"commentators": [],
"slippiConnected": true,
"obsConnected": true,
"started": true
}
```typescript
**Example**
```bash
curl http://localhost:1337/state
```typescript
### POST /state
Updates the overlay state. The entire state object must be provided.
**Parameters**
<ParamField query="clientId" type="string">
Optional client identifier to prevent update loops in the UI
</ParamField>
<ParamField body="state" type="BoofState" required>
The complete [BoofState](/api/state) object to save
</ParamField>
**Response**
Returns `201 Created` on success.
**Side Effects**
- Writes state to `out/state.json`
- Writes formatted output to `out/program_state.json`
- Writes individual text files to `out/p1/` and `out/p2/`
- Writes character images
- Emits `update_state` WebSocket event
**Example**
```bash
curl -X POST http://localhost:1337/state \
-H "Content-Type: application/json" \
-d '{"tournament":{"name":"Local #42","match":"WF","phase":"Top 8","bestOf":5},"player1":{...},"player2":{...},"commentators":[],"slippiConnected":true,"obsConnected":false,"started":false}'
```typescript
## Configuration Endpoints
### GET /config
Returns the current boofstream configuration.
**Response**
Returns a [BoofConfig](/api/config) object.
```json
{
"slippi": {
"port": 53742
},
"obs": {
"doSwitch": true,
"host": "127.0.0.1:4455",
"password": "",
"noGameScene": "Crowd Cam",
"gameScene": "Melee"
},
"startgg": {
"token": "",
"tournamentUrl": ""
},
"customization": {
"appendLToLosers": false,
"player1Color": "#00a800",
"player2Color": "#0f7477"
}
}
```typescript
**Example**
```bash
curl http://localhost:1337/config
```typescript
### POST /config
Updates the boofstream configuration.
**Parameters**
<ParamField query="clientId" type="string">
Optional client identifier to prevent update loops in the UI
</ParamField>
<ParamField body="config" type="BoofConfig" required>
The complete [BoofConfig](/api/config) object to save
</ParamField>
**Response**
Returns `201 Created` on success.
**Side Effects**
- Writes config to `out/config.json`
- Emits `update_config` WebSocket event
- If customization options changed, triggers state file regeneration
**Example**
```bash
curl -X POST http://localhost:1337/config \
-H "Content-Type: application/json" \
-d '{"slippi":{"port":53742},"obs":{...},"startgg":{...},"customization":{...}}'
```typescript
## Asset Endpoints
### GET /countries
Returns a list of available country codes for flag assets.
**Response**
Returns an array of ISO country codes (lowercase).
```json
["us", "ca", "mx", "jp", "kr", "se", "no", ...]
```typescript
**Example**
```bash
curl http://localhost:1337/countries
```typescript
### GET /countries/:country/states
Returns a list of available state/province codes for a specific country.
**Parameters**
<ParamField path="country" type="string" required>
The country code (uppercase, e.g., "US", "CA")
</ParamField>
**Response**
Returns an array of state/province codes.
```json
["AL", "AK", "AZ", "AR", "CA", "CO", ...]
```typescript
**Example**
```bash
curl http://localhost:1337/countries/US/states
```typescript
## WebSocket Events
boofstream also exposes WebSocket events on port `1338` for real-time updates:
- `update_state` - Emitted when state changes
- `update_config` - Emitted when config changes
Connect to `http://localhost:1338` using Socket.io to listen for these events.
## Related
<CardGroup cols={2}>
<Card title="BoofState Type" icon="database" href="/api/state">
State object structure
</Card>
<Card title="BoofConfig Type" icon="gear" href="/api/config">
Configuration object structure
</Card>
<Card title="Start.gg API" icon="brackets-curly" href="/api/startgg">
Tournament integration endpoints
</Card>
<Card title="Slippi API" icon="gamepad" href="/api/slippi">
Livestream connection endpoints
</Card>
</CardGroup>