# Chatbot Creation Framework - API Interface Specifications

## OpenAPI Specification Overview

This document provides detailed API specifications for the Chatbot Creation Framework, following OpenAPI 3.0 standards.

## Base Configuration

```yaml
openapi: 3.0.3
info:
  title: Chatbot Creation Framework API
  description: API for managing chatbot projects with multimodal RAG capabilities
  version: 1.0.0
  contact:
    name: API Support
    email: support@chatbotframework.com
servers:
  - url: http://localhost:3000/api
    description: Development server
  - url: https://api.chatbotframework.com
    description: Production server
```

## Authentication Endpoints

### POST /auth/signup
```yaml
/auth/signup:
  post:
    summary: User registration
    tags: [Authentication]
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [email, password, name]
            properties:
              email:
                type: string
                format: email
                example: user@example.com
              password:
                type: string
                minLength: 8
                example: SecurePass123!
              name:
                type: string
                example: John Doe
    responses:
      201:
        description: User created successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  $ref: '#/components/schemas/User'
                message:
                  type: string
                  example: User created successfully
      400:
        $ref: '#/components/responses/BadRequest'
      409:
        description: User already exists
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Error'
```

### POST /auth/signin
```yaml
/auth/signin:
  post:
    summary: User login
    tags: [Authentication]
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [email, password]
            properties:
              email:
                type: string
                format: email
              password:
                type: string
    responses:
      200:
        description: Login successful
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  $ref: '#/components/schemas/User'
                accessToken:
                  type: string
                refreshToken:
                  type: string
      401:
        $ref: '#/components/responses/Unauthorized'
```

## Project Management Endpoints

### GET /projects
```yaml
/projects:
  get:
    summary: List user's chatbot projects
    tags: [Projects]
    security:
      - bearerAuth: []
    parameters:
      - name: page
        in: query
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: limit
        in: query
        schema:
          type: integer
          default: 10
          minimum: 1
          maximum: 100
      - name: status
        in: query
        schema:
          type: string
          enum: [active, inactive, processing]
    responses:
      200:
        description: Projects retrieved successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                projects:
                  type: array
                  items:
                    $ref: '#/components/schemas/ChatbotProject'
                totalCount:
                  type: integer
                page:
                  type: integer
                limit:
                  type: integer
                hasMore:
                  type: boolean
      401:
        $ref: '#/components/responses/Unauthorized'
```

### POST /projects
```yaml
  post:
    summary: Create new chatbot project
    tags: [Projects]
    security:
      - bearerAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [name]
            properties:
              name:
                type: string
                minLength: 3
                maxLength: 100
                example: Customer Support Bot
              description:
                type: string
                maxLength: 500
                example: AI assistant for customer inquiries
              systemPrompt:
                type: string
                maxLength: 2000
                example: You are a helpful customer support assistant
              n8nChatUrl:
                type: string
                format: uri
                example: https://n8n.example.com/webhook/chat
              n8nWebhookUrl:
                type: string
                format: uri
                example: https://n8n.example.com/webhook/process
    responses:
      201:
        description: Project created successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                project:
                  $ref: '#/components/schemas/ChatbotProject'
                message:
                  type: string
      400:
        $ref: '#/components/responses/BadRequest'
      401:
        $ref: '#/components/responses/Unauthorized'
```

### GET /projects/{id}
```yaml
/projects/{id}:
  get:
    summary: Get project details
    tags: [Projects]
    security:
      - bearerAuth: []
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    responses:
      200:
        description: Project details retrieved
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatbotProject'
      404:
        $ref: '#/components/responses/NotFound'
      401:
        $ref: '#/components/responses/Unauthorized'
```

### PUT /projects/{id}
```yaml
  put:
    summary: Update project configuration
    tags: [Projects]
    security:
      - bearerAuth: []
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                type: string
                minLength: 3
                maxLength: 100
              description:
                type: string
                maxLength: 500
              systemPrompt:
                type: string
                maxLength: 2000
              n8nChatUrl:
                type: string
                format: uri
              n8nWebhookUrl:
                type: string
                format: uri
    responses:
      200:
        description: Project updated successfully
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatbotProject'
      400:
        $ref: '#/components/responses/BadRequest'
      404:
        $ref: '#/components/responses/NotFound'
      401:
        $ref: '#/components/responses/Unauthorized'
```

