api-documentation.md•16.1 kB
# EuConquisto Composer MCP - API Documentation
**Document**: Complete API Reference
**Version**: 1.0
**Date**: July 5, 2025
**Status**: Production Ready
**Author**: Claude Code Migration Team
## Table of Contents
1. [Overview](#overview)
2. [Main Integration API](#main-integration-api)
3. [Content Generation APIs](#content-generation-apis)
4. [Widget Mapping APIs](#widget-mapping-apis)
5. [Performance APIs](#performance-apis)
6. [Authentication APIs](#authentication-apis)
7. [Data Models](#data-models)
8. [Error Handling](#error-handling)
9. [Rate Limiting](#rate-limiting)
10. [Examples](#examples)
## Overview
The EuConquisto Composer MCP provides a comprehensive API for educational content generation and composition creation. The API is organized into four main phases, each providing specific functionality for the content creation pipeline.
### Base URL
```
Production: https://composer.digitalpages.com.br/api/v4
Development: http://localhost:3000/api/v4
```
### Authentication
All API endpoints require JWT authentication unless otherwise specified.
```http
Authorization: Bearer <jwt-token>
Content-Type: application/json
```
## Main Integration API
### POST /composition/generate
**Description**: Main endpoint for complete educational composition generation
**Request Body**:
```typescript
interface EducationalRequest {
topic: string; // Educational topic (e.g., "Movimento de Projéteis")
subject: string; // Subject area (e.g., "física", "química", "história")
grade_level: string; // Grade level ("fundamental", "médio", "superior")
author: string; // Author name
learning_objectives?: string[]; // Optional learning objectives
target_duration?: number; // Lesson duration in minutes (default: 50)
language?: string; // Content language (default: "pt-BR")
complexity_level?: string; // Complexity ("low", "medium", "high", "auto")
include_assessments?: boolean; // Include quizzes/flashcards (default: true)
widget_preferences?: string[]; // Preferred widget types
}
```
**Response**:
```typescript
interface CompositionResponse {
success: boolean;
composition_data: ComposerComposition;
composition_url: string;
execution_time: number;
components_used: string[];
metadata: {
phase1_status: string;
phase2_status: string;
phase3_status: string;
infrastructure_status: string;
performance_metrics: PerformanceMetrics;
};
errors?: string[];
warnings?: string[];
}
```
**Example Request**:
```bash
curl -X POST https://composer.digitalpages.com.br/api/v4/composition/generate \
-H "Authorization: Bearer <jwt-token>" \
-H "Content-Type: application/json" \
-d '{
"topic": "Movimento de Projéteis",
"subject": "física",
"grade_level": "médio",
"author": "Prof. Physics",
"learning_objectives": [
"Compreender a trajetória parabólica",
"Calcular alcance máximo de projéteis"
],
"target_duration": 50
}'
```
**Example Response**:
```json
{
"success": true,
"composition_data": {
"composition": {
"id": "movimento-de-projeteis-medio-1641234567890",
"title": "Movimento de Projéteis - Ensino Médio",
"description": "Composição educacional interativa sobre Movimento de Projéteis",
"author": "Prof. Physics",
"created": "2025-07-05",
"version": "4.0.0",
"metadata": {
"disciplina": "Física",
"serie": "Ensino Médio",
"duracao_estimada": "50 minutos",
"tags": ["Movimento de Projéteis", "física", "médio", "educação"]
},
"elements": [...]
}
},
"composition_url": "https://composer.digitalpages.com.br/#/composer/movimento-de-projeteis-medio-1641234567890",
"execution_time": 247,
"components_used": ["infrastructure", "content-generation", "assessment-engine", "widget-mapping"],
"metadata": {
"phase1_status": "success",
"phase2_status": "success",
"phase3_status": "success",
"infrastructure_status": "success",
"performance_metrics": {...}
}
}
```
## Content Generation APIs
### POST /content/generate
**Description**: Generate educational content without widget mapping
**Request Body**:
```typescript
interface ContentRequest {
topic: string;
subject: string;
grade_level: string;
content_type?: "lesson" | "summary" | "explanation";
include_examples?: boolean;
include_exercises?: boolean;
}
```
**Response**:
```typescript
interface ContentResponse {
success: boolean;
content: {
introduction: string;
main_content: string;
examples: string[];
summary: string;
key_concepts: string[];
};
subject_enhancements: any;
generation_time: number;
}
```
### POST /assessment/generate
**Description**: Generate assessments (quizzes and flashcards)
**Request Body**:
```typescript
interface AssessmentRequest {
topic: string;
subject: string;
grade_level: string;
assessment_types: ("quiz" | "flashcards" | "exercises")[];
question_count?: number;
difficulty_level?: "easy" | "medium" | "hard" | "mixed";
}
```
**Response**:
```typescript
interface AssessmentResponse {
success: boolean;
assessments: {
quiz?: QuizComponent;
flashcards?: FlashcardComponent[];
exercises?: ExerciseComponent[];
};
generation_time: number;
quality_score: number;
}
```
## Widget Mapping APIs
### POST /widgets/map
**Description**: Transform content into Composer widget structure
**Request Body**:
```typescript
interface WidgetMappingRequest {
content: any;
subject: string;
grade_level: string;
widget_preferences?: string[];
optimization_level?: "minimal" | "standard" | "comprehensive";
}
```
**Response**:
```typescript
interface WidgetMappingResponse {
success: boolean;
composer_json: ComposerComposition;
widget_analysis: {
total_widgets: number;
widget_types: string[];
complexity_distribution: any;
};
mapping_time: number;
}
```
### GET /widgets/types
**Description**: Get available widget types and configurations
**Response**:
```typescript
interface WidgetTypesResponse {
success: boolean;
widget_types: {
id: string;
name: string;
description: string;
supported_content_types: string[];
configuration_options: any;
}[];
}
```
### POST /images/select
**Description**: Context-aware image selection for educational content
**Request Body**:
```typescript
interface ImageSelectionRequest {
content: string;
subject: string;
grade_level: string;
widget_type: string;
image_count?: number;
style_preferences?: string[];
}
```
**Response**:
```typescript
interface ImageSelectionResponse {
success: boolean;
selected_images: {
url: string;
alt_text: string;
caption: string;
educational_context: string;
}[];
selection_criteria: string[];
selection_time: number;
}
```
## Performance APIs
### GET /performance/metrics
**Description**: Get current system performance metrics
**Response**:
```typescript
interface PerformanceMetricsResponse {
success: boolean;
metrics: {
average_generation_time: number;
memory_usage: number;
cache_hit_ratio: number;
active_requests: number;
system_health: "healthy" | "warning" | "critical";
};
recommendations: string[];
}
```
### POST /performance/optimize
**Description**: Trigger performance optimization
**Request Body**:
```typescript
interface OptimizationRequest {
optimization_type: "memory" | "cache" | "browser" | "all";
force_cleanup?: boolean;
}
```
**Response**:
```typescript
interface OptimizationResponse {
success: boolean;
optimizations_applied: string[];
performance_improvement: {
before: any;
after: any;
improvement_percentage: number;
};
optimization_time: number;
}
```
## Authentication APIs
### POST /auth/validate
**Description**: Validate JWT token
**Request Body**:
```typescript
interface TokenValidationRequest {
token: string;
}
```
**Response**:
```typescript
interface TokenValidationResponse {
success: boolean;
valid: boolean;
expires_at?: string;
user_info?: {
id: string;
name: string;
role: string;
};
}
```
### GET /auth/health
**Description**: Check authentication system health
**Response**:
```typescript
interface AuthHealthResponse {
success: boolean;
auth_status: "operational" | "degraded" | "down";
jwt_validation: boolean;
browser_automation: boolean;
api_connectivity: boolean;
}
```
## Data Models
### ComposerComposition
```typescript
interface ComposerComposition {
composition: {
id: string;
title: string;
description: string;
author: string;
created: string;
version: string;
metadata: {
disciplina: string;
serie: string;
duracao_estimada: string;
tags: string[];
};
elements: ComposerElement[];
};
}
```
### ComposerElement
```typescript
interface ComposerElement {
id: string;
type: string;
content_title: string;
[key: string]: any; // Widget-specific properties
}
```
### PerformanceMetrics
```typescript
interface PerformanceMetrics {
generation_time: number;
memory_usage: number;
cpu_usage: number;
cache_hit_ratio: number;
resource_efficiency: number;
component_breakdown: ComponentPerformance[];
}
```
### ComponentPerformance
```typescript
interface ComponentPerformance {
component: string;
execution_time: number;
memory_delta: number;
optimization_applied: string[];
}
```
## Error Handling
### Error Response Format
```typescript
interface ErrorResponse {
success: false;
error: {
code: string;
message: string;
details?: any;
timestamp: string;
request_id: string;
};
suggestions?: string[];
}
```
### Common Error Codes
| Code | Description | HTTP Status |
|------|-------------|-------------|
| `AUTH_INVALID` | Invalid or expired JWT token | 401 |
| `AUTH_MISSING` | Authorization header missing | 401 |
| `VALIDATION_ERROR` | Request validation failed | 400 |
| `CONTENT_GENERATION_FAILED` | Content generation error | 500 |
| `WIDGET_MAPPING_FAILED` | Widget mapping error | 500 |
| `PERFORMANCE_DEGRADED` | System performance issues | 503 |
| `RATE_LIMIT_EXCEEDED` | Too many requests | 429 |
| `INTERNAL_ERROR` | Unexpected server error | 500 |
### Error Handling Example
```typescript
try {
const response = await fetch('/api/v4/composition/generate', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(request)
});
if (!response.ok) {
const error = await response.json();
throw new Error(`${error.error.code}: ${error.error.message}`);
}
const composition = await response.json();
return composition;
} catch (error) {
console.error('Composition generation failed:', error.message);
// Handle error appropriately
}
```
## Rate Limiting
### Rate Limits
| Endpoint | Limit | Window |
|----------|-------|--------|
| `/composition/generate` | 10 requests | 1 minute |
| `/content/generate` | 50 requests | 1 minute |
| `/assessment/generate` | 30 requests | 1 minute |
| `/widgets/map` | 100 requests | 1 minute |
| Other endpoints | 200 requests | 1 minute |
### Rate Limit Headers
```http
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1641234567
```
### Rate Limit Exceeded Response
```json
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Try again in 45 seconds.",
"details": {
"limit": 10,
"window": "1 minute",
"reset_at": "2025-07-05T10:45:30Z"
},
"timestamp": "2025-07-05T10:44:45Z",
"request_id": "req_abc123"
},
"suggestions": [
"Reduce request frequency",
"Implement exponential backoff",
"Cache responses when possible"
]
}
```
## Examples
### Complete Lesson Generation
```javascript
// Generate a complete physics lesson
const request = {
topic: "Leis de Newton",
subject: "física",
grade_level: "médio",
author: "Prof. Silva",
learning_objectives: [
"Compreender as três leis de Newton",
"Aplicar as leis em problemas práticos",
"Relacionar força, massa e aceleração"
],
target_duration: 50,
include_assessments: true
};
const response = await fetch('/api/v4/composition/generate', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(request)
});
const composition = await response.json();
console.log('Generated composition:', composition.composition_url);
```
### Assessment Only Generation
```javascript
// Generate only assessments for a topic
const assessmentRequest = {
topic: "Fotossíntese",
subject: "ciências",
grade_level: "fundamental",
assessment_types: ["quiz", "flashcards"],
question_count: 10,
difficulty_level: "medium"
};
const assessmentResponse = await fetch('/api/v4/assessment/generate', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(assessmentRequest)
});
const assessments = await assessmentResponse.json();
console.log('Generated assessments:', assessments.assessments);
```
### Performance Monitoring
```javascript
// Monitor system performance
const metricsResponse = await fetch('/api/v4/performance/metrics', {
headers: {
'Authorization': `Bearer ${token}`
}
});
const metrics = await metricsResponse.json();
console.log('System performance:', metrics.metrics);
if (metrics.metrics.system_health !== 'healthy') {
console.warn('Performance issue detected:', metrics.recommendations);
}
```
### Batch Processing
```javascript
// Process multiple topics efficiently
const topics = [
{ topic: "Ácidos e Bases", subject: "química", grade_level: "médio" },
{ topic: "Revolução Francesa", subject: "história", grade_level: "médio" },
{ topic: "Funções Quadráticas", subject: "matemática", grade_level: "médio" }
];
const compositions = await Promise.all(
topics.map(async (topicData) => {
const response = await fetch('/api/v4/composition/generate', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
...topicData,
author: "Prof. Batch"
})
});
return response.json();
})
);
console.log(`Generated ${compositions.length} compositions`);
```
## SDK and Libraries
### JavaScript/TypeScript SDK
```bash
npm install @euconquisto/composer-mcp-sdk
```
```typescript
import { ComposerMCP } from '@euconquisto/composer-mcp-sdk';
const client = new ComposerMCP({
apiUrl: 'https://composer.digitalpages.com.br/api/v4',
token: 'your-jwt-token'
});
// Generate composition
const composition = await client.generateComposition({
topic: "Movimento de Projéteis",
subject: "física",
grade_level: "médio",
author: "Prof. Physics"
});
```
### Python SDK
```bash
pip install euconquisto-composer-mcp
```
```python
from euconquisto_composer_mcp import ComposerMCPClient
client = ComposerMCPClient(
api_url="https://composer.digitalpages.com.br/api/v4",
token="your-jwt-token"
)
# Generate composition
composition = client.generate_composition({
"topic": "Movimento de Projéteis",
"subject": "física",
"grade_level": "médio",
"author": "Prof. Physics"
})
```
---
**API Status**: ✅ **PRODUCTION READY**
**Documentation Coverage**: ✅ **COMPLETE** (All endpoints documented)
**Authentication**: ✅ **SECURE** (JWT-based with validation)
**Performance**: ✅ **OPTIMIZED** (Rate limiting and caching)
**Error Handling**: ✅ **COMPREHENSIVE** (Detailed error responses)
**🎯 Key Feature: Universal educational content generation API with no pre-mapping requirements, supporting any academic subject with high performance and comprehensive error handling**