virtual-banker/docs/API.md

# Virtual Banker API Reference

## Base URL

```
http://localhost:8081
```

## Authentication

All requests (except health check) require authentication via JWT token in the `Authorization` header:

```
Authorization: Bearer <jwt-token>
```

## Endpoints

### Health Check

```
GET /health
```

**Response:**
```json
{
  "status": "healthy"
}
```

### Create Session

```
POST /v1/sessions
```

**Request Body:**
```json
{
  "tenant_id": "tenant-123",
  "user_id": "user-456",
  "auth_assertion": "jwt-token",
  "portal_context": {
    "route": "/account",
    "account_id": "acc-789"
  }
}
```

**Response:**
```json
{
  "session_id": "sess-abc123",
  "ephemeral_token": "ephemeral-token-xyz",
  "config": {
    "theme": {
      "primaryColor": "#0066cc"
    },
    "avatar_enabled": true,
    "greeting": "Hello! How can I help you today?",
    "allowed_tools": ["get_account_status", "create_ticket"],
    "policy": {
      "max_session_duration_minutes": 30,
      "rate_limit_per_minute": 10,
      "require_consent": true
    }
  },
  "expires_at": "2024-01-20T15:30:00Z"
}
```

### Refresh Token

```
POST /v1/sessions/{session_id}/refresh-token
```

**Response:**
```json
{
  "ephemeral_token": "new-ephemeral-token",
  "expires_at": "2024-01-20T15:35:00Z"
}
```

### End Session

```
POST /v1/sessions/{session_id}/end
```

**Response:**
```json
{
  "status": "ended"
}
```

## Error Responses

All errors follow this format:

```json
{
  "error": "Error message",
  "message": "Detailed error description"
}
```

### Status Codes

- `200 OK` - Success
- `201 Created` - Resource created
- `400 Bad Request` - Invalid request
- `401 Unauthorized` - Authentication required
- `404 Not Found` - Resource not found
- `500 Internal Server Error` - Server error

## WebRTC Signaling

WebRTC signaling is handled via WebSocket (to be implemented in Phase 1):

```
WS /v1/realtime/{session_id}
```

## Rate Limiting

Rate limits are enforced per tenant and user:
- Default: 10 requests per minute per user
- Configurable per tenant

Rate limit headers:
```
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1642680000
```