stackgate.ai
All integrations
API-Sports Handball

Handball

Access handball games, live scores, leagues, standings, teams, players, game events, statistics and head-to-head data.

Manual setup 13 tools

Overview

Connect Handball so AI clients can retrieve competitions, teams, players, games, live scores, standings, game events, statistics, and head-to-head history.

stackgate.ai stores your API-Sports Handball API key encrypted and calls the provider on your behalf. Tool results are returned to your AI client for that request. Responses are cached briefly on the hub (by connection) to reduce duplicate upstream calls and protect your daily quota.

This integration is read-only. Public tool names and response shapes are provider-neutral; the initial upstream provider is API-Sports (Handball).

Prerequisites

  • An API-Sports account with Handball API access and an API key
  • A stackgate.ai account

Getting credentials

  1. Sign in to stackgate.ai.
  2. Go to My Integrations and open Handball.
  3. In a separate tab, open the API-Sports dashboard.
  4. Confirm your subscription includes Handball, then go to Account → My Access and copy your API key.
  5. Paste the key into stackgate.ai and click Save.
  6. stackgate.ai runs a lightweight connection test (/status). On success you may see your plan name and daily request limit.
  7. Optionally use Edit tool access to limit which read tools the connection may use.

Use dashboard keys for https://v1.handball.api-sports.io (header x-apisports-key). RapidAPI host/key pairs are not supported in this integration.

Treat the API key like a password. Regenerate it in the API-Sports dashboard if it is exposed.

Using with AI clients

  • Dedicated endpoint: POST /mcp/handball with a Sanctum bearer token
  • Private gateway: one config for all integrations — use handball__* namespaced tools

See Documentation for HTTP authentication and private gateway setup.

Example prompts

  • Show me the current Champions League standings.
  • Find a team's next five games.
  • Which games are currently live?
  • Show events and statistics from game 12345.
  • Find information about a player.
  • Compare the latest games between two teams.

Suggested workflow

  1. search_competitions / list_seasons — resolve competition_id and season year.
  2. get_standings / search_games — many queries need season as YYYY.
  3. get_live_games — in-play games only.
  4. get_game — summary; use events/statistics tools for detail.
  5. search_teams / search_players — then get tools for profiles.
  6. get_head_to_head — historical games between two teams.

Pagination

Where the provider paginates (for example players), pass page and optionally limit. Responses include pagination with page, total_pages, total_results, and has_more. The hub does not auto-fetch every page.

Caching and freshness

Approximate hub cache durations (per connection):

Data Cache
Competitions / seasons ~24 hours
Teams ~12 hours
Players ~6 hours
Standings / upcoming games ~10 minutes
Completed games ~24 hours
Live games / events ~20 seconds
Game statistics ~2 minutes

Authentication failures are never cached. Live scores can lag a short cache window.

Rate limits

API-Sports plans have a daily request quota and a per-minute cap. Free plans are often around 100 requests/day. Prefer cached tools, specific IDs, and small date windows. A 429 or provider “request limit” error means wait or upgrade your API-Sports plan.

Data licensing notice

stackgate.ai provides access to data returned by the connected provider. Availability and permitted use depend on the provider’s terms and your subscription. Official league branding, logos, and media may have separate rights restrictions. You are responsible for ensuring usage complies with the provider’s terms and applicable rights.

Troubleshooting

  • 422 integration not configured — add your API-Sports Handball API key in My Integrations.
  • Connection test failed / invalid key — confirm the key from Account → My Access and that Handball is on your plan (not a RapidAPI key).
  • 401 / authentication failed — regenerate the key and update My Integrations.
  • 429 / request limit — you hit the provider quota; wait, reduce tool calls, or upgrade your plan.
  • Empty items — no matching data for those filters/season, or your plan does not cover that season.
  • season required — standings and many game queries need a season year (YYYY).

Available tools

  • search_competitions

    Search handball leagues and competitions. Use when you need a competition_id, available seasons, or coverage info. Do not use for games or standings.

  • list_seasons

    List available handball seasons (years). Optionally filter by competition_id.

  • search_teams

    Search handball teams by name, ID, competition+season, or country. Requires at least one filter.

  • get_team

    Get a normalized team profile.

  • search_players

    Search players by name, ID, team, or competition. Season is required for most searches. Use get_player for a single profile.

  • get_player

    Get a normalized player profile. Pass season when you need season-specific team/position context.

  • search_games

    Search games by date, competition, team, last/next N, or game_id. For live games use get_live_games. For two-team history use get_head_to_head.

  • get_live_games

    Return currently live games. Optionally filter by competition IDs. Cached briefly (~20s).

  • get_game

    Get a single game summary (teams, score, status, venue). Does not include events or detailed statistics — use dedicated tools for those.

  • get_game_events

    Game events sorted chronologically. Returns empty items[] when events are unavailable for the game.

  • get_game_statistics

    Team-level game statistics. Values keep original units/labels from the provider.

  • get_standings

    League table / standings for a competition and season. Supports multi-group competitions.

  • get_head_to_head

    Historical games between two teams. Prefer this over search-games when comparing two clubs.

MCP endpoint: https://stackgate.ai/mcp/handball (HTTP) or via the private gateway.

Create account Documentation