# REST API

The Collab Server provides a REST API for snapshots, health checks, and more.

## Base URL

```
http://localhost:4000/api
```

## Endpoints

### Health Check

```http
GET /health
```

Response:
```json
{
  "status": "ok",
  "uptime": 3600,
  "version": "1.0.0"
}
```

### Snapshots

#### Create Snapshot

```http
POST /api/snapshots
Content-Type: application/json

{
  "artworkId": "item-001",
  "sketch": "sketch-entities-001",
  "image": "data:image/png;base64,...",
  "parameters": { ... },
  "metadata": {
    "title": "Morning Light",
    "description": "Warm color palette"
  }
}
```

Response:
```json
{
  "id": "snap_abc123",
  "url": "/api/snapshots/snap_abc123",
  "qrUrl": "/api/snapshots/snap_abc123/qr",
  "created": "2024-06-15T10:30:00Z"
}
```

#### Retrieve Snapshot

```http
GET /api/snapshots/:id
```

Response:
```json
{
  "id": "snap_abc123",
  "artworkId": "item-001",
  "sketch": "sketch-entities-001",
  "image": "data:image/png;base64,...",
  "parameters": { ... },
  "metadata": {
    "title": "Morning Light"
  },
  "created": "2024-06-15T10:30:00Z"
}
```

#### Snapshot Image

```http
GET /api/snapshots/:id/image
```

Returns: PNG image

#### Generate QR Code

```http
GET /api/snapshots/:id/qr
```

Query parameters:
| Parameter | Default | Description |
|-----------|---------|-------------|
| `size` | `200` | Size in pixels |
| `format` | `png` | `png` or `svg` |

Returns: QR code image

### Lifestream

#### Exhibition Snapshots

```http
GET /api/lifestream/:exhibition
```

Query parameters:
| Parameter | Default | Description |
|-----------|---------|-------------|
| `limit` | `20` | Max. count |
| `since` | - | Timestamp filter |

Response:
```json
{
  "exhibition": "mosaik-2027",
  "snapshots": [
    {
      "id": "snap_xyz",
      "artworkId": "item-001",
      "image": "/api/snapshots/snap_xyz/image",
      "timestamp": "2024-06-15T10:30:00Z"
    }
  ]
}
```

#### Post Snapshot (from Artwork)

```http
POST /api/lifestream/:exhibition/snapshots
Content-Type: application/json

{
  "artworkId": "item-001",
  "image": "data:image/png;base64,..."
}
```

### Gallery

#### List Artworks

```http
GET /api/gallery/artworks
```

Response:
```json
{
  "items": [
    {
      "slug": "entities",
      "name": "Entities",
      "description": "Agent-based system",
      "thumbnail": "/assets/thumbs/entities.jpg"
    }
  ]
}
```

#### Artwork Details

```http
GET /api/gallery/artworks/:slug
```

### Statistics

```http
GET /api/stats
```

Response:
```json
{
  "connections": {
    "total": 42,
    "artworks": 15,
    "studio": 2
  },
  "snapshots": {
    "total": 1234,
    "today": 56
  },
  "uptime": 86400
}
```

## Error Handling

Errors are returned as JSON:

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Snapshot not found",
    "statusCode": 404
  }
}
```

### Status Codes

| Code | Meaning |
|------|---------|
| `200` | OK |
| `201` | Created |
| `400` | Bad Request |
| `404` | Not Found |
| `500` | Server Error |

## Rate Limiting

| Endpoint | Limit |
|----------|-------|
| `/api/snapshots` (POST) | 10/min |
| `/api/lifestream/*/snapshots` | 1/min |
| Other GET endpoints | 100/min |

## CORS

CORS is enabled for the following origins:

```
http://localhost:*
https://*.quiet-frames.de
```

## Authentication (optional)

For protected endpoints:

```http
Authorization: Bearer <token>
```

Token is generated via Art.Works! Studio.