API Reference

The KidsBuild API is a REST API that powers all platform features. While most developers will use the SDK which wraps these endpoints, you can also call them directly if needed.

Base URL

https://api.kidsbuild.com/api/v1

Authentication

Most endpoints require authentication. Include the access token in the Authorization header:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://api.kidsbuild.com/api/v1/user

To get an access token, use the kb login CLI command or implement the OAuth flow described in the Authentication guide.

Endpoints Overview

User Endpoints

GET /api/v1/user

Returns information about the currently authenticated user.

{
  "id": "user_abc123",
  "username": "coolbuilder42",
  "displayName": "Cool Builder",
  "avatarUrl": "https://cdn.kidsbuild.com/avatars/abc123.png",
  "createdAt": "2026-01-15T10:30:00Z",
  "isVerified": true
}

State Endpoints

GET /api/v1/apps/:appId/state

Retrieves the current user's state for a specific app.

{
  "state": {
    "score": 1500,
    "level": 5,
    "achievements": ["first_win", "speed_demon"]
  },
  "updatedAt": "2026-03-06T14:22:00Z"
}

PUT /api/v1/apps/:appId/state

Updates the current user's state for a specific app.

{
  "state": {
    "score": 2000,
    "level": 6,
    "achievements": ["first_win", "speed_demon", "level_master"]
  }
}

{
  "success": true,
  "updatedAt": "2026-03-06T14:25:00Z"
}

Leaderboard Endpoints

GET /api/v1/apps/:appId/leaderboard

Retrieves the top scores for an app. Optional query parameters:

• limit - Number of entries (default: 10, max: 100)
• offset - Pagination offset
• period - Time period: "all", "week", "day"

{
  "entries": [
    {
      "rank": 1,
      "userId": "user_xyz789",
      "displayName": "ProGamer",
      "avatarUrl": "https://cdn.kidsbuild.com/avatars/xyz789.png",
      "score": 50000,
      "achievedAt": "2026-03-05T18:00:00Z"
    }
  ],
  "total": 1234,
  "userRank": 42
}

POST /api/v1/apps/:appId/leaderboard

Submits a score to the leaderboard.

{
  "score": 2500,
  "metadata": {
    "level": "hard",
    "time": 120
  }
}

Payment Endpoints

POST /api/v1/payments/request

Requests a BuildBucks payment from the current user.

{
  "amount": 50,
  "description": "Unlock premium features",
  "appId": "your-app-id",
  "metadata": {
    "featureId": "premium-pack"
  }
}

{
  "success": true,
  "transactionId": "tx_abc123xyz",
  "newBalance": 150
}

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Not enough BuildBucks for this transaction",
    "details": {
      "required": 50,
      "available": 30
    }
  }
}

Common error codes:

• AUTH_REQUIRED - Missing or invalid authentication
• FORBIDDEN - User doesn't have permission
• NOT_FOUND - Resource doesn't exist
• VALIDATION_ERROR - Invalid request data
• RATE_LIMITED - Too many requests
• INSUFFICIENT_FUNDS - Not enough BuildBucks

Rate Limits

API requests are rate limited to protect the platform. Current limits:

• 100 requests per minute per user
• 1000 requests per hour per app
• State updates: 10 per second per user

Rate limit headers are included in all responses:

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

Interactive API Explorer

Want to try out the API? Check out our interactive API explorer with try-it-out functionality: