API Endpoints Reference

Complete reference for all Kai API endpoints

Published

November 20, 2025

Overview

This page provides detailed documentation for all Kai API endpoints. Each endpoint includes request/response formats, parameters, examples, and common error scenarios.

NoteBase URL

All API requests should use the base URL:

https://chi2api.com/v1

Authentication

All endpoints require authentication via API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

See Authentication Guide for details on obtaining and managing API keys.

Grading Endpoints

Submit Assignment for Grading

Grade a student submission using AI-powered assessment.

POST /assignments/grade

Request Body:

Parameter Type Required Description
assignment_id string Yes Unique identifier for the assignment
student_submission string Yes Student’s work to be graded (text or URL)
rubric_id string No ID of grading rubric to use
grading_style string No Style of feedback: detailed, concise, points_only (default: detailed)
max_score number No Maximum possible score (default: 100)
return_suggestions boolean No Include improvement suggestions (default: true)

Response:

{
  "grade_id": "grd_abc123",
  "score": 85,
  "max_score": 100,
  "percentage": 85.0,
  "feedback": "Excellent analysis of the main themes...",
  "suggestions": [
    "Consider adding more specific examples",
    "Conclusion could be strengthened"
  ],
  "rubric_scores": {
    "content": 28,
    "organization": 22,
    "grammar": 20,
    "citations": 15
  },
  "confidence": 0.92,
  "timestamp": "2024-01-15T14:30:00Z",
  "processing_time_ms": 1847
}

Example:

curl -X POST https://chi2api.com/v1/assignments/grade \
  -H "Authorization: Bearer kai_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "assignment_id": "PSYCH101-ESSAY1",
    "student_submission": "The fundamental attribution error...",
    "grading_style": "detailed",
    "max_score": 100
  }'
import requests

response = requests.post(
    "https://chi2api.com/v1/assignments/grade",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "assignment_id": "PSYCH101-ESSAY1",
        "student_submission": "The fundamental attribution error...",
        "grading_style": "detailed",
        "max_score": 100
    }
)

result = response.json()
print(f"Score: {result['score']}/{result['max_score']}")
print(f"Feedback: {result['feedback']}")
const response = await fetch('https://chi2api.com/v1/assignments/grade', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    assignment_id: 'PSYCH101-ESSAY1',
    student_submission: 'The fundamental attribution error...',
    grading_style: 'detailed',
    max_score: 100
  })
});

const result = await response.json();
console.log(`Score: ${result.score}/${result.max_score}`);
console.log(`Feedback: ${result.feedback}`);

Batch Grade Submissions

Grade multiple submissions in a single request.

POST /assignments/grade/batch

Request Body:

{
  "assignment_id": "PSYCH101-ESSAY1",
  "grading_style": "concise",
  "submissions": [
    {
      "student_id": "student123",
      "submission": "Student 1's essay text..."
    },
    {
      "student_id": "student124",
      "submission": "Student 2's essay text..."
    }
  ]
}

Response:

{
  "batch_id": "batch_xyz789",
  "status": "processing",
  "total_submissions": 2,
  "estimated_completion": "2024-01-15T14:35:00Z",
  "results_url": "/assignments/grade/batch/batch_xyz789"
}

Get Grading Result

Retrieve results from a batch grading job.

GET /assignments/grade/batch/{batch_id}

Response:

{
  "batch_id": "batch_xyz789",
  "status": "completed",
  "total_submissions": 2,
  "completed": 2,
  "failed": 0,
  "results": [
    {
      "student_id": "student123",
      "grade_id": "grd_abc123",
      "score": 85,
      "feedback": "..."
    },
    {
      "student_id": "student124",
      "grade_id": "grd_abc124",
      "score": 92,
      "feedback": "..."
    }
  ]
}

Content Generation Endpoints

Generate Quiz Questions

Create quiz questions based on course content.

POST /content/quiz

Request Body:

Parameter Type Required Description
topic string Yes Subject matter for quiz
difficulty string No Question difficulty: easy, medium, hard (default: medium)
question_count number No Number of questions (1-50, default: 10)
question_types array No Types to include: multiple_choice, true_false, short_answer
course_id string No Course context for question generation

Response:

