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

club

integer

Filter kits by club ID

season

integer

Filter kits by season ID

country

string

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

Color Filters

primary_color

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

secondary_color

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

design

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

year

integer

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

first_year

integer

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

second_year

integer

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

Pagination

page

integer

default:"1"

Page number (minimum: 1)

page_size

integer

default:"20"

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

Response

integer

Unique identifier for the kit

name

string

Full name of the kit

main_img_url

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

kit_id

integer

required

The unique identifier of the kit

Response

name

string

Full name of the kit

slug

string

URL-friendly slug for the kit

team

object

Club information

team.id

integer

Club ID

team.id_fka

integer

Football Kit Archive internal club ID

team.name

string

Club name

team.slug

string

Club slug

team.logo

string

URL to club logo

team.logo_dark

string

URL to club logo (dark theme version)

team.country

string

ISO 2-letter country code

season

object

Season information

season.id

integer

Season ID

season.year

string

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

season.first_year

string

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

season.second_year

string

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

competition

array

Array of competitions the kit was used in

competition[].id

integer

Competition ID

competition[].name

string

Competition name

competition[].slug

string

Competition slug

competition[].logo

string

URL to competition logo

competition[].logo_dark

string

URL to competition logo (dark theme version)

competition[].country

string

ISO 2-letter country code for the competition

type

object

Kit type information

type.id

integer

Kit type ID

type.name

string

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

type.category

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.)

type.category_order

integer

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

type.order_priority

integer

Priority within category for sorting (lower = higher priority)

type.is_goalkeeper

boolean

Whether this is a goalkeeper kit

brand

object

Brand information

brand.id

integer

Brand ID

brand.name

string

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

brand.slug

string

Brand slug

brand.logo

string

URL to brand logo

brand.logo_dark

string

URL to brand logo (dark theme version)

design

string

Design pattern of the kit

primary_color

object

Primary color of the kit

primary_color.name

string

Color name

primary_color.color

string

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

secondary_color

array

Array of secondary colors

secondary_color[].name

string

Color name

secondary_color[].color

string

Hex color code

main_img_url

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

page

integer

default:"1"

Page number (must be ≥ 1)

page_size

integer

default:"20"

Number of items per page (max: 100)

Response

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

kits

array

Array of random kit objects

kits[].id

integer

Kit ID

kits[].name

string

Kit name

kits[].slug

string

Kit slug

kits[].main_img_url

string

URL to main kit image

kits[].team_name

string

Team/club name

kits[].season_year

string

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

kits[].type_name

string

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

kits[].brand_name

string

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

kits[].colors_display

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.

​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