readme: document HTTP gateway API

README.md

@@ -0,0 +1,93 @@
+# ollie-httpgw
+
+HTTP gateway for ollie. Translates REST requests to D-Bus calls against `org.ollie.SessionManager`, allowing any HTTP client to manage sessions without a D-Bus library. Also serves as the backend for the web UI.
+
+## Building
+
+```sh
+mk
+```
+
+Installs `ollie-httpgw` to `$HOME/bin`.
+
+## Usage
+
+```sh
+ollie-httpgw start       # start daemon (backgrounds itself)
+ollie-httpgw fgstart     # start in foreground
+ollie-httpgw stop        # stop daemon
+ollie-httpgw status      # check if running
+```
+
+The gateway listens on `:8011` by default. Override with `-listen`:
+
+```sh
+ollie-httpgw start -listen :9090
+```
+
+Requires either `olliesrv` or `ollie-dbus` running (provides the D-Bus service).
+
+## API
+
+All responses are JSON. An OpenAPI spec is served at `GET /openapi.json`.
+
+### Sessions
+
+| Method | Path | Action |
+|--------|------|--------|
+| `GET` | `/sessions` | List all sessions |
+| `POST` | `/sessions` | Create a session (body: `{cwd, backend, model, agent}`) |
+| `GET` | `/sessions/{id}` | Get session info |
+| `DELETE` | `/sessions/{id}` | Kill a session |
+| `PATCH` | `/sessions/{id}` | Rename a session (body: `{name}`) |
+
+### Interaction
+
+| Method | Path | Action |
+|--------|------|--------|
+| `POST` | `/sessions/{id}/submit` | Submit a prompt (body: `{prompt}`) |
+| `POST` | `/sessions/{id}/interrupt` | Interrupt the current turn |
+
+### State queries
+
+| Method | Path | Action |
+|--------|------|--------|
+| `GET` | `/sessions/{id}/state` | Get session state |
+| `GET` | `/sessions/{id}/chat?offset=N` | Get chat text from offset |
+| `GET` | `/sessions/{id}/usage` | Get token usage |
+| `GET` | `/sessions/{id}/cost` | Get cost |
+| `GET` | `/sessions/{id}/config` | Get config |
+| `POST` | `/sessions/{id}/config` | Set config (body: `{key, value}`) |
+| `GET` | `/sessions/{id}/context` | Get message history (JSONL) |
+| `GET` | `/sessions/{id}/models` | List models for session's backend |
+
+### Peers
+
+| Method | Path | Action |
+|--------|------|--------|
+| `GET` | `/sessions/{id}/peers` | List peers |
+| `POST` | `/sessions/{id}/peers` | Add peer (body: `{peer_id}`) |
+| `DELETE` | `/sessions/{id}/peers/{peer_id}` | Remove peer |
+| `POST` | `/sessions/{id}/peers/{peer_id}/submit` | Submit to peer (body: `{prompt}`) |
+
+### Enumeration
+
+| Method | Path | Action |
+|--------|------|--------|
+| `GET` | `/backends` | List available backends |
+| `GET` | `/agents` | List available agents |
+
+## Example
+
+```sh
+# Create a session
+curl -X POST http://localhost:8011/sessions \
+  -d '{"cwd": "/home/user/project", "agent": "default"}'
+
+# Submit a prompt
+curl -X POST http://localhost:8011/sessions/<id>/submit \
+  -d '{"prompt": "list files in cwd"}'
+
+# Poll chat
+curl http://localhost:8011/sessions/<id>/chat?offset=0
+```