Add comprehensive API documentation

Co-authored-by: v0l <1172179+v0l@users.noreply.github.com>

API.md

@@ -0,0 +1,316 @@
+# zap.stream API Documentation
+
+This document describes the REST API endpoints available in the zap.stream core streaming server.
+
+## Authentication
+
+The API uses NIP-98 (Nostr HTTP Auth) for authentication. All protected endpoints require an `Authorization` header with the following format:
+
+```
+Authorization: Nostr <base64-encoded-nostr-event>
+```
+
+The Nostr event must:
+- Be of kind 27235 (NIP-98 HTTP Auth)
+- Have a valid signature
+- Include appropriate `method` and `url` tags matching the request
+- Have a recent timestamp (within acceptable time window)
+
+## Base URL
+
+All API endpoints are prefixed with `/api/v1/`
+
+## Endpoints
+
+### Account Management
+
+#### Get Account Information
+```
+GET /api/v1/account
+```
+
+**Authentication:** Required
+
+**Response:**
+```json
+{
+  "endpoints": [
+    {
+      "name": "string",
+      "url": "string", 
+      "key": "string",
+      "capabilities": ["string"],
+      "cost": {
+        "unit": "string",
+        "rate": 0.0
+      }
+    }
+  ],
+  "balance": 0,
+  "tos": {
+    "accepted": false,
+    "link": "string"
+  },
+  "forwards": [
+    {
+      "id": 0,
+      "name": "string"
+    }
+  ],
+  "details": {
+    "title": "string",
+    "summary": "string", 
+    "image": "string",
+    "tags": ["string"],
+    "content_warning": "string",
+    "goal": "string"
+  }
+}
+```
+
+**Description:** Returns comprehensive account information including streaming endpoints, account balance, terms of service status, forward destinations, and stream details.
+
+#### Update Account
+```
+PATCH /api/v1/account
+```
+
+**Authentication:** Required
+
+**Request Body:**
+```json
+{
+  "accept_tos": true
+}
+```
+
+**Response:** 
+```json
+{}
+```
+
+**Description:** Updates account settings, primarily used for accepting terms of service.
+
+### Payment Operations
+
+#### Request Top-up
+```
+GET /api/v1/topup?amount=<amount>
+```
+
+**Authentication:** Required
+
+**Query Parameters:**
+- `amount` (required): Amount to top up in millisatoshi
+
+**Response:**
+```json
+{
+  "pr": "string"
+}
+```
+
+**Description:** Generates a Lightning Network payment request for adding funds to the account balance. Returns a payment request (invoice) that can be paid to credit the account.
+
+#### Withdraw Funds
+```
+POST /api/v1/withdraw?invoice=<payment_request>
+```
+
+**Authentication:** Required
+
+**Query Parameters:**
+- `invoice` (required): Lightning Network payment request to pay
+
+**Response:**
+```json
+{
+  "fee": 0,
+  "preimage": "string"
+}
+```
+
+**Description:** Withdraws funds from the account balance by paying a Lightning Network invoice. Returns the fee charged and payment preimage on success.
+
+### Stream Management
+
+#### Update Stream Event
+```
+PATCH /api/v1/event
+```
+
+**Authentication:** Required
+
+**Request Body:**
+```json
+{
+  "id": "string",
+  "title": "string",
+  "summary": "string",
+  "image": "string", 
+  "tags": ["string"],
+  "content_warning": "string",
+  "goal": "string"
+}
+```
+
+**Response:**
+```json
+{}
+```
+
+**Description:** Updates stream event metadata such as title, description, image, tags, content warnings, and goals.
+
+### Forward Management
+
+#### Create Forward
+```
+POST /api/v1/forward
+```
+
+**Authentication:** Required
+
+**Request Body:**
+```json
+{
+  "name": "string",
+  "target": "string"
+}
+```
+
+**Response:**
+```json
+{
+  "id": 0
+}
+```
+
+**Description:** Creates a new payment forward destination. Forwards allow automatic routing of payments to external Lightning addresses or Nostr zap targets.
+
+#### Delete Forward
+```
+DELETE /api/v1/forward/{id}
+```
+
+**Authentication:** Required
+
+**Path Parameters:**
+- `id`: Forward ID to delete
+
+**Response:**
+```json
+{}
+```
+
+**Description:** Removes a payment forward destination by ID.
+
+### History and Keys
+
+#### Get Account History
+```
+GET /api/v1/history
+```
+
+**Authentication:** Required
+
+**Response:**
+```json
+{
+  "items": [
+    {
+      "created": 0,
+      "type": 0,
+      "amount": 0.0,
+      "desc": "string"
+    }
+  ],
+  "page": 0,
+  "page_size": 0
+}
+```
+
+**Description:** Returns paginated transaction history for the account including payments, withdrawals, and streaming costs.
+
+#### Get Stream Keys
+```
+GET /api/v1/keys
+```
+
+**Authentication:** Required
+
+**Response:**
+```json
+[
+  {
+    "id": 0,
+    "key": "string",
+    "created": 0,
+    "expires": 0,
+    "stream_id": "string"
+  }
+]
+```
+
+**Description:** Returns all active stream keys for the account.
+
+#### Create Stream Key
+```
+POST /api/v1/keys
+```
+
+**Authentication:** Required
+
+**Request Body:**
+```json
+{
+  "event": {
+    "title": "string",
+    "summary": "string",
+    "image": "string",
+    "tags": ["string"], 
+    "content_warning": "string",
+    "goal": "string"
+  },
+  "expires": "2024-01-01T00:00:00Z"
+}
+```
+
+**Response:**
+```json
+{
+  "key": "string",
+  "event": "string"
+}
+```
+
+**Description:** Creates a new stream key with associated event metadata and optional expiration time.
+
+## Error Handling
+
+All endpoints return appropriate HTTP status codes:
+
+- `200 OK` - Successful request
+- `400 Bad Request` - Invalid request parameters or body
+- `401 Unauthorized` - Missing or invalid authentication
+- `404 Not Found` - Resource not found
+- `500 Internal Server Error` - Server error
+
+Error responses include a JSON body with error details where applicable.
+
+## Rate Limiting
+
+The API may implement rate limiting based on account balance and usage patterns. Specific limits are not documented but will be enforced server-side.
+
+## CORS Support
+
+The API includes CORS headers allowing cross-origin requests from web applications:
+
+```
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Headers: *
+Access-Control-Allow-Methods: HEAD, GET, PATCH, DELETE, POST, OPTIONS
+```
+
+## Content Type
+
+All API endpoints expect and return `application/json` content type unless otherwise specified.

README.md

@@ -6,4 +6,7 @@ Rust zap.stream core streaming server
 
 ![diagram](./crates/zap-stream/zap.stream.svg)
 
+## Documentation
+
+- [API Documentation](./API.md) - Complete REST API reference