API Documentation
Explore the complete Balla Stats API with interactive Swagger documentation. Test endpoints, view schemas, and authenticate directly in the browser.
Prerequisites
Before exploring the API documentation, you need:
- A Balla Stats account
- Basic understanding of REST APIs
Explore the complete Balla Stats API with interactive Swagger documentation. Test endpoints, view schemas, and authenticate directly in the browser.
Try Endpoints
Execute API calls live
View Schemas
TypeScript-compatible types
Authentication
JWT and API key support
- Access API docs
- Authenticate in Swagger
- Explore endpoints
- Try an API call
- Understand response schemas
- Common API patterns
Navigate to /api-docs in your browser, or click API Docs in the sidebar. The Swagger UI loads the complete API reference with all available endpoints.
Click the "Authorize" button at the top of the page. Enter your Bearer token - either a JWT from login or an API key. This authenticates all subsequent requests made through the Swagger UI.
Endpoints are organized by category for easy navigation. Expand any section to see the available operations:
Click "Try it out" on any endpoint to make it interactive. Fill in the required parameters, then click "Execute". The response body, headers, and status code are displayed below.
Expand the Schema section below any endpoint to see the full response structure. These types are compatible with the TypeScript definitions in the @balla-stats/types package, making it straightforward to build type-safe integrations.
Schema Features
- Field types: String, number, boolean, array, object with exact type definitions
- Required fields: Clearly marked to distinguish optional from required properties
- Enums: Exact allowed values for status fields, roles, and types
- Nested objects: Expandable to show full relationship structure
The Balla Stats API follows consistent patterns across all endpoints:
Pagination
Use page and limit query parameters. Responses include total count and current page metadata.
Filtering
Filter results with query parameters like status, teamId, seasonId, and date ranges.
Error Responses
Consistent format with message and statusCode fields. Validation errors include field-level details.
Date Formats
All dates use ISO 8601 format (e.g., 2026-02-16T10:30:00.000Z). Timestamps are always in UTC.
Test Before Coding
Use Swagger for testing before writing integration code. Verify endpoints return the data you expect.
Check All Fields
Check response schemas for all available fields. Responses often include more data than you might expect.
Rate Limits Apply
Rate limits apply to Swagger requests too. Use API keys for higher limits when testing extensively.
401 Error in Swagger
- Click the Authorize button and enter your token first
- Ensure you include the full token without extra spaces
- JWT tokens expire - log in again if your session has timed out
Empty Responses
- Check that query parameters are correct (e.g., valid group ID)
- Verify you have access to the requested resource
- Ensure the resource exists - try listing all items first