Skip to main content

​
API Overview

The Studley AI API provides programmatic access to our AI-powered study platform. Build integrations, automate workflows, and create custom learning experiences using our comprehensive REST API.

​
Base URL

All API requests are made to: 
https://api.studley.ai/api
For local development: 
http://localhost:3000/api

​
API Architecture

Studley AI uses a Next.js App Router architecture with API routes organized by feature:

​
Core API Endpoints

  • Authentication (/api/auth/*) - User authentication, login, signup, and session management
  • AI Tutor (/api/ai-tutor/*) - Interactive AI tutoring sessions and chat
  • AI Workspace (/api/ai-workspace/*) - AI-powered workspace sessions
  • Content Generation - Generate quizzes, flashcards, notes, and study materials
  • Materials (/api/materials/*) - Document upload and management
  • Dashboard (/api/dashboard/*) - User dashboard data and analytics
  • Tools (/api/tools/*) - Specialized study tools and utilities

​
Request Format

​
Content Type

All API requests should use JSON format: 
Content-Type: application/json

​
HTTP Methods

The API uses standard HTTP methods:
  • GET - Retrieve resources
  • POST - Create resources or execute actions
  • PUT - Update resources
  • DELETE - Remove resources

​
Example Request

curl -X POST https://api.studley.ai/api/generate-quiz \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_TOKEN" \
  -d '{
    "topic": "World War II",
    "numQuestions": 5
  }'

​
Response Format

All API responses are returned in JSON format:

​
Success Response

{
  "questions": [
    {
      "question": "When did World War II begin?",
      "options": ["1939", "1941", "1945", "1937"],
      "correctAnswer": 0,
      "explanation": "World War II began in 1939 with Germany's invasion of Poland."
    }
  ],
  "topic": "World War II"
}

​
Error Response

{
  "error": "Topic is required"
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
CodeDescription
200Success - Request completed successfully
400Bad Request - Invalid parameters or missing required fields
401Unauthorized - Authentication required or invalid credentials
403Forbidden - Authenticated but insufficient permissions
404Not Found - Resource does not exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server-side error occurred

​
Rate Limiting

To ensure fair usage and platform stability, the Studley AI API implements rate limiting on content generation endpoints.

​
Rate Limit Configuration

  • Limit: 10 generations per 5-minute window
  • Window: Rolling 5-minute window
  • Cooldown: 5 minutes after hitting the limit

​
How It Works

Rate limits are tracked per user identifier (user ID for authenticated requests, IP address for anonymous requests). The system uses a sliding window algorithm:
  1. Each generation request is recorded with a timestamp
  2. Recent requests within the 5-minute window are counted
  3. If the count exceeds 10, subsequent requests are rejected
  4. Once requests age beyond the 5-minute window, they no longer count toward the limit

​
Rate Limit Headers

When you hit a rate limit, the response includes: 
{
  "isValid": false,
  "violatesPolicy": true,
  "violationType": "rate_limit",
  "reason": "You've generated 10 quizzes in the last 5 minutes. Please wait 3 minutes before generating more.",
  "errorCode": 203,
  "retryAfter": 180
}

​
Best Practices

Implement exponential backoff when receiving rate limit errors. Use the retryAfter value to determine when to retry your request.
Rate limits apply to generation endpoints including quiz generation, flashcard creation, and AI-powered content creation. Read operations and authentication endpoints have separate, more generous limits.

​
Pagination

Endpoints that return lists of items support pagination: 
GET /api/ai-tutor/sessions?page=1&limit=20

​
Pagination Parameters

  • page - Page number (default: 1)
  • limit - Items per page (default: 20, max: 100)

​
Pagination Response

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

​
Error Handling

The API uses consistent error response formats: 
{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {
    "field": "Additional context"
  }
}

​
Common Error Codes

  • INVALID_REQUEST - Malformed request or missing required parameters
  • AUTHENTICATION_REQUIRED - User must be authenticated
  • RATE_LIMIT_EXCEEDED - Too many requests
  • RESOURCE_NOT_FOUND - Requested resource does not exist
  • INTERNAL_ERROR - Server-side error

​
Versioning

The Studley AI API is currently in version 1. All endpoints are stable unless marked as beta. Breaking changes will be communicated with advance notice.
API versioning is currently managed through the endpoint structure. Future versions may introduce version prefixes (/v2/api/*).

​
Next Steps

Authentication

Learn how to authenticate API requests

AI Tutor API

Build AI-powered tutoring experiences

Content Generation

Generate quizzes, flashcards, and study materials

Rate Limits

Understanding rate limits and best practices

Build docs developers (and LLMs) love

Get started for freeTalk to us