API_RESPONSES.md

# MasterLLM API Response Schemas (Updated)

This document outlines the **ACTUAL** JSON response structures for the `api_routes_v2.py` endpoints after implementing all API response corrections. All fields shown reflect the current implementation.

**Last Updated:** January 3, 2026  
**Implementation Status:** 100% Complete ✅

---

## 1. Session Management

### `GET /api/v2/sessions`

**Description:** Returns a list of all chat sessions, sorted by `last_activity` (descending).

**Parameters:**
- `limit` (int, default=100) - Maximum sessions to return
- `skip` (int, default=0) - Pagination offset
- `include_stats` (bool, default=False) - Include detailed statistics

**Response (Default - `include_stats=False`):**

```json
{
  "sessions": [
    {
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": null,
      "last_activity": null
    },
    {
      "session_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "created_at": null,
      "last_activity": null
    }
  ],
  "pagination": {
    "total": 2,
    "returned": 2,
    "limit": 100,
    "skip": 0,
    "has_more": false
  }
}
```

**Response (with `include_stats=True`):**

```json
{
  "sessions": [
    {
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "user_12345",
      "created_at": "2023-11-15T08:30:00.000000Z",
      "last_activity": "2023-11-15T09:45:00.000000Z",
      "state": "completed",
      "chat_name": "Q3 Financial Report Analysis",
      "stats": {
        "message_count": 12
      },
      "total_messages": 12,
      "pipeline_executions_count": 3
    }
  ],
  "pagination": {
    "total": 1,
    "returned": 1,
    "limit": 100,
    "skip": 0,
    "has_more": false
  }
}
```

**Key Changes:**
- ✅ Sessions sorted by `last_activity` (descending)
- ✅ `current_file` field removed
- ✅ `state` reflects actual pipeline/conversation status

---

### `GET /api/v2/sessions/{session_id}/history`

**Description:** Returns the full message history and pipeline history for a specific session.

**Parameters:**
- `limit` (int, default=50) - Maximum messages to return

**Response:**

```json
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "history": [
    {
      "message_id": "msg_a1b2c3d4e5f6",
      "role": "user",
      "content": "Uploaded file: report.pdf",
      "timestamp": "2023-11-15T08:30:00Z",
      "file_data": {
        "has_file": true,
        "file_name": "report.pdf",
        "file_url": "https://s3.amazonaws.com/bucket/key?signature=..."
      },
      "file": true,
      "fileName": "report.pdf",
      "fileUrl": "https://s3.amazonaws.com/bucket/key?signature=..."
    },
    {
      "message_id": "msg_g7h8i9j0k1l2",
      "role": "assistant",
      "content": "File uploaded successfully.",
      "timestamp": "2023-11-15T08:30:05Z",
      "file_data": {
        "has_file": false
      },
      "file": false,
      "fileName": null,
      "fileUrl": null
    },
    {
      "message_id": "msg_m3n4o5p6q7r8",
      "role": "user",
      "content": "Summarize this document.",
      "timestamp": "2023-11-15T08:31:00Z",
      "file_data": {
        "has_file": false
      },
      "file": false,
      "fileName": null,
      "fileUrl": null
    }
  ],
  "count": 3,
  "limit": 50,
  "chat_name": "Q3 Financial Report Analysis",
  "pipelines_history": [
    {
      "pipeline_id": "pipe_987654321",
      "pipeline_name": "Document Summarization",
      "status": "completed",
      "created_at": "2023-11-15T08:31:05Z",
      "created_from": "request",
      "model_provider": "bedrock",
      "model_name": "anthropic.claude-3-sonnet-20240229-v1:0",
      "result": "The Q3 report indicates a 15% growth in revenue...",
      "hasError": false,
      "error": null,
      "updated_at": "2023-11-15T08:32:00Z",
      "tools": ["extract_text", "summarize_text"],
      "component_count": 2,
      "components": [
        {
          "component_id": "comp_abc123def456",
          "component_name": "extract_text",
          "order": 1,
          "status": "completed",
          "started_at": "2023-11-15T08:31:10Z",
          "completed_at": "2023-11-15T08:31:25Z",
          "component_output": {
            "text": "Full extracted text from the PDF...",
            "pages_processed": 15
          },
          "hasError": false,
          "error": null,
          "success_message": "Text extraction completed",
          "metadata": {
            "duration_ms": 15000,
            "pages_count": 15
          }
        },
        {
          "component_id": "comp_ghi789jkl012",
          "component_name": "summarize_text",
          "order": 2,
          "status": "completed",
          "started_at": "2023-11-15T08:31:26Z",
          "completed_at": "2023-11-15T08:32:00Z",
          "component_output": {
            "summary": "The Q3 report indicates a 15% growth in revenue...",
            "word_count": 150
          },
          "hasError": false,
          "error": null,
          "success_message": "Summarization completed",
          "metadata": {
            "duration_ms": 34000,
            "tokens_used": 250
          }
        }
      ]
    }
  ]
}
```

