Skip to main content
Use this endpoint to retrieve human-readable descriptions of the SquadAssist role taxonomy. You can either look up a single role by name or fetch the complete list of all roles and their descriptions in one call. Role values returned here correspond to the player_role field in GET /api/player_info.

​
Authentication

All requests must include a valid API key, either as an x-api-key header or as a Bearer token in the Authorization header. 
x-api-key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY

​
Request

​
role
string
The role value to look up (e.g., "Box-to-Box Midfielder", "Goalkeeper"). If omitted, all role descriptions are returned. The value must exactly match one of the role names listed in the Roles Reference below.

​
Response

When role is provided:
​
role
string
The role name as supplied in the request.
​
description
string
A description of the role’s tactical characteristics and responsibilities.
When role is omitted:
​
descriptions
array
An array containing all role objects.

​
Errors

StatusDescription
400The role parameter was provided but does not match any known role. The error response includes an allowed_roles array listing all valid values.

​
Examples

curl -s "https://api.squadassist.ai/v1/role_description?role=Box-to-Box%20Midfielder" \
  -H "x-api-key: YOUR_API_KEY"
Single role response
{
  "role": "Box-to-Box Midfielder",
  "description": "A Box-to-Box Midfielder is a midfielder that moves further up the field as the play progresses. During defensive actions, they are positioned like a CDM while they are positioned as a CAM during offensive play."
}
All roles response (truncated)
{
  "descriptions": [
    {
      "role": "Goalkeeper",
      "description": "The role for all players that are primarily goalkeepers"
    },
    {
      "role": "Box-to-Box Midfielder",
      "description": "A Box-to-Box Midfielder is a midfielder that moves further up the field as the play progresses. During defensive actions, they are positioned like a CDM while they are positioned as a CAM during offensive play."
    }
  ]
}