# API Reference

## Base Behavior

- Base URL: same origin as UI host.
- UI route:
  - `GET /` returns the dashboard HTML shell.
- API route namespace:
  - All API endpoints are under `/api/...`.
- Cache behavior:
  - Responses under `/api/` and `/static/` include no-store cache headers.

## Authentication Model

- Login endpoint sets a session value on success.
- Protected endpoints require `Depends(require_auth)`.
- Session cookie behavior:
  - `same_site=lax`
  - max age: 8 hours
  - secure flag controlled by `SESSION_COOKIE_SECURE`

Related references:

- Configuration: `doc/environment.md`
- Auth implementation: `app/auth.py`

## Error Contract

- `401` for authentication failures.
- `400` for missing required node configuration values.
- `422` for request validation and unsupported chart window values.
- `502` for RPC or SSH operation failures.
- Error shape for handled exceptions:
  - `{ "detail": "<message>" }`

## Endpoint Contracts

### Health and Session

| Method | Path | Auth | Description |
| --- | --- | --- | --- |
| `GET` | `/api/health` | No | Returns service liveness: `{ "ok": true }`. |
| `GET` | `/api/auth/me` | No | Returns current authentication state and username if authenticated. |
| `POST` | `/api/auth/login` | No | Validates credentials and creates session. |
| `POST` | `/api/auth/logout` | Yes | Clears session. |

`POST /api/auth/login` request body:

```json
{
  "username": "admin",
  "password": "secret"
}
```

### Node Settings

| Method | Path | Auth | Description |
| --- | --- | --- | --- |
| `GET` | `/api/settings` | Yes | Returns persisted node connection and control settings. |
| `PUT` | `/api/settings` | Yes | Validates and persists node settings. |

`PUT /api/settings` request body fields:

- `rpc_url` string
- `rpc_username` string
- `rpc_password` string
- `rpc_wallet` string
- `config_path` string
- `ssh_host` string
- `ssh_port` integer `1..65535`
- `ssh_username` string
- `ssh_password` string
- `ssh_key_path` string
- `bitcoin_binary` string

All string fields are trimmed before persistence.

### Dashboard

| Method | Path | Auth | Description |
| --- | --- | --- | --- |
| `GET` | `/api/dashboard/summary` | Yes | Returns chain, network, mempool, mining, uptime, optional wallet data, and `updated_at`. |
| `GET` | `/api/dashboard/history` | Yes | Returns metric history for query-param `window` and `limit`. |
| `GET` | `/api/dashboard/history/{window}` | Yes | Same as above with `window` as a path parameter. |

Supported `window` values:

- `5m`
- `30m`
- `2h`
- `6h`
- `all`

`limit` is clamped server-side to `[1, 20000]`.

### RPC Explorer

| Method | Path | Auth | Description |
| --- | --- | --- | --- |
| `POST` | `/api/rpc/call` | Yes | Executes a JSON-RPC method with params and optional wallet override. |
| `GET` | `/api/rpc/commands` | Yes | Calls node `help` and returns parsed method catalog. |
| `GET` | `/api/rpc/help/{method_name}` | Yes | Returns detailed `help` output for one method. |

`POST /api/rpc/call` request body:

```json
{
  "method": "getblockchaininfo",
  "params": [],
  "wallet": null
}
```

### Node Actions

| Method | Path | Auth | Description |
| --- | --- | --- | --- |
| `POST` | `/api/actions/stop` | Yes | Calls RPC `stop`. |
| `POST` | `/api/actions/start` | Yes | Runs SSH start command built from persisted settings. |
| `POST` | `/api/actions/restart` | Yes | Attempts RPC stop then runs SSH start command. |

Action responses include action metadata and remote execution payload when SSH is involved.

## Operational Notes

- Startup and restart require:
  - valid SSH connectivity
  - `config_path`
  - SSH user credentials or key access
- When running in Docker, `rpc_url` should usually target `host.docker.internal` if the node is on the Docker host.

See `doc/build-and-deploy.md` for Docker network details.