> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Arvo-AI/aurora/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API Overview

> Complete reference for Aurora REST API endpoints

## API Architecture

Aurora provides a comprehensive REST API built with Flask, organized into domain-specific blueprints. All endpoints are accessible via the main server running on port 5080.

### Base URL

```
http://localhost:5080  # Development
https://your-domain.com  # Production
```

### Authentication

All API requests require authentication via one of these methods:

1. **Header-based authentication** (Recommended)
   ```http theme={null}
   X-User-ID: user_abc123
   ```

2. **Session-based authentication**
   * Uses Flask session cookies
   * Set via Auth.js authentication flow

## Core Endpoints

### Authentication

#### POST /api/auth/register

Register a new user with email and password.

**Request Body:**

```json theme={null}
{
  "email": "user@example.com",
  "password": "securepassword123",
  "name": "John Doe"
}
```

**Response (201):**

```json theme={null}
{
  "id": "user_abc123",
  "email": "user@example.com",
  "name": "John Doe"
}
```

**Validation:**

* Password must be at least 8 characters
* Email must be unique
* Password is hashed using bcrypt

#### POST /api/auth/login

Authenticate with email and password.

**Request Body:**

```json theme={null}
{
  "email": "user@example.com",
  "password": "securepassword123"
}
```

**Response (200):**

```json theme={null}
{
  "id": "user_abc123",
  "email": "user@example.com",
  "name": "John Doe"
}
```

**Security Features:**

* Constant-time password comparison to prevent timing attacks
* bcrypt password hashing with salt
* Failed login attempts logged

#### POST /api/auth/change-password

Change user password (requires authentication).

**Headers:**

```http theme={null}
X-User-ID: user_abc123
```

**Request Body:**

```json theme={null}
{
  "currentPassword": "oldpassword",
  "newPassword": "newsecurepassword"
}
```

**Response (200):**

```json theme={null}
{
  "message": "Password changed successfully"
}
```

### Chat Sessions

#### GET /chat\_api/sessions

Retrieve all chat sessions for the authenticated user.

**Headers:**

```http theme={null}
X-User-ID: user_abc123
```

**Response (200):**

```json theme={null}
{
  "sessions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Deploy to GKE",
      "created_at": "2024-03-01T10:00:00Z",
      "updated_at": "2024-03-01T10:30:00Z",
      "message_count": 15,
      "status": "active",
      "ui_state": {
        "selectedModel": "anthropic/claude-3.5-sonnet",
        "selectedMode": "agent",
        "selectedProviders": ["gcp", "aws"]
      }
    }
  ]
}
```

#### POST /chat\_api/sessions

Create a new chat session.

**Request Body:**

```json theme={null}
{
  "title": "Deploy to GKE",
  "messages": [],
  "ui_state": {
    "selectedModel": "anthropic/claude-3.5-sonnet",
    "selectedMode": "agent"
  }
}
```

**Response (201):**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Deploy to GKE",
  "messages": [],
  "created_at": "2024-03-01T10:00:00Z",
  "status": "active"
}
```

#### GET /chat\_api/sessions/:session\_id

Get a specific chat session with full message history.

**Response (200):**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Deploy to GKE",
  "messages": [
    {
      "sender": "user",
      "text": "Deploy my app to GKE",
      "timestamp": "2024-03-01T10:00:00Z"
    },
    {
      "sender": "assistant",
      "text": "I'll help you deploy to GKE...",
      "timestamp": "2024-03-01T10:00:05Z"
    }
  ],
  "status": "active"
}
```

#### PUT /chat\_api/sessions/:session\_id

Update a chat session.

**Request Body:**

```json theme={null}
{
  "title": "Updated Title",
  "messages": [...],
  "ui_state": {...}
}
```

#### DELETE /chat\_api/sessions/:session\_id

Soft delete a chat session.

**Response (200):**

```json theme={null}
{
  "message": "Chat session deleted successfully"
}
```

### Incidents (RCA)

#### GET /api/incidents

Get all incidents for the current user.

**Response (200):**

```json theme={null}
{
  "incidents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "sourceType": "grafana",
      "sourceAlertId": "12345",
      "status": "investigating",
      "severity": "critical",
      "alert": {
        "title": "High CPU Usage",
        "service": "api-server",
        "source": "grafana",
        "sourceUrl": "https://grafana.com"
      },
      "auroraStatus": "running",
      "summary": "Investigating high CPU usage...",
      "startedAt": "2024-03-01T10:00:00Z",
      "correlatedAlertCount": 3,
      "affectedServices": ["api-server", "database"]
    }
  ]
}
```

#### GET /api/incidents/:incident\_id

Get detailed information about a specific incident.

**Response (200):**

```json theme={null}
{
  "incident": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "sourceType": "grafana",
    "status": "investigating",
    "alert": {
      "title": "High CPU Usage",
      "rawPayload": "{...}",
      "triggeredAt": "2024-03-01T10:00:00Z"
    },
    "suggestions": [
      {
        "id": "1",
        "title": "Check pod resource limits",
        "description": "Review Kubernetes resource limits",
        "type": "diagnostic",
        "risk": "safe",
        "command": "kubectl get pods -o yaml"
      }
    ],
    "streamingThoughts": [
      {
        "id": "1",
        "content": "Analyzing CPU metrics...",
        "timestamp": "2024-03-01T10:00:05Z",
        "type": "analysis"
      }
    ],
    "citations": [
      {
        "id": "1",
        "key": "1",
        "toolName": "kubectl_get",
        "command": "kubectl get pods",
        "output": "...",
        "executedAt": "2024-03-01T10:00:10Z"
      }
    ],
    "correlatedAlerts": [...],
    "chatSessions": [...]
  }
}
```

