Skip to main content
The TeamBattles API allows you to programmatically access your match data and integrate with external services like Twitch.

​
Base URL

All API endpoints are served from: 
https://teambattles.gg/api/v1

​
Authentication

All API requests require authentication using an API key. You can generate API keys from Settings > Developer in the TeamBattles app. Include your API key in the Authorization header: 
Authorization: Bearer tb_your_api_key_here
Keep your API keys secret. Never expose them in client-side code or public repositories.

​
Permissions

API keys have granular permissions that control what they can access:
PermissionDescription
matches.user_matchesAccess to your match data
matches.team_matchesAccess to matches for teams you’re a member of
matches.org_matchesAccess to matches for organizations you’re a member of
connections.twitchAccess to Twitch integration (requires Twitch account connection)
connections.discordAccess to Discord integration
connections.githubAccess to GitHub integration
connections.battlenetAccess to Battle.net integration
When creating an API key, you select which permissions to enable. Endpoints will return a 403 error if the required permission is not enabled.

​
Rate Limiting

API requests are rate limited to ensure fair usage. Current limits:
  • 100 requests per minute per API key
If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

​
Error Responses

All error responses follow a consistent format: 
{
  "error": "error_code",
  "details": "Additional information (optional)"
}

​
Common Error Codes

CodeHTTP StatusDescription
error_api_key_required401No API key provided in Authorization header
error_api_key_invalid401API key is invalid or revoked
error_api_key_permission_denied403API key lacks required permission
error_team_membership_required403User is not an active member of the team
error_org_membership_required403User is not an active member of the organization
error_team_not_found404Team ID or slug not found
error_org_not_found404Organization ID or slug not found
error_invalid_request400Request body or parameters are invalid
error_invalid_cursor400Pagination cursor is invalid or expired
error_invalid_limit400Limit must be between 1 and 100
error_invalid_date_format400Date parameter is not valid ISO 8601
error_internal500Internal server error

​
Available Endpoints

User Matches

Retrieve matches where you’re on the roster

Team Matches

Retrieve matches for a specific team

Organization Matches

Retrieve matches for all teams in an organization

Twitch Badges

Access Twitch badge data for chat overlays

​
SDKs & Libraries

We don’t currently provide official SDKs, but the API is straightforward to use with any HTTP client: 
const response = await fetch('https://teambattles.gg/api/v1/user/matches', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tb_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    excludeStatuses: ['COMPLETED', 'CANCELLED']
  })
});

const data = await response.json();
console.log(`Found ${data.count} matches`);

​
Need Help?

Support

Contact our support team

Discord

Join our Discord community