# Using the CardSight AI API - Release Calendar

## Overview
The Release Calendar lists upcoming and recent card product releases sorted by release date (newest first). It is the source of truth for street dates and pre-order windows, and powers "coming soon" feeds, release-day countdowns, and new-product discovery pages. Filter by `segment`, `manufacturer`, and/or `year` to narrow the result set. `segment` and `manufacturer` accept a UUID **or** a case-insensitive name; `year` is an exact string match (e.g. `"2026"`).

## Endpoint Details

- **Method**: GET
- **URL**: `https://api.cardsight.ai/v1/release-calendar/`
- **Authentication**: API Key required (X-Api-Key header)

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| segment | string | No | Filter by segment. UUID **or** case-insensitive name (e.g. `"Basketball"`). |
| manufacturer | string | No | Filter by manufacturer. UUID **or** case-insensitive name (e.g. `"Panini"`). |
| year | string | No | Exact release year (e.g. `"2026"`). UUIDs are **not** accepted here. |
| take | integer | No | Page size. Min 1, max **100**, default 20. |
| skip | integer | No | Pagination offset. Default 0. |

## Using the CardSight AI SDK (Recommended)

### Node.js / TypeScript
```typescript
import { CardSightAI } from 'cardsightai'

const client = new CardSightAI({ apiKey: 'your-api-key' })

const response = await client.releaseCalendar.list({
  manufacturer: 'Panini',
  year: '2026',
  take: 20,
  skip: 0,
})

if (response.error) {
  console.error('Error:', response.error)
} else {
  const data = response.data
  console.log(`Total upcoming: ${data.total_count}`)

  for (const entry of data.release_calendar) {
    const preOrder = entry.pre_order_date ?? 'N/A'
    console.log(`${entry.name} — releases ${entry.release_date} (pre-order: ${preOrder})`)
  }
}
```

### Python
```python
from cardsightai import CardSightAI

client = CardSightAI(api_key='your-api-key')
response = client.release_calendar.list(manufacturer='Panini', year='2026', take=20)

for entry in response.release_calendar:
    print(f"{entry.name} — releases {entry.release_date}")
```

## Direct API Call (cURL)
```bash
curl -X GET "https://api.cardsight.ai/v1/release-calendar/?manufacturer=Panini&year=2026&take=20" \
  -H "X-Api-Key: your-api-key"
```

## Example Response
```json
{
  "release_calendar": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "2026 Panini Prizm Basketball",
      "year": "2026",
      "release_date": "2026-11-12",
      "pre_order_date": "2026-08-01",
      "segment_id": "660e8400-e29b-41d4-a716-446655440001",
      "manufacturer_id": "770e8400-e29b-41d4-a716-446655440002"
    }
  ],
  "total_count": 42,
  "skip": 0,
  "take": 20
}
```

## Response Fields

### Top-Level Response (PaginatedReleaseCalendarResponse)

All four fields are always present.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| release_calendar | ReleaseCalendarEntry[] | Yes | Array of entries matching the query |
| total_count | number | Yes | Total entries matching the query across all pages |
| skip | number | Yes | Offset applied |
| take | number | Yes | Page size applied |

### ReleaseCalendarEntry

Per the OpenAPI spec, every field is always present on every entry. Nullable fields (`year`, `release_date`, `pre_order_date`, `segment_id`, `manufacturer_id`) may be `null` for rumored or placeholder entries — they are never omitted.

| Field | Type | Nullable | Description |
|-------|------|----------|-------------|
| id | UUID | No | Release calendar entry ID |
| name | string | No | Full release name |
| year | string | Yes | Release year |
| release_date | string | Yes | Expected or actual release date (YYYY-MM-DD) |
| pre_order_date | string | Yes | Date when pre-orders open (YYYY-MM-DD) |
| segment_id | UUID | Yes | Associated segment UUID — use with `/v1/catalog/segments/{id}` |
| manufacturer_id | UUID | Yes | Associated manufacturer UUID — use with `/v1/catalog/manufacturers/{id}` |

## Common Use Cases
- Build a "coming soon" or "recently released" feed on your site
- Alert collectors when pre-orders open for a favorite manufacturer
- Drive a release-day countdown or roadmap view
- Feed a marketing page that highlights the next wave of products
- Cross-reference `manufacturer_id` / `segment_id` against the catalog for richer product pages

## Tips for AI Assistants
- **Working with IDs:** The release UUIDs (`id`) here let you look up catalog entities and chain calls together. Caching them briefly to fulfill a user's request is expected and fine — it's why the image and other free endpoints exist. If you need to save cards for the long term, add them to a **list or collection**: those are your own stable resources, purpose-built for holding cards. If you need a bulk or offline copy of catalog data, reach out to us at `support@cardsight.ai` so we can help with your use case.
- Results are sorted by `release_date` with newest first (server-enforced, not configurable). Upcoming future releases appear before released products.
- `manufacturer` and `segment` accept either UUIDs or case-insensitive names. `year` is NOT UUID-compatible — pass the four-digit year as a string.
- Every entry always includes all seven fields, but `year`, `release_date`, `pre_order_date`, `segment_id`, and `manufacturer_id` can be `null` for rumored or placeholder entries — never assume a date is populated.
- `take` is capped at 100. For larger exports, paginate with `skip` and watch `total_count`.
- To list the sets and cards inside a release that has shipped, use `/v1/catalog/releases/{id}` and `/v1/catalog/releases/{id}/cards` — this endpoint is for calendar metadata only.
- The SDK client exposes this as `client.releaseCalendar.list(...)` — the path has a trailing slash (`/v1/release-calendar/`), so construct URLs carefully if calling the REST endpoint directly.