Kits Endpoints

List Kits

curl -X GET "https://your-domain.com/api/kits?club=1&primary_color=Red&page=1&page_size=20" \
  -H "X-API-Key: your-api-key-here"

Retrieve kits with advanced filtering options including club, season, country, colors, design, and year filters.

Query Parameters

Basic Filters

integer

Filter kits by club ID

integer

Filter kits by season ID

string

Filter kits by club country using ISO 2-letter code (e.g., “ES”, “GB”, “FR”)

Color Filters

string

Filter by primary color. Available options: White, Red, Blue, Black, Yellow, Green, Sky blue, Navy, Orange, Gray, Claret, Purple, Pink, Brown, Gold, Silver, Off-white

array

Filter by secondary color(s). Can specify multiple values. Available options: White, Red, Blue, Black, Yellow, Green, Sky blue, Navy, Orange, Gray, Claret, Purple, Pink, Brown, Gold, Silver, Off-white

Design Filter

string

Filter by design pattern. Available options: Plain, Stripes, Graphic, Chest band, Contrasting sleeves, Pinstripes, Hoops, Single stripe, Half-and-half, Sash, Chevron, Checkers, Gradient, Diagonal, Cross, Quarters

Year/Season Filters

integer

Filter by year. Searches in both first_year and second_year of seasons (e.g., 2024 matches “2024-25” and “2023-24”)

integer

Filter by season first year (e.g., 2024 for “2024-25”)

integer

Filter by season second year (e.g., 2025 for “2024-25”). Use with first_year for exact season match

Pagination

integer

default:"1"

Page number (minimum: 1)

integer

default:"20"

Number of items per page (minimum: 1, maximum: 100)

Response

integer

Unique identifier for the kit

string

Full name of the kit

string

URL to the main image of the kit

[
  {
    "id": 1001,
    "name": "Manchester United 2024-25 Home Kit",
    "main_img_url": "https://www.footballkitarchive.com/images/kits/manchester-united-2024-25-home.jpg"
  },
  {
    "id": 1003,
    "name": "Liverpool 2024-25 Home Kit",
    "main_img_url": "https://www.footballkitarchive.com/images/kits/liverpool-2024-25-home.jpg"
  }
]

Examples

curl -X GET "https://your-domain.com/api/kits"

curl -X GET "https://your-domain.com/api/kits?club=1"

curl -X GET "https://your-domain.com/api/kits?primary_color=Red"

curl -X GET "https://your-domain.com/api/kits?secondary_color=White&secondary_color=Blue"

curl -X GET "https://your-domain.com/api/kits?design=Stripes"

curl -X GET "https://your-domain.com/api/kits?year=2024"

curl -X GET "https://your-domain.com/api/kits?first_year=2024&second_year=2025"

curl -X GET "https://your-domain.com/api/kits?country=ES"

curl -X GET "https://your-domain.com/api/kits?primary_color=Red&year=2024&country=ES&design=Stripes"

Results are cached for optimal performance and sorted by ID in descending order.

Get Kit by ID

curl -X GET "https://your-domain.com/api/kits/1001" \
  -H "X-API-Key: your-api-key-here"

Retrieve comprehensive information about a specific kit by its ID, including team, season, competition, brand, colors, and design details.

Path Parameters

integer

required

The unique identifier of the kit

Response

string

Full name of the kit

string

URL-friendly slug for the kit

object

Club information

integer

Club ID

integer

Football Kit Archive internal club ID

string

Club name

string

Club slug

string

URL to club logo

string

URL to club logo (dark theme version)

string

ISO 2-letter country code

object

Season information

integer

Season ID

string

Season year (e.g., “2024-25”)

string

First year of the season (e.g., “2024”)

string

Second year of the season (e.g., “2025”), nullable for single-year seasons

array

Array of competitions the kit was used in

integer

Competition ID

string

Competition name

string

Competition slug

string

URL to competition logo

string

URL to competition logo (dark theme version)

string

ISO 2-letter country code for the competition

object

Kit type information

integer

Kit type ID

string

Kit type name (e.g., “Home”, “Away”, “Third”, “Training”, “Goalkeeper Home”)

string

Kit category: “match” (game kits), “prematch” (pre-match, bench, warm-up), “preseason” (pre-season, temporary), “training” (training kits), “travel” (travel/polo kits), “jacket” (anthem, rain, windbreaker, etc.)

integer

Order of category for sorting (1-6, lower = higher priority)

integer

Priority within category for sorting (lower = higher priority)

boolean

Whether this is a goalkeeper kit

object

Brand information

integer

Brand ID

string

Brand name (e.g., “Adidas”, “Nike”, “Puma”)

string

Brand slug

string

URL to brand logo

string

URL to brand logo (dark theme version)

string

Design pattern of the kit

object

Primary color of the kit

string

Color name

string