{
  "quiz_id": "quiz_123",
  "topic": "Introduction to Statistics",
  "difficulty": "medium",
  "questions": [
    {
      "question_id": "q1",
      "type": "multiple_choice",
      "text": "What is the primary purpose of standard error?",
      "options": [
        "Measure variability in population",
        "Estimate sampling distribution spread",
        "Calculate correlation",
        "Determine causation"
      ],
      "correct_answer": 1,
      "explanation": "Standard error estimates the standard deviation of the sampling distribution.",
      "points": 1
    }
  ],
  "total_points": 10
}

Generate Assignment Prompts

Create assignment prompts based on learning objectives.

POST /content/assignment

Request Body:

{
  "learning_objectives": [
    "Understand hypothesis testing",
    "Apply t-tests to real data"
  ],
  "assignment_type": "problem_set",
  "difficulty": "intermediate",
  "estimated_time": 60
}

Response:

{
  "assignment_id": "assign_456",
  "title": "Hypothesis Testing with Real-World Data",
  "description": "Apply your knowledge of hypothesis testing...",
  "prompts": [
    {
      "prompt_number": 1,
      "text": "Given the following dataset...",
      "rubric_criteria": ["Correct null hypothesis", "Appropriate test selection"]
    }
  ],
  "estimated_time_minutes": 60
}

Feedback Endpoints

Request Student Feedback

Trigger a feedback request to enrolled students.

POST /courses/{course_id}/feedback/request

Request Body:

Parameter Type Required Description
questions array No Custom questions (uses default if omitted)
response_window_minutes number No How long students have to respond (default: 2)
anonymous boolean No Collect anonymously (default: true)

Response:

{
  "request_id": "freq_789",
  "course_id": "course_abc",
  "sent_to_students": 45,
  "delivery_status": {
    "sent": 45,
    "delivered": 43,
    "failed": 2
  },
  "response_window_closes": "2024-01-15T14:35:00Z"
}

Get Feedback Results

Retrieve responses from a feedback request.

GET /courses/{course_id}/feedback/{request_id}

Response:

{
  "request_id": "freq_789",
  "course_id": "course_abc",
  "response_rate": 0.73,
  "total_responses": 33,
  "total_students": 45,
  "analysis": {
    "high_frequency_confusion": [
      {
        "topic": "Standard Error",
        "mentioned_by_count": 23,
        "percentage": 0.70,
        "action": "class_review_recommended"
      }
    ],
    "low_frequency_confusion": [
      {
        "topic": "Z-scores",
        "mentioned_by_count": 4,
        "percentage": 0.12,
        "action": "individual_resources_recommended"
      }
    ]
  },
  "sentiment": {
    "positive": 0.65,
    "neutral": 0.25,
    "negative": 0.10
  }
}

Analytics Endpoints

Get Course Analytics

Retrieve comprehensive analytics for a course.

GET /analytics/courses/{course_id}

Query Parameters:

Parameter Type Required Description
start_date string No ISO 8601 date (default: semester start)
end_date string No ISO 8601 date (default: today)
metrics string No Comma-separated list of metrics

Response:

{
  "course_id": "course_abc",
  "period": {
    "start": "2024-01-01",
    "end": "2024-05-01"
  },
  "enrollment": {
    "total": 45,
    "active": 43,
    "dropped": 2
  },
  "engagement": {
    "avg_feedback_response_rate": 0.73,
    "avg_quiz_completion_rate": 0.88,
    "app_active_users": 41
  },
  "performance": {
    "avg_quiz_score": 82.5,
    "avg_assignment_score": 85.2,
    "improvement_trend": 0.08
  },
  "common_confusion_topics": [
    "Standard Error",
    "Hypothesis Testing",
    "P-values"
  ]
}

Get Student Performance

Retrieve individual student analytics.

GET /analytics/students/{student_id}

Query Parameters:

Parameter Type Description
course_id string Filter by specific course
start_date string ISO 8601 date
end_date string ISO 8601 date

Response:

