> ## Documentation Index
> Fetch the complete documentation index at: https://docs.footycollect.sunr4y.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Item Endpoints

> API endpoints for managing football memorabilia items in FootyCollect

## Overview

The Items API provides endpoints for managing football memorabilia in your collection. Items include jerseys, shorts, outerwear, tracksuits, pants, and other collectibles.

**Base URL**: `/api/items/`

**Authentication**: Token authentication required for all endpoints.

## Interactive API Documentation

<Note>
  Full interactive API documentation for item endpoints is available at `/api/docs/` when running the FootyCollect server. The Swagger UI interface allows you to explore and test all endpoints with real-time responses.
</Note>

## OpenAPI Schema

The complete OpenAPI schema for item endpoints is available at:

```
GET /api/schema/
```

This provides a machine-readable specification of all item endpoints, request/response schemas, and validation rules.

## Item Types

FootyCollect supports the following item types:

* **Jersey** - Football shirts/jerseys
* **Shorts** - Football shorts
* **Outerwear** - Hoodies, jackets, windbreakers, crewnecks
* **Tracksuit** - Training tracksuits
* **Pants** - Training pants
* **Other** - Pins, hats, caps, socks, and other memorabilia

## Common Fields

All items share these base fields from the BaseItem model (see `footycollect/collection/models.py:180-364`):

<Expandable title="Base Item Fields">
  <ResponseField name="id" type="integer">
    Unique identifier for the item
  </ResponseField>

  <ResponseField name="item_type" type="string">
    Type of item: jersey, shorts, outerwear, tracksuit, pants, or other
  </ResponseField>

  <ResponseField name="name" type="string">
    Name or title of the item
  </ResponseField>

  <ResponseField name="user" type="integer">
    ID of the user who owns this item
  </ResponseField>

  <ResponseField name="brand" type="integer">
    ID of the brand (manufacturer)
  </ResponseField>

  <ResponseField name="club" type="integer">
    ID of the football club
  </ResponseField>

  <ResponseField name="season" type="integer">
    ID of the season
  </ResponseField>

  <ResponseField name="condition" type="integer">
    Condition rating from 1-10
  </ResponseField>

  <ResponseField name="detailed_condition" type="string">
    Detailed condition: BNWT, BNWOT, EXCELLENT, VERY\_GOOD, GOOD, FAIR, POOR
  </ResponseField>

  <ResponseField name="description" type="string">
    Item description
  </ResponseField>

  <ResponseField name="is_replica" type="boolean">
    Whether the item is a replica
  </ResponseField>

  <ResponseField name="is_private" type="boolean">
    Whether the item is private
  </ResponseField>

  <ResponseField name="is_draft" type="boolean">
    Whether the item is a draft
  </ResponseField>

  <ResponseField name="design" type="string">
    Design pattern: PLAIN, STRIPES, GRAPHIC, CHEST\_BAND, etc.
  </ResponseField>

  <ResponseField name="main_color" type="integer">
    ID of the main color
  </ResponseField>

  <ResponseField name="created_at" type="datetime">
    When the item was created
  </ResponseField>

  <ResponseField name="updated_at" type="datetime">
    When the item was last updated
  </ResponseField>
</Expandable>

## RESTful Conventions

Item endpoints follow standard RESTful conventions:

* `GET /api/items/` - List all items
* `POST /api/items/` - Create a new item
* `GET /api/items/{id}/` - Retrieve a specific item
* `PUT /api/items/{id}/` - Full update of an item
* `PATCH /api/items/{id}/` - Partial update of an item
* `DELETE /api/items/{id}/` - Delete an item

## Sample Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://localhost:8000/api/items/" \
    -H "Authorization: Token your_auth_token_here"
  ```

  ```python Python theme={null}
  import requests

  url = "http://localhost:8000/api/items/"
  headers = {
      "Authorization": "Token your_auth_token_here"
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```
</CodeGroup>

## Sample Response

```json theme={null}
[
  {
    "id": 1,
    "item_type": "jersey",
    "name": "Real Betis Home 2020-21 - XS - Joaquin#17 - Player Version",
    "brand": 5,
    "club": 12,
    "season": 8,
    "condition": 9,
    "detailed_condition": "EXCELLENT",
    "is_replica": false,
    "is_private": false,
    "is_draft": false,
    "design": "STRIPES",
    "main_color": 3,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]
```

## Jersey-Specific Fields

Jerseys have additional fields (see `footycollect/collection/models.py:379-506`):

<Expandable title="Jersey Fields">
  <ResponseField name="kit" type="integer">
    ID of the kit type (home, away, third, etc.)
  </ResponseField>

  <ResponseField name="size" type="integer">
    ID of the size
  </ResponseField>

  <ResponseField name="is_fan_version" type="boolean">
    Whether it's a fan version (vs player version)
  </ResponseField>

  <ResponseField name="is_signed" type="boolean">
    Whether the jersey is signed
  </ResponseField>

  <ResponseField name="has_nameset" type="boolean">
    Whether the jersey has a player name/number
  </ResponseField>

  <ResponseField name="player_name" type="string">
    Name of the player on the jersey
  </ResponseField>

  <ResponseField name="number" type="integer">
    Player number on the jersey
  </ResponseField>

  <ResponseField name="is_short_sleeve" type="boolean">
    Whether the jersey has short sleeves
  </ResponseField>
</Expandable>

## Learn More

<Card title="OpenAPI Documentation" icon="book" href="/api/docs/">
  Access the full interactive API documentation with request/response examples and the ability to test endpoints directly.
</Card>

<Card title="OpenAPI Schema" icon="code" href="/api/schema/">
  Download the complete OpenAPI specification for integration with API clients and code generation tools.
</Card>