### DELETE /projects/{id}
```yaml
  delete:
    summary: Delete project and all resources
    tags: [Projects]
    security:
      - bearerAuth: []
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    responses:
      200:
        description: Project deleted successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                success:
                  type: boolean
                message:
                  type: string
      404:
        $ref: '#/components/responses/NotFound'
      401:
        $ref: '#/components/responses/Unauthorized'
```

## Document Management Endpoints

### GET /projects/{id}/documents
```yaml
/projects/{projectId}/documents:
  get:
    summary: List project documents
    tags: [Documents]
    security:
      - bearerAuth: []
    parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
      - name: status
        in: query
        schema:
          type: string
          enum: [pending, processing, completed, failed]
    responses:
      200:
        description: Documents retrieved successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                documents:
                  type: array
                  items:
                    $ref: '#/components/schemas/Document'
                totalCount:
                  type: integer
```

### POST /projects/{id}/documents
```yaml
  post:
    summary: Upload new document
    tags: [Documents]
    security:
      - bearerAuth: []
    parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [file]
            properties:
              file:
                type: string
                format: binary
                description: Document file to upload
              filename:
                type: string
                description: Custom filename (optional)
    responses:
      201:
        description: Document uploaded successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                document:
                  $ref: '#/components/schemas/Document'
                processingJobId:
                  type: string
                  format: uuid
      400:
        $ref: '#/components/responses/BadRequest'
      413:
        description: File too large
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Error'
```

### DELETE /documents/{id}
```yaml
/documents/{documentId}:
  delete:
    summary: Delete document
    tags: [Documents]
    security:
      - bearerAuth: []
    parameters:
      - name: documentId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    responses:
      200:
        description: Document deleted successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                success:
                  type: boolean
                message:
                  type: string
```

### POST /documents/{id}/process
```yaml
  post:
    summary: Trigger document processing
    tags: [Documents]
    security:
      - bearerAuth: []
    parameters:
      - name: documentId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              forceReprocess:
                type: boolean
                default: false
    responses:
      200:
        description: Processing triggered
        content:
          application/json:
            schema:
              type: object
              properties:
                jobId:
                  type: string
                  format: uuid
                status:
                  type: string
                  enum: [queued, processing]
```

## Chat Endpoints

### POST /projects/{id}/chat
```yaml
/projects/{projectId}/chat:
  post:
    summary: Send chat message
    tags: [Chat]
    security:
      - bearerAuth: []
    parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [message]
            properties:
              message:
                type: string
                maxLength: 4000
                example: How can I reset my password?
              conversationId:
                type: string
                format: uuid
                description: Optional conversation ID for context
              context:
                type: object
                description: Additional context data
    responses:
      200:
        description: Response generated successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                response:
                  type: string
                conversationId:
                  type: string
                  format: uuid
                messageId:
                  type: string
                  format: uuid
                context:
                  type: object
                sources:
                  type: array
                  items:
                    type: object
                    properties:
                      documentId:
                        type: string
                        format: uuid
                      content:
                        type: string
                      similarity:
                        type: number
                        format: float
```

### GET /projects/{id}/conversations
```yaml
/projects/{projectId}/conversations:
  get:
    summary: Get conversation history
    tags: [Chat]
    security:
      - bearerAuth: []
    parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
    responses:
      200:
        description: Conversations retrieved
        content:
          application/json:
            schema:
              type: object
              properties:
                conversations:
                  type: array
                  items:
                    $ref: '#/components/schemas/Conversation'
```

