miracles_in_motion/docs/API.md

API Documentation

Student Assistance AI API

Core Endpoints

POST /api/student-requests

Process new student assistance requests through AI matching engine.

Request Body:

{
  studentId: string
  description: string
  category: 'clothing' | 'supplies' | 'food' | 'transportation' | 'emergency'
  urgency: 'low' | 'medium' | 'high' | 'critical'
  constraints: {
    maxBudget?: number
    timeframe: string
    geographic?: {
      maxDistance: number
      preferredAreas?: string[]
    }
  }
}

Response:

{
  requestId: string
  status: 'pending' | 'processing' | 'matched' | 'completed'
  matches: MatchResult[]
  estimatedCompletion: string
  aiConfidence: number
}

GET /api/requests/{requestId}/status

Get real-time status of a student request.

POST /api/ai/feedback

Submit feedback for AI model improvement.

Request Body:

{
  requestId: string
  matchId: string
  outcome: 'successful' | 'partial' | 'failed'
  feedback: {
    satisfactionScore: number (1-5)
    issues?: string[]
    improvements?: string[]
  }
}

Error Handling

All API endpoints return errors in the following format:

{
  error: {
    code: string
    message: string
    details?: any
  }
}

Common error codes:

• INVALID_REQUEST: Request format is incorrect
• AI_MODEL_UNAVAILABLE: AI service is temporarily unavailable
• INSUFFICIENT_RESOURCES: No matching resources found
• RATE_LIMIT_EXCEEDED: Too many requests from client