REST API

Complete HTTP API reference for CoderspaE platform

Base URL#

https://api.coderspae.com/v1

All API endpoints are relative to this base URL.

Authentication#

The API uses API key authentication. Include your API key in the Authorization header:

curl -H "Authorization: Bearer your-api-key" \
     -H "Content-Type: application/json" \
     https://api.coderspae.com/v1/battles

Keep your API key secure

Never expose your API key in client-side code. Use environment variables or secure key management.

Battles#

POST/battles

Create a new battle

Request Body:

{
  "type": "practice" | "realtime",
  "difficulty": "easy" | "medium" | "hard",
  "language": "javascript" | "python" | "java" | "cpp",
  "timeLimit": 3600,
  "participants": 2,
  "problemId": "string" // optional
}

Response:

{
  "id": "battle_123",
  "type": "practice",
  "status": "waiting",
  "joinUrl": "https://coderspae.com/battle/123",
  "problem": {
    "id": "two-sum",
    "title": "Two Sum",
    "difficulty": "easy"
  },
  "createdAt": "2025-01-15T10:00:00Z"
}

GET/battles/{id}

Get battle details

Response:

{
  "id": "battle_123",
  "type": "realtime",
  "status": "active",
  "participants": [
    {
      "id": "user_456",
      "username": "coder123",
      "rating": 1500
    }
  ],
  "timeRemaining": 2700,
  "leaderboard": [
    {
      "userId": "user_456",
      "username": "coder123",
      "score": 100,
      "submissions": 3
    }
  ]
}

POST/battles/{id}/submit

Submit a solution to a battle

Request Body:

{
  "language": "javascript",
  "code": "function twoSum(nums, target) { ... }"
}

Response:

{
  "id": "submission_789",
  "status": "accepted",
  "score": 100,
  "executionTime": 45,
  "memoryUsed": 1024,
  "testCases": {
    "passed": 10,
    "failed": 0,
    "total": 10
  }
}

Tournaments#

GET/tournaments

List available tournaments

Query Parameters:

status: "open" | "active" | "completed"
difficulty: "easy" | "medium" | "hard"
limit: number (default: 20)
offset: number (default: 0)

Response:

{
  "tournaments": [
    {
      "id": "tournament_456",
      "title": "Weekly Championship",
      "status": "open",
      "startTime": "2025-01-20T12:00:00Z",
      "participants": 150,
      "maxParticipants": 500,
      "prizePool": "$1000"
    }
  ],
  "total": 25,
  "hasMore": true
}

POST/tournaments/{id}/register

Response:

{
  "registered": true,
  "registrationId": "reg_789",
  "tournament": {
    "id": "tournament_456",
    "title": "Weekly Championship"
  }
}

Rate Limits#

API requests are rate limited to ensure fair usage and system stability.

Rate Limits by Plan:

Free

• 100 requests/hour
• 10 battles/day
• 1 request/second

Pro

• 1,000 requests/hour
• 100 battles/day
• 10 requests/second

Enterprise

• Custom limits
• Unlimited battles
• Dedicated support

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642677600

Error Responses#

The API uses conventional HTTP response codes and returns JSON error objects.

{
  "error": {
    "code": "INVALID_BATTLE_TYPE",
    "message": "Battle type must be 'practice' or 'realtime'",
    "details": {
      "field": "type",
      "value": "invalid_type"
    }
  }
}

Common Error Codes

HTTP Status	Error Code	Description
400	INVALID_REQUEST	Request parameters are invalid
401	UNAUTHORIZED	Invalid or missing API key
403	FORBIDDEN	Insufficient permissions
404	NOT_FOUND	Resource not found
429	RATE_LIMITED	Too many requests
500	INTERNAL_ERROR	Server error