API Reference

Complete reference documentation for CoderspaE REST API endpoints

Authentication

All API requests require authentication using API keys or OAuth tokens.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Base URL

Production: https://api.coderspae.com/v1
Staging:    https://staging-api.coderspae.com/v1

Users API

Get Current User

Request

GET /users/me

Response

{
  "id": "user_123",
  "username": "coder_pro",
  "email": "user@example.com",
  "rating": 1750,
  "tier": "platinum",
  "joinedAt": "2024-01-15T10:00:00Z"
}

Update User Profile

Request

PUT /users/me
{
  "displayName": "Pro Coder",
  "bio": "Love algorithms",
  "location": "San Francisco",
  "website": "https://example.com"
}

Response

{
  "success": true,
  "user": {
    "id": "user_123",
    "username": "coder_pro",
    "displayName": "Pro Coder",
    "bio": "Love algorithms"
  }
}

Get User Statistics

Request

GET /users/me/stats?timeframe=30d

Response

{
  "totalBattles": 89,
  "wins": 67,
  "losses": 22,
  "winRate": 0.753,
  "averageTime": 847,
  "rating": 1750,
  "ratingChange": "+45"
}

Battles API

Create Battle

Request

POST /battles
{
  "type": "quick",
  "difficulty": "medium",
  "language": "javascript",
  "maxParticipants": 2
}

Response

{
  "id": "battle_456",
  "type": "quick",
  "status": "waiting",
  "problem": {
    "id": "prob_789",
    "title": "Two Sum",
    "difficulty": "medium"
  },
  "participants": [],
  "createdAt": "2024-01-20T14:30:00Z"
}

Join Battle

Request

POST /battles/battle_456/join

Response

{
  "success": true,
  "battle": {
    "id": "battle_456",
    "status": "active",
    "participants": [
      {
        "id": "user_123",
        "username": "coder_pro",
        "joinedAt": "2024-01-20T14:32:00Z"
      }
    ]
  }
}

Submit Solution

Request

POST /battles/battle_456/submit
{
  "code": "function twoSum(nums, target) {...}",
  "language": "javascript"
}

Response

{
  "submissionId": "sub_789",
  "status": "testing",
  "testResults": [
    {
      "input": "[2,7,11,15], 9",
      "expected": "[0,1]",
      "actual": "[0,1]",
      "passed": true
    }
  ],
  "score": 100,
  "executionTime": 23
}

List User Battles

Request

GET /battles?status=completed&limit=10

Response

{
  "battles": [
    {
      "id": "battle_123",
      "type": "quick",
      "status": "completed",
      "result": "won",
      "score": 95,
      "duration": 847,
      "completedAt": "2024-01-19T16:45:00Z"
    }
  ],
  "total": 89,
  "page": 1,
  "hasMore": true
}

Tournaments API

List Tournaments

Request

GET /tournaments?status=active&limit=5

Response

{
  "tournaments": [
    {
      "id": "tour_123",
      "name": "Weekly Sprint",
      "status": "active",
      "format": "elimination",
      "participants": 128,
      "maxParticipants": 256,
      "prize": "$1000",
      "startsAt": "2024-01-21T18:00:00Z"
    }
  ]
}

Register for Tournament

Request

POST /tournaments/tour_123/register

Response

{
  "success": true,
  "registration": {
    "tournamentId": "tour_123",
    "userId": "user_123",
    "registeredAt": "2024-01-20T15:30:00Z",
    "status": "confirmed"
  }
}

Get Tournament Leaderboard

Request

GET /tournaments/tour_123/leaderboard

Response

{
  "leaderboard": [
    {
      "rank": 1,
      "user": {
        "id": "user_456",
        "username": "speed_demon"
      },
      "score": 285,
      "problemsSolved": 3,
      "totalTime": 1847
    }
  ],
  "userRank": 15,
  "userScore": 190
}

Teams API

Create Team

Request

POST /teams
{
  "name": "Code Warriors",
  "description": "Elite coding team",
  "isPublic": true,
  "maxMembers": 10
}

Response

{
  "id": "team_789",
  "name": "Code Warriors",
  "description": "Elite coding team",
  "owner": {
    "id": "user_123",
    "username": "coder_pro"
  },
  "members": 1,
  "maxMembers": 10,
  "isPublic": true,
  "createdAt": "2024-01-20T16:00:00Z"
}

Invite Team Member

Request

POST /teams/team_789/invite
{
  "username": "ninja_coder",
  "role": "member"
}

Response

{
  "success": true,
  "invitation": {
    "id": "inv_123",
    "teamId": "team_789",
    "inviteeId": "user_456",
    "role": "member",
    "status": "pending",
    "sentAt": "2024-01-20T16:15:00Z"
  }
}

Leaderboards API

Global Leaderboard

Request

GET /leaderboards/global?limit=10&offset=0

Response

{
  "rankings": [
    {
      "rank": 1,
      "user": {
        "id": "user_999",
        "username": "algorithm_god",
        "rating": 2847,
        "tier": "grandmaster"
      },
      "winRate": 0.943,
      "battlesWon": 234
    }
  ],
  "total": 47892,
  "hasMore": true
}

User Rank Info

Request

GET /leaderboards/users/me/rank

Response

{
  "globalRank": 1247,
  "rating": 1750,
  "tier": "platinum",
  "percentile": 85.7,
  "ratingHistory": [
    {
      "date": "2024-01-20",
      "rating": 1750
    }
  ]
}

Error Codes

Status Code

Error Code

Description

400

INVALID_REQUEST

Request body or parameters are invalid

401

UNAUTHORIZED

API key is missing or invalid

403

FORBIDDEN

Insufficient permissions for this action

404

NOT_FOUND

Requested resource does not exist

409

CONFLICT

Resource already exists or action conflicts

429

RATE_LIMITED

Rate limit exceeded

500

INTERNAL_ERROR

Internal server error

Error Response Format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Battle type must be 'quick', 'arena', or 'team'",
    "details": {
      "field": "type",
      "value": "invalid_type"
    },
    "requestId": "req_123456789"
  }
}

Rate Limits

Standard Limits

General API calls1000/hour

Battle submissions100/hour

Tournament registration10/hour

Team operations50/hour

Response Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1705756800
X-RateLimit-Window: 3600

Webhooks

POST /webhooks
{
  "url": "https://your-app.com/webhooks/coderspae",
  "events": ["battle.completed", "tournament.started", "user.rating_changed"],
  "secret": "your_webhook_secret"
}

# Example webhook payload
{
  "event": "battle.completed",
  "timestamp": "2024-01-20T16:30:00Z",
  "data": {
    "battleId": "battle_456",
    "winner": "user_123",
    "participants": ["user_123", "user_456"],
    "duration": 847
  }
}