Skip to main content

🧪 Science Olympiad API Documentation

Comprehensive REST API for Science Olympiad question management, AI-powered features, collaborative testing, and content moderation

For developers. Studying for an event? Browse the study guides.

Base URL: https://scio.ly
API Version: 1.0.0
Content-Type: application/json
Authentication: API key required for most endpoints
Rate Limiting: AI endpoints have rate limiting
CORS: Enabled for cross-origin requests

🔄 Recent API Updates

Simplified Explanations API: The AI explanations endpoint has been streamlined to use simple JSON request/response patterns. Streaming functionality has been removed for improved reliability and easier integration. See the AI-Powered Features section for details.

📋 Table of Contents

Overview

Response Format

All endpoints return JSON responses with consistent structure:

Standard Response Schema

{
  "success": boolean,
  "data": any,
  "message": string,
  "error": string
}

Success Response Example

{
  "success": true,
  "data": { ... },
  "message": "Operation completed successfully"
}

Error Response Example

{
  "success": false,
  "error": "Invalid request parameters"
}

Data Types

Question Object

{
  "id": "uuid",
  "question": "string",
  "tournament": "string",
  "division": "string",
  "event": "string",
  "options": ["string"],
  "answers": ["string" | "number"],
  "subtopics": ["string"],
  "difficulty": number,
  "imageData": "string",
  "created_at": "ISO8601",
  "updated_at": "ISO8601",
  "base52": "string"
}

ID Question Object

{
  "id": "uuid",
  "question": "string",
  "tournament": "string",
  "division": "string",
  "event": "string",
  "options": ["string"],
  "answers": ["string" | "number"],
  "subtopics": ["string"],
  "difficulty": number,
  "images": ["string"],
  "created_at": "ISO8601",
  "updated_at": "ISO8601"
}

Authentication

API Key Authentication

Most API endpoints require authentication using API keys. API keys are provided on request - please contact us at team@scio.ly to request an API key.

Authentication Methods

All requests must include your API key using one of these methods:

✅ Recommended: Headers

Headers

X-API-Key: your-api-key-here
Authorization: Bearer your-api-key-here
⚠️ Not Recommended: Query Parameter
Security Warning: Query parameters may be logged in server logs, browser history, and proxy logs. Use headers when possible.

Query Parameter

GET /api/questions?api_key=your-api-key-here&event=Chemistry%20Lab

cURL Examples

✅ Recommended: Using Headers

API Request with Headers

curl -H "X-API-Key: your-api-key" \
     https://scio.ly/api/questions?event=Chemistry%20Lab
⚠️ Not Recommended: Using Query Parameter

API Request with Query Parameter

curl "https://scio.ly/api/questions?event=Chemistry%20Lab&api_key=your-api-key"

Public Endpoints

The following endpoints do not require authentication:

  • • GET /api/docs - API documentation
  • • GET /api/meta/events - List all events
  • • GET /api/meta/tournaments - List all tournaments
  • • GET /api/meta/subtopics - List all subtopics
  • • GET /api/meta/stats - Database statistics

Error Response

When API key is missing or invalid:

Error Response

{
  "success": false,
  "error": "API_KEY_REQUIRED",
  "message": "Valid API key required. Contact us at team@scio.ly to request an API key."
}

Question Retrieval

Metadata & Statistics

Sharing & Codes

Quotes Management

🧠 Using the Explanations API

Basic Usage

The explanations API is designed for simple integration. Here's how to use it in your frontend application:

React Hook Example

Here's how to create a custom React hook for managing explanations:

Error Handling

The API returns structured error responses that you should handle appropriately:

Best Practices

  • • Rate Limiting: Implement client-side rate limiting to respect the 2-second delay between requests
  • • Loading States: Show loading indicators while waiting for explanations
  • • Error Handling: Display user-friendly error messages for different error types
  • • Caching: Consider caching explanations to avoid repeated requests for the same question
  • • Progressive Enhancement: Ensure your app works without explanations if the API is unavailable
  • • Accessibility: Provide alternative text for users who can't access explanations

Rate Limiting Implementation

Here's how to implement client-side rate limiting:

📚 Question Management APIs

Fetching Questions

Use the /api/questions endpoint to retrieve filtered questions with pagination:

React Hook for Questions

Custom React hook for managing question state and fetching:

System Endpoints

Error Codes

• 400 - Bad Request (invalid parameters)
• 404 - Not Found (resource doesn't exist)
• 429 - Too Many Requests (rate limit exceeded)
• 500 - Internal Server Error
• 503 - Service Unavailable (AI service down)

Best Practices

• Implement exponential backoff for rate-limited endpoints
• Cache metadata endpoints (events, tournaments, subtopics)
• Use appropriate limits to avoid overwhelming the system
• Handle errors gracefully with user-friendly messages
• Validate input data before sending requests