REST API Overview

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:

Header-based authentication (Recommended)
X-User-ID: user_abc123
Session-based authentication
- Uses Flask session cookies
- Set via Auth.js authentication flow

Core Endpoints

Authentication

POST /api/auth/register

{
  "email": "user@example.com",
  "password": "securepassword123",
  "name": "John Doe"
}

Response (201):

{
  "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

Authenticate with email and password. Request Body:

{
  "email": "user@example.com",
  "password": "securepassword123"
}

Response (200):

{
  "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:

X-User-ID: user_abc123

Request Body:

{
  "currentPassword": "oldpassword",
  "newPassword": "newsecurepassword"
}

Response (200):

{
  "message": "Password changed successfully"
}

Chat Sessions

GET /chat_api/sessions

Retrieve all chat sessions for the authenticated user. Headers:

X-User-ID: user_abc123

Response (200):

{
  "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:

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

Response (201):

{
  "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):

{
  "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:

{
  "title": "Updated Title",
  "messages": [...],
  "ui_state": {...}
}

DELETE /chat_api/sessions/:session_id

Soft delete a chat session. Response (200):

{
  "message": "Chat session deleted successfully"
}

Incidents (RCA)

GET /api/incidents

Get all incidents for the current user. Response (200):

{
  "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):

{
  "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:

{
  "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:

{
  "question": "What caused the high CPU usage?",
  "mode": "ask"
}

Response (202):

{
  "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):

{
  "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):

{
  "status": "alive"
}

GET /health/readiness

Kubernetes readiness probe. Response (200 or 503):

{
  "status": "ready"
}

Cloud Provider Endpoints

GCP

Initiate GCP OAuth flow. Request Body:

{
  "userId": "user_abc123"
}

Response:

{
  "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:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709294400

Error Responses

Standard Error Format

{
  "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

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

// 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

# 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"}'

​API Architecture

​Base URL

​Authentication

​Core Endpoints

​Authentication

​POST /api/auth/register

​POST /api/auth/login

​POST /api/auth/change-password

​Chat Sessions

​GET /chat_api/sessions

​POST /chat_api/sessions

​GET /chat_api/sessions/:session_id

​PUT /chat_api/sessions/:session_id

​DELETE /chat_api/sessions/:session_id

​Incidents (RCA)

​GET /api/incidents

​GET /api/incidents/:incident_id

​PATCH /api/incidents/:incident_id

​POST /api/incidents/:incident_id/chat

​Health Checks

​GET /health

​GET /health/liveness

​GET /health/readiness

​Cloud Provider Endpoints

​GCP

​POST /login

​GET /callback

​POST /api/gcp/force-disconnect

​AWS, Azure, and Other Providers

​Rate Limiting

​Error Responses

​Standard Error Format

​Common HTTP Status Codes

​CORS Configuration

​API Versioning

​Code Examples

​Python

​JavaScript/TypeScript

​cURL

API Architecture

Base URL

Authentication

Core Endpoints

Authentication

POST /api/auth/register

POST /api/auth/login

POST /api/auth/change-password

Chat Sessions

GET /chat_api/sessions

POST /chat_api/sessions

GET /chat_api/sessions/:session_id

PUT /chat_api/sessions/:session_id

DELETE /chat_api/sessions/:session_id

Incidents (RCA)

GET /api/incidents

GET /api/incidents/:incident_id

PATCH /api/incidents/:incident_id

POST /api/incidents/:incident_id/chat

Health Checks

GET /health

GET /health/liveness

GET /health/readiness

Cloud Provider Endpoints

GCP

POST /login

GET /callback

POST /api/gcp/force-disconnect

AWS, Azure, and Other Providers

Rate Limiting

Error Responses

Standard Error Format

Common HTTP Status Codes

CORS Configuration

API Versioning

Code Examples

Python

JavaScript/TypeScript

cURL