API Reference

ASCND uses the Connect Protocol for type-safe RPC communication. All endpoints accept JSON and return JSON.

Base URL

https://api.ascnd.gg

Authentication

All API requests require authentication via an API key in the Authorization header:

Authorization: Bearer your_api_key_here

Get your API key from the ASCND Dashboard.

Request Format

All requests use POST method with a JSON body. The endpoint path follows the pattern:

POST /ascnd.v1.AscndService/{MethodName}
Content-Type: application/json

Example Request

curl -X POST https://api.ascnd.gg/ascnd.v1.AscndService/SubmitScore \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "leaderboard_id": "lb_xxx",
    "player_id": "player_123",
    "score": "50000"
  }'

Scores as strings

Large integers (like score) are sent as strings in JSON to preserve precision. The SDK handles this automatically.

Available Endpoints

Endpoint	Description
SubmitScore	Record a player's score
GetLeaderboard	Retrieve top scores
GetPlayerRank	Get a player's rank

Error Handling

Errors are returned with appropriate HTTP status codes and a JSON body:

{
  "code": "invalid_argument",
  "message": "leaderboard_id is required"
}

Common Error Codes

Code	HTTP Status	Description
invalid_argument	400	Missing or invalid request parameter
unauthenticated	401	Missing or invalid API key
permission_denied	403	API key doesn't have access to this resource
not_found	404	Leaderboard or player not found
resource_exhausted	429	Rate limit exceeded
internal	500	Server error

Rate Limits

• Free tier: 100 requests/minute
• Pro tier: 1,000 requests/minute
• Enterprise: Custom limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200