### GET /conversations/{id}/messages
```yaml
/conversations/{conversationId}/messages:
  get:
    summary: Get conversation messages
    tags: [Chat]
    security:
      - bearerAuth: []
    parameters:
      - name: conversationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
    responses:
      200:
        description: Messages retrieved
        content:
          application/json:
            schema:
              type: object
              properties:
                messages:
                  type: array
                  items:
                    $ref: '#/components/schemas/Message'
```

## Public Chat API (for chatbot integration)

### POST /public/chat/{projectId}
```yaml
/public/chat/{projectId}:
  post:
    summary: Public chat endpoint for chatbot integration
    tags: [Public API]
    security:
      - apiKey: []
    parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [message]
            properties:
              message:
                type: string
                maxLength: 4000
              sessionId:
                type: string
                description: Client-provided session identifier
              metadata:
                type: object
                description: Additional metadata
    responses:
      200:
        description: Chat response
        content:
          application/json:
            schema:
              type: object
              properties:
                response:
                  type: string
                sessionId:
                  type: string
                sources:
                  type: array
                  items:
                    type: object
      401:
        description: Invalid API key
      429:
        description: Rate limit exceeded
```

## Webhook Endpoints

### POST /webhooks/n8n/{projectId}
```yaml
/webhooks/n8n/{projectId}:
  post:
    summary: n8n processing status webhook
    tags: [Webhooks]
    parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [executionId, status]
            properties:
              executionId:
                type: string
                description: n8n execution ID
              documentId:
                type: string
                format: uuid
              status:
                type: string
                enum: [started, completed, failed]
              result:
                type: object
                description: Processing results
              error:
                type: string
                description: Error message if failed
    responses:
      200:
        description: Webhook processed successfully
      400:
        $ref: '#/components/responses/BadRequest'
```

## Data Schemas

### User Schema
```yaml
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        image:
          type: string
          format: uri
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
```

### ChatbotProject Schema
```yaml
    ChatbotProject:
      type: object
      properties:
        id:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        systemPrompt:
          type: string
        n8nChatUrl:
          type: string
          format: uri
        n8nWebhookUrl:
          type: string
          format: uri
        databaseName:
          type: string
        minioBucketName:
          type: string
        status:
          type: string
          enum: [active, inactive, processing]
        documentCount:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
```

### Document Schema
```yaml
    Document:
      type: object
      properties:
        id:
          type: string
          format: uuid
        chatbotProjectId:
          type: string
          format: uuid
        filename:
          type: string
        originalFilename:
          type: string
        fileType:
          type: string
          enum: [pdf, markdown, docx, txt]
        fileSize:
          type: integer
          format: int64
        minioPath:
          type: string
        processingStatus:
          type: string
          enum: [pending, processing, completed, failed]
        processingError:
          type: string
        uploadedAt:
          type: string
          format: date-time
        processedAt:
          type: string
          format: date-time
```

### Message Schema
```yaml
    Message:
      type: object
      properties:
        id:
          type: string
          format: uuid
        conversationId:
          type: string
          format: uuid
        role:
          type: string
          enum: [user, assistant, system]
        content:
          type: string
        metadata:
          type: object
        createdAt:
          type: string
          format: date-time
```

### Conversation Schema
```yaml
    Conversation:
      type: object
      properties:
        id:
          type: string
          format: uuid
        sessionId:
          type: string
        lastMessage:
          type: string
        messageCount:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
```

### Error Schema
```yaml
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Invalid input provided
            details:
              type: object
            timestamp:
              type: string
              format: date-time
```

## Security Schemes

```yaml
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
```

## Response Templates

```yaml
  responses:
    BadRequest:
      description: Invalid request data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Access denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
```

## Rate Limiting

### Default Rate Limits
- **Authentication endpoints**: 5 requests per minute per IP
- **Project management**: 60 requests per minute per user
- **File uploads**: 10 uploads per minute per user
- **Chat endpoints**: 30 requests per minute per user
- **Public API**: 100 requests per minute per API key

### Rate Limit Headers
```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200
```

This comprehensive API specification provides all the necessary endpoints and data structures needed to implement the chatbot creation framework with proper authentication, validation, and error handling.