REST API Reference - Lyceum Documentation

The Lyceum Cloud API enables you to programmatically execute code, manage files, monitor usage, and integrate our cloud compute platform into your applications.

Base URL

All API requests use this base URL:

https://api.lyceum.technology/api/v2/external

Authentication

JWT Tokens

Best for: Web applications, user sessions

24-hour expiration
Automatic refresh support
Obtained via login endpoint

API Keys

Best for: CI/CD, automation, services

No expiration (configurable)
Revocable anytime
Created in dashboard

Quick Start Authentication

Get JWT Token
Use Token
API Keys

curl -X POST https://api.lyceum.technology/api/v2/external/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Response:

{
  "access_token": "eyJhbGci...",
  "refresh_token": "eyJhbGci...",
  "expires_in": 86400
}

API Endpoints

🚀 Code Execution

Execute Python code or Docker containers on cloud infrastructure.

Python Execution

POST /execution/streaming/start

{
  "code": "print('Hello World')",
  "nbcode": 0,
  "execution_type": "cpu",
  "timeout": 300,
  "requirements_content": "pandas==2.0.0"
}

Response:

{
  "execution_id": "uuid",
  "status": "running",
  "streaming_url": "wss://..."
}

Docker Containers

POST /execution/image/start

{
  "docker_image_ref": "python:3.11",
  "docker_run_cmd": ["python", "-c", "print('Hello')"],
  "execution_type": "cpu",
  "timeout": 600
}

Execution Management

GET /execution/streaming/{id}/status - Check status
POST /execution/streaming/abort/{id} - Stop execution
POST /execution/streaming/complete/{id} - Mark complete

📁 File Storage

Manage files in cloud storage with S3-compatible API.

Upload Files

POST /storage/upload

curl -X POST .../storage/upload \
  -H "Authorization: Bearer <token>" \
  -F "[email protected]" \
  -F "key=datasets/data.csv"

List & Download

GET /storage/list-files?prefix=datasets/ - List files
GET /storage/download/{file_key} - Download file
DELETE /storage/delete/{file_key} - Delete file

S3 Credentials

POST /storage/credentialsGet temporary S3 credentials for direct access:

{
  "access_key_id": "AKIA...",
  "secret_access_key": "...",
  "session_token": "...",
  "expiration": "2024-01-01T12:00:00Z"
}

💳 Billing & Credits

Monitor usage and manage billing.

Credit Balance

GET /billing/credits

{
  "available_credits": 100.0,
  "used_credits": 25.0,
  "remaining_credits": 75.0,
  "monthly_free_credits": 20.0,
  "purchased_credits": 80.0
}

Usage History

GET /billing/history?limit=50&offset=0Returns execution history with costs.

Purchase Credits

POST /billing/checkout

{
  "credits_amount": 100,
  "success_url": "https://yourapp.com/success",
  "cancel_url": "https://yourapp.com/cancel"
}

🔐 Authentication & Users

Manage authentication and API keys.

Authentication

POST /auth/login - Login with email/password
POST /auth/refresh - Refresh access token

API Key Management

GET /auth/api-keys/ - List API keys
POST /auth/api-keys/ - Create new key
DELETE /auth/api-keys/{id} - Delete key
PATCH /auth/api-keys/{id}/toggle - Enable/disable

User Management

DELETE /user/delete - Delete account

🏥 System Health

Monitor API status and version.

GET /health/ping - Health check
GET /health/version - API version info

Quick Start Examples

Python
JavaScript
cURL

import requests

class LyceumClient:
    def __init__(self, email, password):
        self.base_url = "https://api.lyceum.technology/api/v2/external"
        self.token = self._authenticate(email, password)
    
    def _authenticate(self, email, password):
        response = requests.post(
            f"{self.base_url}/auth/login",
            json={"email": email, "password": password}
        )
        return response.json()["access_token"]
    
    def execute_code(self, code):
        response = requests.post(
            f"{self.base_url}/execution/streaming/start",
            headers={
                "Authorization": f"Bearer {self.token}",
                "Content-Type": "application/json"
            },
            json={
                "code": code,
                "nbcode": 0,
                "execution_type": "cpu"
            }
        )
        return response.json()

# Usage
client = LyceumClient("[email protected]", "password")
result = client.execute_code("print('Hello World')")
print(f"Execution ID: {result['execution_id']}")

Response Format

Success Response

{
  "status": "success",
  "data": {
    // Response data
  },
  "message": "Operation completed successfully"
}

Error Response

{
  "detail": "Error message",
  "status": 400,
  "type": "validation_error",
  "errors": [
    {
      "field": "code",
      "message": "Required field missing"
    }
  ]
}

Rate Limits

Rate limits help ensure fair usage and platform stability. Headers indicate your current usage.

Endpoint Category	Limit	Window
Authentication	10 requests	per minute
Code Execution	100 requests	per hour
File Storage	1000 requests	per hour
Billing	100 requests	per hour

Rate Limit Headers:

X-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Requests remaining
X-RateLimit-Reset: Unix timestamp when limit resets

HTTP Status Codes

Code	Status	Description
200	OK	Request successful
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Authentication required or invalid
403	Forbidden	Access denied to resource
404	Not Found	Resource doesn’t exist
429	Too Many Requests	Rate limit exceeded
500	Internal Error	Server error occurred
503	Service Unavailable	Service temporarily down

Error Handling

import time
import requests
from requests.exceptions import RequestException

def api_call_with_retry(url, headers, json_data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, json=json_data)
            
            if response.status_code == 429:  # Rate limited
                retry_after = int(response.headers.get('Retry-After', 60))
                time.sleep(retry_after)
                continue
            
            response.raise_for_status()
            return response.json()
            
        except RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff
    
    return None

Best Practices

Use Environment Variables

Store API credentials securely:

export LYCEUM_API_TOKEN="your-token"
export LYCEUM_API_KEY="lk_live_..."

Implement Retry Logic

Handle transient failures gracefully with exponential backoff.

Monitor Rate Limits

Check rate limit headers and implement appropriate throttling.

Clean Up Resources

Stop unnecessary executions and delete temporary files.

Validate Inputs

Check parameters before making API calls to avoid errors.

Use Appropriate Timeouts

Set reasonable timeouts for long-running operations.

SDK & Tools

Python SDK

Official Python client library

pip install lyceum-cloud

CLI Tool

Command-line interface

npm install -g @lyceum/cli

VS Code Extension

Execute code directly from VS Code

Postman Collection

Interactive API testing

Support

API Status

Check current API status and incidents

Support

Get help from our technical team

Getting Started

Endpoints

​Base URL

​Authentication

JWT Tokens

API Keys

​Quick Start Authentication

​API Endpoints

​🚀 Code Execution

​📁 File Storage

​💳 Billing & Credits

​🔐 Authentication & Users

​🏥 System Health

​Quick Start Examples

​Response Format

​Success Response

​Error Response

​Rate Limits

​HTTP Status Codes

​Error Handling

​Best Practices

​SDK & Tools

Python SDK

CLI Tool

VS Code Extension

Postman Collection

​Support

API Status

Support

Base URL

Authentication

Quick Start Authentication

API Endpoints

🚀 Code Execution

📁 File Storage

💳 Billing & Credits

🔐 Authentication & Users

🏥 System Health

Quick Start Examples

Response Format

Success Response

Error Response

Rate Limits

HTTP Status Codes

Error Handling

Best Practices

SDK & Tools

Support