**Key Changes:**
- ✅ All messages include `message_id`
- ✅ Pipelines use `result` instead of `result_preview`
- ✅ `pipeline_s3_key` removed from response
- ✅ Added `hasError` and structured `error` fields
- ✅ Components include `component_id`, `status`, `component_output`, `hasError`, `error`, `metadata`
- ✅ Presigned URLs valid for 7 days

---

### `GET /api/v2/sessions/{session_id}/pipelines`

**Description:** Get all pipeline executions for a session with full component details.

**NEW ENDPOINT** ✨

**Response:**

```json
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "pipelines": [
    {
      "execution_id": "exec_abc123",
      "pipeline_id": "pipe_987654321",
      "pipeline_name": "Document Summarization",
      "status": "completed",
      "created_at": "2023-11-15T08:31:05Z",
      "completed_at": "2023-11-15T08:32:00Z",
      "created_from": "request",
      "executor": "bedrock",
      "result": "The Q3 report indicates a 15% growth in revenue...",
      "hasError": false,
      "error": null,
      "output_id": "output_xyz789abc123",
      "final_output_url": "https://s3.amazonaws.com/bucket/outputs/exec_abc123/final_output.json?signature=...",
      "final_output_presigned_expires_at": "2023-11-22T08:32:00Z",
      "components": [
        {
          "component_id": "comp_abc123def456",
          "component_name": "extract_text",
          "order": 1,
          "status": "completed",
          "component_output": {
            "text": "Full extracted text...",
            "pages_processed": 15
          },
          "hasError": false,
          "error": null,
          "metadata": {
            "duration_ms": 15000
          }
        },
        {
          "component_id": "comp_ghi789jkl012",
          "component_name": "summarize_text",
          "order": 2,
          "status": "completed",
          "component_output": {
            "summary": "The Q3 report indicates...",
            "word_count": 150
          },
          "hasError": false,
          "error": null,
          "metadata": {
            "duration_ms": 34000,
            "tokens_used": 250
          }
        }
      ]
    }
  ]
}
```

**Key Features:**
- ✅ Full component details with IDs and outputs
- ✅ `output_id` for download tracking
- ✅ `final_output_url` with 7-day validity
- ✅ Internal S3 keys removed
- ✅ Component-level error tracking

---

### `DELETE /api/v2/sessions/{session_id}`

**Description:** Deletes a session and its S3 conversation history.

**Response:**

