claude-configs/skills/paper-dynasty/reference/api-reference.md

# Paper Dynasty API Reference

**Load this when**: You need API endpoint details, authentication setup, or Python client examples.

---

## Authentication

All API requests require Bearer token:
```bash
export API_TOKEN='your-token-here'
```

Headers:
```python
{'Authorization': f'Bearer {API_TOKEN}'}
```

---

## Environments

| Environment | URL | When to Use |
|-------------|-----|-------------|
| **Production** | `https://pd.manticorum.com/api/v2/` | Default for all operations |
| **Development** | `https://pddev.manticorum.com/api/v2/` | Testing only |

Set via:
```bash
export DATABASE='prod'  # or 'dev'
```

---

## Key Endpoints

### Teams
- `GET /teams` - List teams (params: `season`, `abbrev`, `event`)
- `GET /teams/{id}` - Get team by ID

### Cards
- `GET /cards` - List cards (params: `team_id`, `player_id`)
- `POST /cards/wipe-team/{team_id}` - Unassign all team cards

### Packs
- `GET /packs` - List packs
  - Params: `team_id`, `opened` (true/false), `new_to_old` (true/false), `limit` (e.g., 200, 1000, 2000)
  - Example: `/packs?opened=true&new_to_old=true&limit=200` (200 most recently opened packs)
  - Note: Use extended timeout for large limits (>1000)
- `POST /packs` - Create packs (bulk distribution)
  - Payload: `{'packs': [{'team_id': int, 'pack_type_id': int, 'pack_cardset_id': int|None}]}`
- `DELETE /packs/{id}` - Delete pack

### Gauntlet Runs
- `GET /gauntletruns` - List runs (params: `gauntlet_id`, `team_id`, `is_active`)
- `PATCH /gauntletruns/{id}?ended=true` - End run

### Players
- `GET /players` - List players (params: `cardset`, `rarity`)
- `GET /players/{id}` - Get player by ID

### Results
- `GET /results` - List game results (params: `season`, `team_id`)

### Stats
- `GET /batstats` - Batting statistics
- `GET /pitstats` - Pitching statistics

---

## Using the API Client

### Basic Setup

```python
from api_client import PaperDynastyAPI

# Initialize (reads API_TOKEN from environment)
api = PaperDynastyAPI(environment='prod', verbose=True)

# Or provide token directly
api = PaperDynastyAPI(environment='dev', token='your-token')
```

### Common Operations

```python
# Get a team
team = api.get_team(abbrev='SKB')
team = api.get_team(team_id=69)

# List teams
all_teams = api.list_teams()
season_teams = api.list_teams(season=5)

# List cards for a team
cards = api.list_cards(team_id=69)

# Find gauntlet teams with active runs
active_gauntlet_teams = api.find_gauntlet_teams(event_id=8, active_only=True)

# List gauntlet runs
runs = api.list_gauntlet_runs(event_id=8, active_only=True)

# Get player info
player = api.get_player(player_id=12345)

# List all MVP players
mvp_players = api.list_players(rarity='MVP')
```

### Gauntlet Operations

```python
# Find team
team = api.get_team(abbrev='Gauntlet-SKB')

# Wipe cards
api.wipe_team_cards(team_id=team['id'])

# Delete packs
packs = api.list_packs(team_id=team['id'])
for pack in packs:
    api.delete_pack(pack['id'])

# End run
runs = api.list_gauntlet_runs(team_id=team['id'], active_only=True)
for run in runs:
    api.end_gauntlet_run(run['id'])
```

### Pack Distribution

```python
# Distribute packs to all teams
result = api.distribute_packs(num_packs=10)
print(f"Distributed {result['total_packs']} to {result['teams_count']} teams")

# Distribute with exclusions
result = api.distribute_packs(num_packs=11, exclude_team_abbrev=['CAR', 'SKB'])

# Create specific packs for one team
api.create_packs([
    {'team_id': 31, 'pack_type_id': 1, 'pack_cardset_id': None}
    for _ in range(5)
])

# Create Team Choice pack with specific cardset
api.create_packs([{
    'team_id': 31,
    'pack_type_id': 8,          # Team Choice
    'pack_cardset_id': 27       # 2005 Live
}])
```

### Analytics Operations

```python
# Get packs opened today (built-in analytics)
result = api.get_packs_opened_today()
print(f"{result['total']} packs opened by {len(result['teams'])} teams")
for team in result['teams']:
    print(f"  {team['abbrev']}: {team['packs']} packs")

# Get recent opened packs
recent_packs = api.list_packs(opened=True, new_to_old=True, limit=200)

# Get unopened packs for a team
unopened = api.list_packs(team_id=69, opened=False)

# Large query with extended timeout
all_recent = api.list_packs(opened=True, limit=2000, timeout=30)

# Custom analytics (filter by specific criteria)
from datetime import datetime, timezone, timedelta
packs = api.list_packs(opened=True, limit=1000, timeout=30)
yesterday = (datetime.now(timezone.utc) - timedelta(days=1)).date()
yesterday_packs = [
    p for p in packs
    if p.get('open_time') and
    datetime.fromtimestamp(p['open_time']/1000, tz=timezone.utc).date() == yesterday
]
```

---

## API Client Location

**File**: `~/.claude/skills/paper-dynasty/api_client.py`

**Test connection**:
```bash
cd ~/.claude/skills/paper-dynasty
python api_client.py --env prod --verbose
```