# Using the Autocomplete APIs

## Overview
Get autocomplete suggestions for search queries across different entity types. The API provides 6 specialized endpoints for segments, manufacturers, years, releases, sets, and cards. Each returns up to 10 matching suggestions sorted alphabetically (or chronologically for years).

## Endpoints

| Method | URL | Description |
|--------|-----|-------------|
| GET | /v1/autocomplete/segments | Segment name suggestions |
| GET | /v1/autocomplete/manufacturers | Manufacturer name suggestions |
| GET | /v1/autocomplete/years | Year suggestions |
| GET | /v1/autocomplete/releases | Release name suggestions |
| GET | /v1/autocomplete/sets | Set name suggestions |
| GET | /v1/autocomplete/cards | Card name suggestions |

**Authentication**: API Key required (X-Api-Key header)

## Parameters by Endpoint

### Segments
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| q | string | Yes | Search query (minimum 1 character) |

### Manufacturers
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| q | string | Yes | Search query (minimum 1 character) |
| segmentId | UUID | No | Filter by segment |

### Years
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| q | string | Yes | Search query (minimum 1 character) |
| segmentId | UUID | No | Filter by segment |
| manufacturerId | UUID | No | Filter by manufacturer |

### Releases
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| q | string | Yes | Search query (minimum 1 character) |
| segmentId | UUID | No | Filter by segment |
| manufacturerId | UUID | No | Filter by manufacturer |
| year | string | No | Filter by year (e.g., "2023") |

### Sets
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| q | string | Yes | Search query (minimum 1 character) |
| releaseId | UUID | No | Filter by release |
| segmentId | UUID | No | Filter by segment (when releaseId not provided) |
| manufacturerId | UUID | No | Filter by manufacturer (when releaseId not provided) |
| year | string | No | Filter by year (when releaseId not provided) |

### Cards
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| q | string | Yes | Search query (minimum 1 character) |
| setId | UUID | No | Filter by set |
| releaseId | UUID | No | Filter by release (when setId not provided) |
| segmentId | UUID | No | Filter by segment (for broader search) |
| manufacturerId | UUID | No | Filter by manufacturer (for broader search) |
| year | string | No | Filter by year (for broader search) |

## Using the CardSight AI SDK (Recommended)

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

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

// Autocomplete card names
const cardResponse = await client.autocomplete.cards('Ohtani')

if (cardResponse.error) {
  console.error('Error:', cardResponse.error)
} else {
  for (const suggestion of cardResponse.data.suggestions) {
    console.log(suggestion)
  }
}

// Autocomplete releases with filters
const releaseResponse = await client.autocomplete.releases('Topps', {
  year: '2023'
})

if (!releaseResponse.error) {
  console.log('Matching releases:', releaseResponse.data.suggestions)
}

// Autocomplete sets within a specific release
const setResponse = await client.autocomplete.sets('Base', {
  releaseId: '550e8400-e29b-41d4-a716-446655440000'
})
```

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

client = CardSightAI(api_key='your-api-key')

# Autocomplete card names
response = client.autocomplete.cards('Ohtani')

for suggestion in response.suggestions:
    print(suggestion)

# Autocomplete with filters
response = client.autocomplete.releases('Topps', year='2023')
print(response.suggestions)
```

## Direct API Calls (cURL)

```bash
# Autocomplete card names
curl -X GET "https://api.cardsight.ai/v1/autocomplete/cards?q=Ohtani" \
  -H "X-Api-Key: your-api-key"

# Autocomplete releases filtered by year
curl -X GET "https://api.cardsight.ai/v1/autocomplete/releases?q=Topps&year=2023" \
  -H "X-Api-Key: your-api-key"

# Autocomplete sets within a release
curl -X GET "https://api.cardsight.ai/v1/autocomplete/sets?q=Base&releaseId=550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Api-Key: your-api-key"

# Autocomplete segments
curl -X GET "https://api.cardsight.ai/v1/autocomplete/segments?q=Base" \
  -H "X-Api-Key: your-api-key"
```

## Example Response
All autocomplete endpoints return the same response structure:

```json
{
  "suggestions": [
    "Shohei Ohtani",
    "Shohei Ohtani RC",
    "Shohei Ohtani Auto"
  ]
}
```

## Response Fields

| Field | Type | Description |
|-------|------|-------------|
| suggestions | array | Array of matching strings (max 10 items) |

## Common Use Cases
- Build search-as-you-type interfaces
- Power dropdown suggestions in forms
- Help users discover available content
- Create cascading filter dropdowns (segment → manufacturer → year → release → set → card)

## Tips for AI Assistants
- **Working with IDs:** The `releaseId` and `setId` filters accept catalog UUIDs you can use to look up 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.
- The SDK returns `{ data, error }` - always check for errors first
- All endpoints require minimum 1 character for the query
- Results are limited to 10 suggestions maximum
- Segments and manufacturers return alphabetically sorted results
- Years return chronologically sorted results
- Use filter parameters to narrow suggestions (e.g., filter releases by manufacturer)
- The cascading filter pattern works well: get segments first, then use segmentId to filter manufacturers, etc.