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
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: [email protected]
servers:
- url: http://localhost:3000/api
description: Development server
- url: https://api.chatbotframework.com
description: Production server
Authentication Endpoints
POST /auth/signup
/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: [email protected]
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
/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
/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
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}
/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}
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}
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
/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
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}
/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
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
/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
/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
/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}
/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}
/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
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
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
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
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
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
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
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
apiKey:
type: apiKey
in: header
name: X-API-Key
Response Templates
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.