{
  "student_id": "student123",
  "courses": [
    {
      "course_id": "course_abc",
      "course_name": "Introduction to Statistics",
      "performance": {
        "current_grade": 87.5,
        "quiz_average": 85.0,
        "assignment_average": 90.0,
        "participation_score": 88.0
      },
      "engagement": {
        "feedback_response_rate": 0.95,
        "app_login_frequency": "daily",
        "last_active": "2024-01-15T14:30:00Z"
      },
      "struggling_topics": [
        "Hypothesis Testing"
      ],
      "strong_topics": [
        "Descriptive Statistics",
        "Probability"
      ]
    }
  ]
}

Course Management Endpoints

List Courses

Get all courses for the authenticated account.

GET /courses

Query Parameters:

Parameter Type Description
status string Filter by status: active, archived, draft
semester string Filter by semester
limit number Results per page (max 100)
offset number Pagination offset

Response:

{
  "courses": [
    {
      "course_id": "course_abc",
      "name": "Introduction to Statistics",
      "code": "STAT101",
      "semester": "Spring 2024",
      "status": "active",
      "enrollment_count": 45,
      "lms_integration": "canvas"
    }
  ],
  "total": 1,
  "limit": 100,
  "offset": 0
}

Create Course

Create a new course.

POST /courses

Request Body:

{
  "name": "Introduction to Statistics",
  "code": "STAT101",
  "semester": "Spring 2024",
  "description": "Introduction to statistical concepts...",
  "lms_integration": {
    "platform": "canvas",
    "course_id": "12345"
  }
}

Response:

{
  "course_id": "course_abc",
  "name": "Introduction to Statistics",
  "code": "STAT101",
  "enrollment_code": "ABC123",
  "enrollment_link": "https://kaitheai.com/enroll/ABC123",
  "created_at": "2024-01-15T14:30:00Z"
}

Update Course

Update course settings.

PATCH /courses/{course_id}

Request Body:

{
  "name": "Introduction to Statistics (Updated)",
  "settings": {
    "feedback_enabled": true,
    "quiz_enabled": true,
    "anonymous_feedback": true
  }
}

Delete Course

Archive or delete a course.

DELETE /courses/{course_id}

Query Parameters:

Parameter Type Description
permanent boolean Permanently delete (default: false, archives instead)

Webhook Endpoints

Register Webhook

Configure a webhook to receive real-time updates.

POST /webhooks

Request Body:

{
  "url": "https://your-domain.com/webhook",
  "events": [
    "grading.completed",
    "feedback.received",
    "quiz.submitted"
  ],
  "active": true,
  "secret": "your_webhook_secret"
}

Response:

{
  "webhook_id": "wh_123",
  "url": "https://your-domain.com/webhook",
  "events": ["grading.completed", "feedback.received", "quiz.submitted"],
  "active": true,
  "created_at": "2024-01-15T14:30:00Z"
}

List Webhooks

Get all configured webhooks.

GET /webhooks

Test Webhook

Send a test event to verify webhook configuration.

POST /webhooks/{webhook_id}/test

Rate Limits

All endpoints are subject to rate limiting based on your plan:

Plan Requests/min Requests/day Burst
Free 10 1,000 20
Educator 60 10,000 100
Department 180 50,000 300
Institution 600 500,000 1000

Rate Limit Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642262400

Error Responses

All endpoints return errors in a consistent format:

{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'assignment_id' field is required",
    "details": {
      "field": "assignment_id",
      "constraint": "required"
    },
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T14:30:00Z"
  }
}

Common Error Codes:

Code HTTP Status Description
invalid_parameter 400 Request parameter invalid or missing
unauthorized 401 Invalid or missing API key
forbidden 403 Insufficient permissions
not_found 404 Resource not found
rate_limit_exceeded 429 Too many requests
internal_error 500 Server error
service_unavailable 503 Temporary service outage

SDKs and Client Libraries

Official SDKs available for easy integration:

Pagination

List endpoints support cursor-based pagination:

Request:

GET /courses?limit=20&offset=40

Response:

{
  "data": [...],
  "pagination": {
    "limit": 20,
    "offset": 40,
    "total": 156,
    "has_more": true
  }
}

Versioning

The API uses URL-based versioning. Current version: v1

Base URL includes version:

https://chi2api.com/v1/endpoint

Version sunset policy: - New versions announced 6 months in advance - Old versions supported for minimum 12 months - Deprecation notices sent via email and headers

Support

This reference is updated regularly. Last updated: November 20, 2025