# CoachHelpr

> CoachHelpr makes lineup proposals and keeps playing time fair for youth sports coaches. Its integration API lets your server read the start lineup of one team, over REST or MCP, with that team's API key.

Every call carries the team's key as `Authorization: Bearer chk_...`. The key names the team, so a call needs no team id, body or query. The answer is the start lineup of the match being played now, else of the next match, else the team's standard lineup. Players come by first name, initials and shirt number only, never a last name. 60 calls per minute per key: polling once a minute is plenty. There are no CORS headers, so call it from a server. A coach of the team makes the key in the CoachHelpr app (Meer, Teams, the team, Koppelingen) and gives it to you; it stops working when that coach no longer coaches the team, and every coach of the team can revoke it.

`GET https://coachhelpr.app/api/v1/integration/start-lineup` answers, for example:

```json
{
  "team": {
    "name": "MO14-1",
    "clubName": "HC De Linden"
  },
  "source": "match",
  "match": {
    "kickoffAt": "2026-10-10T10:30:00.000Z",
    "opponent": "HC Oosterpark MO14-2",
    "isHome": true,
    "pitch": "Veld 2",
    "running": false
  },
  "lineupStatus": "confirmed",
  "formation": "3-3-3-1",
  "slots": [
    {
      "slot": 1,
      "positionCode": "K",
      "line": "keeper",
      "x": 50,
      "y": 95,
      "player": {
        "firstName": "Noa",
        "initials": "NB",
        "shirtNumber": 1,
        "isCaptain": false
      }
    },
    {
      "slot": 2,
      "positionCode": "CA",
      "line": "defence",
      "x": 50,
      "y": 80,
      "player": {
        "firstName": "Amira",
        "initials": "AY",
        "shirtNumber": 4,
        "isCaptain": true
      }
    },
    {
      "slot": 3,
      "positionCode": "LA",
      "line": "defence",
      "x": 20,
      "y": 64,
      "player": {
        "firstName": "Fleur",
        "initials": "FJ",
        "shirtNumber": 3,
        "isCaptain": false
      }
    },
    {
      "slot": 4,
      "positionCode": "VS",
      "line": "defence",
      "x": 50,
      "y": 67,
      "player": {
        "firstName": "Lotte",
        "initials": "LV",
        "shirtNumber": 5,
        "isCaptain": false
      }
    },
    {
      "slot": 5,
      "positionCode": "RA",
      "line": "defence",
      "x": 80,
      "y": 64,
      "player": {
        "firstName": "Sara",
        "initials": "SK",
        "shirtNumber": 2,
        "isCaptain": false
      }
    },
    {
      "slot": 6,
      "positionCode": "LM",
      "line": "midfield",
      "x": 20,
      "y": 45,
      "player": {
        "firstName": "Julia",
        "initials": "JM",
        "shirtNumber": 8,
        "isCaptain": false
      }
    },
    {
      "slot": 7,
      "positionCode": "MM",
      "line": "midfield",
      "x": 50,
      "y": 48,
      "player": {
        "firstName": "Evi",
        "initials": "ED",
        "shirtNumber": 6,
        "isCaptain": false
      }
    },
    {
      "slot": 8,
      "positionCode": "RM",
      "line": "midfield",
      "x": 80,
      "y": 45,
      "player": {
        "firstName": "Tess",
        "initials": "TH",
        "shirtNumber": 7,
        "isCaptain": false
      }
    },
    {
      "slot": 9,
      "positionCode": "LV",
      "line": "attack",
      "x": 20,
      "y": 25,
      "player": {
        "firstName": "Mila",
        "initials": "MS",
        "shirtNumber": 11,
        "isCaptain": false
      }
    },
    {
      "slot": 10,
      "positionCode": "SP",
      "line": "attack",
      "x": 50,
      "y": 15,
      "player": {
        "firstName": "Zoë",
        "initials": "ZP",
        "shirtNumber": 9,
        "isCaptain": false
      }
    },
    {
      "slot": 11,
      "positionCode": "RV",
      "line": "attack",
      "x": 80,
      "y": 25,
      "player": null
    }
  ],
  "bench": [
    {
      "firstName": "Iris",
      "initials": "IW",
      "shirtNumber": 14,
      "isCaptain": false
    },
    {
      "firstName": "Yara",
      "initials": "YB",
      "shirtNumber": 16,
      "isCaptain": false
    }
  ],
  "serverTime": "2026-10-07T14:02:11.000Z"
}
```

## Docs

- [Developer page](https://coachhelpr.app/developers): what you can read, how to get a key, examples, every field, errors and limits, and the MCP setup
- [OpenAPI document](https://coachhelpr.app/api/v1/integration/openapi.json): OpenAPI 3.1 for the start lineup endpoint, with the example above

## MCP

- [MCP endpoint](https://coachhelpr.app/api/v1/integration/mcp): Streamable HTTP, stateless, JSON answers, the same key as a Bearer header; one tool, `get_start_lineup`, without arguments, which answers what the REST endpoint answers