Hex color code (e.g., “#FF0000”)

array

Array of secondary colors

string

Color name

string

Hex color code

string

URL to the main image of the kit

{
  "name": "Manchester United 2024-25 Home Kit",
  "slug": "manchester-united-2024-25-home-kit",
  "team": {
    "id": 1,
    "id_fka": 1001,
    "name": "Manchester United",
    "slug": "manchester-united-kits",
    "logo": "https://www.footballkitarchive.com/images/logos/clubs/manchester-united.png",
    "logo_dark": "https://www.footballkitarchive.com/images/logos/clubs/manchester-united-dark.png",
    "country": "GB"
  },
  "season": {
    "id": 123,
    "year": "2024-25",
    "first_year": "2024",
    "second_year": "2025"
  },
  "competition": [
    {
      "id": 1,
      "name": "Premier League",
      "slug": "premier-league-kits",
      "logo": "https://www.footballkitarchive.com/images/logos/competitions/premier-league.png",
      "logo_dark": "https://www.footballkitarchive.com/images/logos/competitions/premier-league-dark.png",
      "country": "GB"
    },
    {
      "id": 5,
      "name": "UEFA Champions League",
      "slug": "uefa-champions-league-kits",
      "logo": "https://www.footballkitarchive.com/images/logos/competitions/ucl.png",
      "logo_dark": "https://www.footballkitarchive.com/images/logos/competitions/ucl-dark.png",
      "country": null
    }
  ],
  "type": {
    "id": 1,
    "name": "Home",
    "category": "match",
    "category_order": 1,
    "order_priority": 1,
    "is_goalkeeper": false
  },
  "brand": {
    "id": 1,
    "name": "Adidas",
    "slug": "adidas-kits",
    "logo": "https://www.footballkitarchive.com/images/logos/brands/adidas.png",
    "logo_dark": "https://www.footballkitarchive.com/images/logos/brands/adidas-dark.png"
  },
  "design": "Plain",
  "primary_color": {
    "name": "Red",
    "color": "#DA020E"
  },
  "secondary_color": [
    {
      "name": "White",
      "color": "#FFFFFF"
    },
    {
      "name": "Black",
      "color": "#000000"
    }
  ],
  "main_img_url": "https://www.footballkitarchive.com/images/kits/manchester-united-2024-25-home.jpg"
}

Results are cached for optimal performance.

Get Random Kits

Retrieve a paginated list of random kits for discovery and browsing.

Endpoint

GET /api/random-kits/

Query Parameters

integer

default:"1"

Page number (must be ≥ 1)

integer

default:"20"

Number of items per page (max: 100)

Response

Returns a paginated array of kit objects with reduced schema for performance.

array

Array of random kit objects

integer

Kit ID

string

Kit name

string

Kit slug

string

URL to main kit image

string

Team/club name

string

Season year (e.g., “2024-25”, “2023”)

string

Kit type name (e.g., “Home”, “Away”, “Third”)

string

Brand name (e.g., “Adidas”, “Nike”)

string

Formatted color display string (e.g., “Red, White”)

Example Request

curl "http://localhost:8000/api/random-kits/?page=1&page_size=20"

import requests

response = requests.get(
    'http://localhost:8000/api/random-kits/',
    params={'page': 1, 'page_size': 20}
)
kits = response.json()

const response = await fetch(
  'http://localhost:8000/api/random-kits/?page=1&page_size=20'
);
const kits = await response.json();

Example Response

[
  {
    "id": 123,
    "name": "Arsenal 2024-25 Home Kit",
    "slug": "arsenal-2024-25-home-kit",
    "main_img_url": "https://www.footballkitarchive.com/images/kits/...",
    "team_name": "Arsenal",
    "season_year": "2024-25",
    "type_name": "Home",
    "brand_name": "Adidas",
    "colors_display": "Red, White"
  },
  {
    "id": 456,
    "name": "Bayern Munich 2023-24 Away Kit",
    "slug": "bayern-munich-2023-24-away-kit",
    "main_img_url": "https://www.footballkitarchive.com/images/kits/...",
    "team_name": "Bayern Munich",
    "season_year": "2023-24",
    "type_name": "Away",
    "brand_name": "Adidas",
    "colors_display": "Black, Gold"
  }
]

Use Cases

Random kit discovery on homepage or explore pages
Kit browsing without specific search criteria
Generating varied kit collections for display

Random selection is performed using database-level randomization for efficiency.

Overview

Endpoints

Advanced

Kits Endpoints

List Kits

Query Parameters

Basic Filters

Color Filters

Design Filter

Year/Season Filters

Response

Examples

Get Kit by ID

Path Parameters

Response

Get Random Kits

Endpoint

Query Parameters

Response

Example Request

Example Response

Use Cases

​List Kits

​Query Parameters

​Basic Filters

​Color Filters

​Design Filter

​Year/Season Filters

​Pagination

​Response

​Examples

​Get Kit by ID

​Path Parameters

​Response

​Get Random Kits

​Endpoint

​Query Parameters

​Response

​Example Request

​Example Response

​Use Cases

List Kits

Query Parameters

Basic Filters

Color Filters

Design Filter

Year/Season Filters

Pagination

Response

Examples

Get Kit by ID

Path Parameters

Response

Get Random Kits

Endpoint

Query Parameters

Response

Example Request

Example Response

Use Cases