#### PATCH /api/incidents/:incident\_id

Update incident status or properties.

**Request Body:**

```json theme={null}
{
  "status": "resolved",
  "auroraStatus": "complete",
  "summary": "Issue resolved by scaling pods",
  "activeTab": "chat"
}
```

**Allowed Values:**

* `status`: "investigating", "analyzed", "merged", "resolved"
* `auroraStatus`: "idle", "running", "complete", "error"
* `activeTab`: "thoughts", "chat"

#### POST /api/incidents/:incident\_id/chat

Ask a question about an incident (creates background chat task).

**Query Parameters:**

* `session_id` (optional): Continue existing chat session

**Request Body:**

```json theme={null}
{
  "question": "What caused the high CPU usage?",
  "mode": "ask"
}
```

**Response (202):**

```json theme={null}
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "is_new_session": true
}
```

### Health Checks

#### GET /health

Comprehensive health check for all services.

**Response (200 or 503):**

```json theme={null}
{
  "overall_status": "healthy",
  "timestamp": "2024-03-01T10:00:00Z",
  "response_time_ms": 150.25,
  "checks": {
    "database": {
      "status": "healthy",
      "message": "Database connection successful"
    },
    "redis": {
      "status": "healthy",
      "message": "Redis connection successful"
    },
    "weaviate": {
      "status": "healthy",
      "message": "Weaviate connection successful"
    },
    "celery": {
      "status": "healthy",
      "message": "2 Celery workers active"
    },
    "chatbot_websocket": {
      "status": "healthy",
      "message": "Chatbot connection successful"
    }
  }
}
```

#### GET /health/liveness

Kubernetes liveness probe.

**Response (200):**

```json theme={null}
{
  "status": "alive"
}
```

#### GET /health/readiness

Kubernetes readiness probe.

**Response (200 or 503):**

```json theme={null}
{
  "status": "ready"
}
```

## Cloud Provider Endpoints

### GCP

#### POST /login

Initiate GCP OAuth flow.

**Request Body:**

```json theme={null}
{
  "userId": "user_abc123"
}
```

**Response:**

```json theme={null}
{
  "login_url": "https://accounts.google.com/o/oauth2/auth?..."
}
```

#### GET /callback

Handle OAuth callback from Google.

#### POST /api/gcp/force-disconnect

Disconnect GCP account and clear credentials.

### AWS, Azure, and Other Providers

Similar patterns apply for other cloud providers with provider-specific authentication flows.

## Rate Limiting

Aurora implements rate limiting to protect against abuse:

* **Default rate**: 100 requests per minute per user
* **Chat endpoints**: 20 requests per minute
* **Health endpoints**: Exempt from rate limiting

**Rate Limit Headers:**

```http theme={null}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709294400
```

## Error Responses

### Standard Error Format

```json theme={null}
{
  "error": "Description of what went wrong",
  "code": "ERROR_CODE"
}
```

### Common HTTP Status Codes

* `200 OK`: Successful request
* `201 Created`: Resource created successfully
* `202 Accepted`: Request accepted for async processing
* `400 Bad Request`: Invalid request format or parameters
* `401 Unauthorized`: Authentication required
* `403 Forbidden`: Insufficient permissions
* `404 Not Found`: Resource not found
* `409 Conflict`: Resource already exists
* `429 Too Many Requests`: Rate limit exceeded
* `500 Internal Server Error`: Server error
* `503 Service Unavailable`: Service temporarily unavailable

## CORS Configuration

Aurora is configured with CORS support for cross-origin requests:

**Allowed Origins:**

* Configured via `FRONTEND_URL` environment variable
* Credentials supported: `true`

**Allowed Methods:**

* GET, POST, PUT, DELETE, OPTIONS, PATCH

**Allowed Headers:**

* Content-Type, X-Provider, X-Requested-With, X-User-ID, Authorization, X-Provider-Preference

## API Versioning

Currently, Aurora API does not use explicit versioning. Breaking changes are avoided, and new features are added in a backward-compatible manner.

## Code Examples

### Python

```python theme={null}
import requests

# Authentication
response = requests.post(
    "http://localhost:5080/api/auth/login",
    json={
        "email": "user@example.com",
        "password": "password123"
    }
)
user = response.json()

# Create chat session
response = requests.post(
    "http://localhost:5080/chat_api/sessions",
    headers={"X-User-ID": user["id"]},
    json={
        "title": "Deploy to GKE",
        "messages": []
    }
)
session = response.json()
```

### JavaScript/TypeScript

```typescript theme={null}
// Authentication
const response = await fetch('http://localhost:5080/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
});
const user = await response.json();

// Get chat sessions
const sessions = await fetch('http://localhost:5080/chat_api/sessions', {
  headers: { 'X-User-ID': user.id }
});
const data = await sessions.json();
```

### cURL

```bash theme={null}
# Login
curl -X POST http://localhost:5080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123"}'

# Get incidents
curl http://localhost:5080/api/incidents \
  -H "X-User-ID: user_abc123"

# Update incident
curl -X PATCH http://localhost:5080/api/incidents/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-User-ID: user_abc123" \
  -H "Content-Type: application/json" \
  -d '{"status":"resolved"}'
```