```json
{
  "status": "deleted",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

---

### `PUT /api/v2/sessions/{session_id}/rename`

**Description:** Renames a session.

**Response:**

```json
{
  "success": true,
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "new_name": "New Chat Title"
}
```

---

## 2. Unified Chat (Non-Streaming)

### `POST /api/v2/chat/unified`

**Description:** Main interaction endpoint for chat, pipeline generation, and execution.

#### **Scenario 1: Casual Chat / Question**

**Response:**

```json
{
  "message_id": "msg_s9t0u1v2w3x4",
  "assistant_response": "I am MasterLLM, an advanced AI agent designed to help you process documents.",
  "output": {},
  "final_output": null,
  "hasError": false,
  "exception": null,
  "api_response": {
    "type": "informational_response",
    "message": "I am MasterLLM, an advanced AI agent designed to help you process documents.",
    "intent_classification": {
      "intent": "question",
      "confidence": 0.98,
      "requires_pipeline": false
    }
  },
  "intent": {
    "intent": "question",
    "confidence": 0.98,
    "requires_pipeline": false
  },
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "initial",
  "file": false,
  "fileName": null,
  "fileUrl": null
}
```

#### **Scenario 2: File Uploaded (Only)**

**Response:**

```json
{
  "message_id": "msg_y5z6a7b8c9d0",
  "assistant_response": "📁 File uploaded successfully. Tell me what you'd like to do with it (e.g., extract text, get tables, summarize).",
  "output": {},
  "final_output": null,
  "hasError": false,
  "exception": null,
  "api_response": {
    "type": "file_uploaded",
    "file": {
      "bucket": "my-s3-bucket",
      "key": "masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf",
      "s3_uri": "s3://my-s3-bucket/masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf",
      "presigned_url": "https://s3.amazonaws.com/my-s3-bucket/masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf?signature=...",
      "presigned_expires_at": "2023-11-22T08:30:00.000000Z"
    },
    "next_action": "send_instruction"
  },
  "intent": {
    "intent": "file_uploaded"
  },
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "initial",
  "file": true,
  "fileName": "report.pdf",
  "fileUrl": "https://s3.amazonaws.com/my-s3-bucket/..."
}
```

#### **Scenario 3: Pipeline Generated (Proposal)**

**Response:**

```json
{
  "message_id": "msg_e1f2g3h4i5j6",
  "assistant_response": "🎯 **Pipeline Created: Document Summarization**\nHere's what I'll do:\n  1. extract_text\n  2. summarize_text\n**Ready to proceed?**\n- Type 'approve' or 'yes' to execute\n- Type 'reject' or 'no' to cancel\n- Describe changes to modify the plan",
  "output": {
    "pipeline_id": "pipe_123abc",
    "pipeline_name": "Document Summarization",
    "steps_count": 2,
    "tools": ["extract_text", "summarize_text"]
  },
  "final_output": null,
  "hasError": false,
  "exception": null,
  "api_response": {
    "type": "pipeline_generated",
    "message": "Pipeline successfully created",
    "pipeline": {
      "pipeline_id": "pipe_123abc",
      "pipeline_name": "Document Summarization",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2023-11-15T08:35:00Z",
      "_generator": "Claude 3.5 Sonnet",
      "_model": "claude-3-5-sonnet-20240620",
      "components": [
        {
          "component_id": "comp_k7l8m9n0o1p2",
          "tool_name": "extract_text",
          "args": { "pages": "all" }
        },
        {
          "component_id": "comp_q3r4s5t6u7v8",
          "tool_name": "summarize_text",
          "args": { "style": "brief" }
        }
      ]
    },
    "required_action": "approval"
  },
  "intent": {
    "intent": "pipeline_request",
    "requires_pipeline": true,
    "confidence": 0.99
  },
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "pipeline_proposed",
  "file": true,
  "fileName": "report.pdf",
  "fileUrl": "https://s3.amazonaws.com/..."
}
```

#### **Scenario 4: Pipeline Completed (Execution Success)**

**Response:**

```json
{
  "message_id": "msg_w9x0y1z2a3b4",
  "assistant_response": "🎉 Pipeline completed successfully!",
  "output": {
    "component_summary": "Pipeline executed successfully",
    "steps": 2
  },
  "final_output": {
    "text": "The Q3 financial report highlights a strong performance with a 15% revenue increase driven by the new product line launch. Operating expenses were reduced by 5% due to efficiency improvements. The outlook for Q4 is positive with projected growth of 10%.",
    "output_id": "output_c5d6e7f8g9h0",
    "download_url": "https://s3.amazonaws.com/bucket/outputs/exec_abc123/final_output.json?signature=..."
  },
  "hasError": false,
  "exception": null,
  "api_response": {
    "type": "pipeline_completed",
    "result": {
      "pipeline_id": "pipe_123abc",
      "status": "completed",
      "components_executed": [
        {
          "component_id": "comp_k7l8m9n0o1p2",
          "tool_name": "extract_text",
          "status": "completed",
          "component_output": {
            "text": "Full extracted text...",
            "pages_processed": 15
          }
        },
        {
          "component_id": "comp_q3r4s5t6u7v8",
          "tool_name": "summarize_text",
          "status": "completed",
          "component_output": {
            "summary": "The Q3 financial report highlights..."
          }
        }
      ]
    },
    "pipeline": {
      "pipeline_id": "pipe_123abc",
      "pipeline_name": "Document Summarization",
      "components": [
        { "component_id": "comp_k7l8m9n0o1p2", "tool_name": "extract_text" },
        { "component_id": "comp_q3r4s5t6u7v8", "tool_name": "summarize_text" }
      ]
    }
  },
  "intent": {
    "intent": "pipeline_execute"
  },
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "initial",
  "file": true,
  "fileName": "report.pdf",
  "fileUrl": "https://s3.amazonaws.com/..."
}
```

**Key Changes:**
- ✅ `message_id` in all responses
- ✅ `hasError` flag
- ✅ `output_id` and `download_url` in `final_output`
- ✅ Component IDs in pipeline proposals
- ✅ Removed nested `result` object from `final_output`

#### **Scenario 5: Error**

**Response:**

```json
{
  "message_id": "msg_i1j2k3l4m5n6",
  "assistant_response": "❌ Pipeline execution failed: ValueError: Input file is empty.",
  "output": {},
  "final_output": null,
  "hasError": true,
  "exception": "ValueError: Input file is empty.",
  "api_response": {
    "type": "error",
    "error_code": "PIPELINE_EXECUTION_FAILED",
    "message": "ValueError: Input file is empty.",
    "failed_component": {
      "component_id": "comp_k7l8m9n0o1p2",
      "tool_name": "extract_text",
      "error": {
        "message": "ValueError: Input file is empty.",
        "error_code": "FILE_READ_ERROR"
      }
    }
  },
  "intent": {
    "intent": "pipeline_execute"
  },
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "initial",
  "file": true,
  "fileName": "report.pdf",
  "fileUrl": "https://s3.amazonaws.com/..."
}
```

**Key Changes:**
- ✅ `hasError` set to `true`
- ✅ Component-level error details in `failed_component`
- ✅ Structured error with `error_code` and `message`

---

## 3. Unified Chat (Streaming)

### `POST /api/v2/chat/unified/stream`

**Description:** Streaming version of the unified chat. Returns **NDJSON** (Newlines Delimited JSON).

**Event Type: `status`**

```json
{
  "type": "status",
  "message": "Analyzing request and creating a pipeline...",
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "initial"
}
```

**Event Type: `assistant_final` (Typical Chat Response)**

```json
{
  "type": "assistant_final",
  "content": "Hello! How can I help you today?",
  "intent": {
    "intent": "casual_chat",
    "confidence": 0.99
  },
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "initial"
}
```

**Event Type: `assistant_final` (Execution Completed)**

```json
{
  "type": "assistant_final",
  "content": "🎉 Pipeline Completed Successfully!\n- Pipeline: Document Summarization\n- Total Steps: 2\n- Successful: 2\n- Executor: Bedrock Agent\n\nThe Q3 financial report highlights...",
  "result": {
    "summary": "The Q3 financial report highlights...",
    "full_text": "..."
  },
  "output": {
    "component_summary": "Executed 2 steps successfully",
    "steps_completed": 2,
    "total_steps": 2
  },
  "final_output": {
    "text": "The Q3 financial report highlights...",
    "output_id": "output_o9p0q1r2s3t4",
    "download_url": "https://s3.amazonaws.com/..."
  },
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "initial"
}
```

---

## 4. File Management

### `POST /api/v2/chats/{chat_id}/upload`

**Description:** Direct file upload endpoint.

**Response:**

```json
{
  "status": "success",
  "message": "File uploaded to S3",
  "file": {
    "bucket": "my-s3-bucket",
    "key": "masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf",
    "s3_uri": "s3://my-s3-bucket/masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf",
    "presigned_url": "https://s3.amazonaws.com/my-s3-bucket/masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf?signature=...",
    "presigned_expires_at": "2023-11-22T08:30:00.000000Z"
  },
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "next_action": "💬 Now tell me what you'd like to do with this document"
}
```

**Key Changes:**
- ✅ Presigned URLs valid for 7 days

---

## 5. System

### `POST /api/v2/chats`

**Description:** Create a new empty chat session.

**Response:**

```json
{
  "chat_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### `GET /api/v2/health`

**Description:** Health check.

**Response:**

```json
{
  "status": "ok",
  "service": "MasterLLM v2.0",
  "time": "2023-11-15T08:30:00.000000Z"
}
```

---

## Summary of Changes

### ✅ New Fields Added
- `message_id` - Unique identifier for all messages (format: `msg_xxxxxxxxxxxx`)
- `component_id` - Unique identifier for pipeline components (format: `comp_xxxxxxxxxxxx`)
- `output_id` - Unique identifier for pipeline outputs (format: `output_xxxxxxxxxxxx`)
- `hasError` - Boolean flag for error detection
- `error` - Structured error object with `message`, `error_code`, `details`
- `component_output` - Actual output from component execution
- `download_url` - Direct download URL for pipeline results
- `failed_component` - Component-level error details in error responses
- `metadata` - Component execution metadata (duration, tokens, etc.)

### ✅ Fields Renamed
- `result_preview` → `result`

### ✅ Fields Removed
- `current_file` (from session list response)
- `pipeline_s3_key` (internal field, not exposed in API)
- Nested `result` object in `final_output` (simplified structure)

### ✅ New Endpoints
- `GET /api/v2/sessions/{session_id}/pipelines` - Get all pipelines for a session

### ✅ Behavioral Changes
- Sessions sorted by `last_activity` (descending)
- Presigned URLs valid for 7 days (604800 seconds)
- Component-level error tracking and reporting
- State field dynamically reflects pipeline/conversation status

---

## ID Formats

All IDs follow consistent formats for easy identification:

- **Message IDs:** `msg_xxxxxxxxxxxx` (12 hex characters)
- **Component IDs:** `comp_xxxxxxxxxxxx` (12 hex characters)
- **Output IDs:** `output_xxxxxxxxxxxx` (12 hex characters)
- **Session IDs:** Standard UUID v4 format
- **Pipeline IDs:** `pipe_` prefix or UUID format

---

## Error Handling

All error responses now include:

1. **Top-level `hasError` flag** - Quick error detection
2. **Structured `error` object** - Detailed error information
3. **Component-level errors** - Identify which component failed
4. **Error codes** - Machine-readable error classification

Example error structure:
```json
{
  "hasError": true,
  "error": {
    "message": "Detailed error message",
    "error_code": "ERROR_TYPE",
    "details": {
      "additional": "context"
    }
  },
  "failed_component": {
    "component_id": "comp_xxxxxxxxxxxx",
    "tool_name": "tool_name",
    "error": {...}
  }
}
```

---

**Document Version:** 2.0  
**Implementation Date:** January 3, 2026  
**Status:** Production Ready ✅