### Get Random Deck from Any Set

Source: https://context7.com/cardsofkeyforge/api/llms.txt

Fetches a random KeyForge deck. No specific set is required.

```bash
curl -X GET "https://api.cardsofkeyforge.com/decks/random"
```

--------------------------------

### Get Cards API

Source: https://context7.com/cardsofkeyforge/api/llms.txt

Search and filter KeyForge cards from the database with multiple query parameters including set, house, card type, rarity, amber value, power, armor, and special card types like mavericks and anomalies. The API returns localized card data based on the `Accept-Language` header.

```APIDOC
## GET /cards

### Description
Search and filter KeyForge cards from the database with multiple query parameters including set, house, card type, rarity, amber value, power, armor, and special card types like mavericks and anomalies. The API returns localized card data based on the `Accept-Language` header.

### Method
GET

### Endpoint
/cards

### Query Parameters
- **set** (string) - Optional - Filter by expansion set (e.g., "cota", "wc").
- **name** (string) - Optional - Search cards by name with partial matching.
- **house** (string) - Optional - Filter by house (e.g., "Logos", "Dis").
- **type** (string) - Optional - Filter by card type (e.g., "creature").
- **amber** (integer) - Optional - Filter by minimum amber value.
- **power** (integer) - Optional - Filter by minimum power value.
- **armor** (integer) - Optional - Filter by armor value.
- **anomaly** (boolean) - Optional - Filter for anomaly cards (true/false).
- **maverick** (boolean) - Optional - Filter for maverick cards (true/false).
- **rarity** (string) - Optional - Filter by rarity (e.g., "Common", "Rare").

### Request Example
```bash
curl -X GET "https://api.cardsofkeyforge.com/cards?set=cota&house=Logos&type=creature&amber=2&anomaly=true"
  -H "Accept-Language: en"
```

### Response
#### Success Response (200)
- **card_title** (string) - The title of the card.
- **set** (string) - The set the card belongs to.
- **amber** (integer) - The amber value of the card.
- **card_number** (string) - The card's number within its set.
- **card_text** (string) - The text description of the card's abilities.
- **card_type** (string) - The type of the card (e.g., "Creature").
- **expansion** (integer) - The expansion ID.
- **flavor_text** (string) - Flavor text associated with the card.
- **houses** (array) - An array of house objects the card belongs to.
- **is_anomaly** (boolean) - Indicates if the card is an anomaly.
- **is_maverick** (boolean) - Indicates if the card is a maverick.
- **power** (string) - The power value of the card.
- **armor** (string) - The armor value of the card.
- **rarity** (string) - The rarity of the card.
- **traits** (string) - Traits associated with the card.

#### Response Example
```json
[
  {
    "card_title": "Ember Imp",
    "set": "cota",
    "amber": 0,
    "card_number": "51",
    "card_text": "Play: Deal 2 damage to a creature.",
    "card_type": "Creature",
    "expansion": 341,
    "flavor_text": "He's very passionate about his work.",
    "houses": [{"id": "dis-51", "house": "Dis", "normal": "...", "zoom": "..."}],
    "is_anomaly": false,
    "is_maverick": false,
    "power": "2",
    "armor": "0",
    "rarity": "Common",
    "traits": "Imp"
  }
]
```
```

--------------------------------

### Get Random Deck

Source: https://context7.com/cardsofkeyforge/api/llms.txt

Retrieve a random KeyForge deck. You can optionally filter by set.

```APIDOC
## GET /decks/random

### Description
Retrieves a random KeyForge deck. Supports filtering by expansion set.

### Method
GET

### Endpoint
/decks/random

### Query Parameters
- **set** (string) - Optional - The code of the expansion set to draw a deck from. Defaults to 'all' (any set).
  Supported set codes: 'all', 'cota', 'aoa', 'wc', 'anomaly', 'mm', 'dt', 'woe', 'rotk', 'tac'.

### Response
#### Success Response (200)
- **Id** (string) - The unique identifier of the deck.
- **Name** (string) - The name of the deck.
- **Expansion** (integer) - The expansion ID the deck belongs to.

### Response Example
```json
{
  "Id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "Name": "A. J. Sereena, the Madwoman of the Den",
  "Expansion": 341
}
```
```

--------------------------------

### Get Random Deck from Specific Set

Source: https://context7.com/cardsofkeyforge/api/llms.txt

Fetches a random KeyForge deck from a specified set using its code. Supported set codes include 'cota', 'aoa', 'wc', 'mm', 'dt', 'woe', and others.

```bash
curl -X GET "https://api.cardsofkeyforge.com/decks/random?set=cota"
```

```bash
curl -X GET "https://api.cardsofkeyforge.com/decks/random?set=aoa"
```

```bash
curl -X GET "https://api.cardsofkeyforge.com/decks/random?set=wc"
```

```bash
curl -X GET "https://api.cardsofkeyforge.com/decks/random?set=mm"
```

```bash
curl -X GET "https://api.cardsofkeyforge.com/decks/random?set=dt"
```

```bash
curl -X GET "https://api.cardsofkeyforge.com/decks/random?set=woe"
```

--------------------------------

### Random Vault Deck API

Source: https://context7.com/cardsofkeyforge/api/llms.txt

Retrieve a random deck from the KeyForge Master Vault. Optionally filter by expansion set to get a random deck from a specific KeyForge edition. This endpoint queries the official Master Vault API to find a random deck from the entire registered deck pool.

```APIDOC
## GET /decks/random

### Description
Retrieve a random deck from the KeyForge Master Vault. Optionally filter by expansion set to get a random deck from a specific KeyForge edition. This endpoint queries the official Master Vault API to find a random deck from the entire registered deck pool.

### Method
GET

### Endpoint
/decks/random

### Query Parameters
- **set** (string) - Optional - Filter by expansion set (e.g., "cota", "wc") to get a random deck from that specific set.

### Request Example
```bash
curl -X GET "https://api.cardsofkeyforge.com/decks/random?set=aoa"
  -H "Accept-Language: en"
```

### Response
#### Success Response (200)
- **deckid** (string) - The unique identifier of the random deck.
- **name** (string) - The name of the deck.
- **expansion** (string) - The expansion set the deck belongs to.
- **cards** (array) - An array of card objects in the deck.
  - **card_title** (string) - The title of the card.
  - **card_type** (string) - The type of the card.
  - **house** (string) - The house the card belongs to.
  - **set** (string) - The set the card belongs to.

#### Response Example
```json
{
  "deckid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "The Deck of Wonders",
  "expansion": "cota",
  "cards": [
    {
      "card_title": "Ember Imp",
      "card_type": "Creature",
      "house": "Dis",
      "set": "cota"
    },
    {
      "card_title": "Grom",
      "card_type": "Creature",
      "house": "Mars",
      "set": "cota"
    }
  ]
}
```
```

--------------------------------

### Import Deck for Tabletop Simulator

Source: https://context7.com/cardsofkeyforge/api/llms.txt

Convert a Master Vault deck ID into a JSON structure compatible with Tabletop Simulator. Supports custom sleeve colors and language localization.

```bash
# Import a deck for Tabletop Simulator with default red sleeves
curl -X GET "https://api.cardsofkeyforge.com/decks/tts?deckid=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Accept-Language: en"

# Import deck with custom sleeve color
curl -X GET "https://api.cardsofkeyforge.com/decks/tts?deckid=a1b2c3d4-e5f6-7890-abcd-ef1234567890&sleeve=blue" \
  -H "Accept-Language: pt"

# Import deck in Portuguese (default language)
curl -X GET "https://api.cardsofkeyforge.com/decks/tts?deckid=a1b2c3d4-e5f6-7890-abcd-ef1234567890"
```

--------------------------------

### Search and Filter KeyForge Cards

Source: https://context7.com/cardsofkeyforge/api/llms.txt

Use these cURL commands to query the card database with various filters like set, house, type, and rarity. The API returns localized data based on the Accept-Language header.

```bash
# Get all cards from a specific set
curl -X GET "https://api.cardsofkeyforge.com/cards?set=cota" \
  -H "Accept-Language: en"

# Search cards by name with partial matching
curl -X GET "https://api.cardsofkeyforge.com/cards?name=Ember" \
  -H "Accept-Language: en"

# Filter cards by house and type
curl -X GET "https://api.cardsofkeyforge.com/cards?house=Logos&type=creature" \
  -H "Accept-Language: en"

# Get cards with minimum amber value
curl -X GET "https://api.cardsofkeyforge.com/cards?amber=2&set=wc" \
  -H "Accept-Language: en"

# Search for anomaly cards
curl -X GET "https://api.cardsofkeyforge.com/cards?anomaly=true" \
  -H "Accept-Language: en"

# Search for maverick cards
curl -X GET "https://api.cardsofkeyforge.com/cards?maverick=true&set=aoa" \
  -H "Accept-Language: en"

# Filter by rarity and minimum power
curl -X GET "https://api.cardsofkeyforge.com/cards?rarity=Rare&power=5" \
  -H "Accept-Language: en"

# Combined search: Shadows creatures with armor in World's Collide
curl -X GET "https://api.cardsofkeyforge.com/cards?set=wc&house=Shadows&type=creature&armor=1" \
  -H "Accept-Language: pt"
```

--------------------------------

### Implement AWS Lambda Handler

Source: https://context7.com/cardsofkeyforge/api/llms.txt

Standard pattern for API endpoints including CORS headers, error handling, and JSON response formatting.

```go
package main

import (
    "github.com/aws/aws-lambda-go/events"
    "github.com/aws/aws-lambda-go/lambda"
    "keyforge-cards-backend/internal/api"
    "keyforge-cards-backend/internal/service"
    "net/http"
)

func handleRequest(event events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) {
    // Extract query parameters
    parameters := event.QueryStringParameters

    // Call service layer
    result, err := service.SearchCards(event)

    // CORS headers for browser access
    headers := map[string]string{
        "Access-Control-Allow-Origin":      "https://site.cardsofkeyforge.com",
        "Access-Control-Allow-Methods":     "*",
        "Access-Control-Allow-Headers":     "*",
        "Access-Control-Allow-Credentials": "true",
    }

    // Error handling with appropriate status codes
    if err != nil {
        statusCode := api.StatusCodeFromError(err)
        return api.Error(statusCode, headers, "failed to fetch cards", err), err
    }

    // Success response
    return api.Response(http.StatusOK, headers, result), nil
}

func main() {
    lambda.Start(handleRequest)
}

// Response helper creates JSON API Gateway response
func Response(statusCode int, headers map[string]string, body interface{}) events.APIGatewayProxyResponse {
    marshal, _ := json.Marshal(body)
    return events.APIGatewayProxyResponse{
        StatusCode: statusCode,
        Headers:    headers,
        Body:       string(marshal),
    }
}
```

--------------------------------

### Import TTS Deck API

Source: https://context7.com/cardsofkeyforge/api/llms.txt

Convert a Master Vault deck into a Tabletop Simulator (TTS) compatible JSON object. This endpoint fetches deck data from the official KeyForge API and generates a complete TTS custom deck structure with card images, sleeve colors, and proper positioning.

```APIDOC
## GET /decks/tts

### Description
Convert a Master Vault deck into a Tabletop Simulator (TTS) compatible JSON object. This endpoint fetches deck data from the official KeyForge API and generates a complete TTS custom deck structure with card images, sleeve colors, and proper positioning. Non-deck cards (like tokens) are automatically separated into a side deck.

### Method
GET

### Endpoint
/decks/tts

### Query Parameters
- **deckid** (string) - Required - The unique identifier of the Master Vault deck.
- **sleeve** (string) - Optional - The desired sleeve color for the deck (e.g., "red", "blue"). Defaults to "red" if not specified.

### Request Example
```bash
curl -X GET "https://api.cardsofkeyforge.com/decks/tts?deckid=a1b2c3d4-e5f6-7890-abcd-ef1234567890&sleeve=blue"
  -H "Accept-Language: en"
```

### Response
#### Success Response (200)
- **ObjectStates** (array) - An array representing the state of objects in TTS.
  - **Name** (string) - The name of the object state (e.g., "DeckCustom").
  - **ContainedObjects** (array) - Objects contained within this state.
    - **CardID** (integer) - Unique identifier for the card.
    - **Name** (string) - The name of the card.
    - **Nickname** (string) - Nickname for the card in TTS.
    - **Description** (string) - Description of the card.
    - **Transform** (object) - Transformation data (position, rotation, scale).
  - **DeckIDs** (array) - Array of card IDs in the deck.
  - **CustomDeck** (object) - Configuration for custom decks in TTS.
    - **[CardID]** (object) - Configuration for a specific card ID.
      - **FaceURL** (string) - URL for the card's face image.
      - **BackURL** (string) - URL for the card's back image.
      - **NumHeight** (integer) - Height of the card in the deck grid.
      - **NumWidth** (integer) - Width of the card in the deck grid.
      - **BackIsHidden** (boolean) - Whether the card back is hidden.
  - **Transform** (object) - Transformation data for the deck object.

#### Response Example
```json
{
  "ObjectStates": [
    {
      "Name": "DeckCustom",
      "ContainedObjects": [
        {
          "CardID": 100,
          "Name": "Card",
          "Nickname": "Dust Pixie",
          "Description": "Untamed",
          "Transform": {"posX": 0, "posY": 0, "posZ": 0, "rotX": 0, "rotY": 180, "rotZ": 180, "scaleX": 1, "scaleY": 1, "scaleZ": 1}
        }
      ],
      "DeckIDs": [100, 200, 300],
      "CustomDeck": {
        "1": {
          "FaceURL": "https://cards-keyforge.s3.eu-north-1.amazonaws.com/media/en/cota/Untamed-331.png",
          "BackURL": "https://raw.githubusercontent.com/cardsofkeyforge/json/master/decks/assets/redBack.png",
          "NumHeight": 1,
          "NumWidth": 1,
          "BackIsHidden": true
        }
      },
      "Transform": {"posX": 0, "posY": 1, "posZ": 0, "rotX": 0, "rotY": 180, "rotZ": 180, "scaleX": 1.5, "scaleY": 1, "scaleZ": 1.5}
    }
  ]
}
```
```

--------------------------------

### Card Data Model

Source: https://context7.com/cardsofkeyforge/api/llms.txt

Defines the structure of a KeyForge card object.

```APIDOC
## Card Data Model

The Card model represents a complete KeyForge card with all attributes including localized text, house associations, and card images. Cards are stored in DynamoDB with the set code as partition key and card number as range key.

### Card Struct
```go
type Card struct {
    CardTitle  string  `json:"card_title,omitempty"`
    Set        string  `json:"set,omitempty" dynamo:",hash"`
    Amber      int     `json:"amber,omitempty"`
    CardNumber string  `json:"card_number,omitempty" dynamo:",range"`
    CardText   string  `json:"card_text,omitempty"`
    CardType   string  `json:"card_type,omitempty"`
    Expansion  int64   `json:"expansion,omitempty"`
    FlavorText string  `json:"flavor_text,omitempty"`
    Houses     []House `json:"houses,omitempty"`
    IsAnomaly  bool    `json:"is_anomaly,omitempty"`
    IsMaverick bool    `json:"is_maverick,omitempty"`
    Power      string  `json:"power,omitempty"`
    Armor      string  `json:"armor,omitempty"`
    Rarity     string  `json:"rarity,omitempty"`
    Traits     string  `json:"traits,omitempty"`
    Errata     string  `json:"errata,omitempty"`
    Rules      []Rules `json:"rules,omitempty"`
}
```

### House Struct
```go
type House struct {
    Id     string `json:"id,omitempty"`
    House  string `json:"house,omitempty"`
    Normal string `json:"normal,omitempty"`
    Zoom   string `json:"zoom,omitempty"`
}
```

### Rules Struct
```go
type Rules struct {
    Title  string `json:"title,omitempty"`
    Text   string `json:"text,omitempty"`
    Source Source `json:"source,omitempty"`
}
```

### Supported Houses
- Brobnar
- Dis
- Ekwidon
- Logos
- Mars
- Sanctum
- Saurian
- Shadows
- Star Alliance
- Untamed
- Unfathomable
```

--------------------------------

### Database Query Builder

Source: https://context7.com/cardsofkeyforge/api/llms.txt

Utilities for constructing DynamoDB queries and scans.

```APIDOC
## Database Query Builder

The FilterBuilder provides a fluent interface for constructing DynamoDB filter expressions. It supports equality, comparison, contains, and begins_with operations with automatic AND/OR chaining.

### Build Card Filter Example
```go
import "keyforge-cards-backend/internal/database"

// Build a filter for searching cards with multiple conditions
func buildCardFilter() *database.Filter {
    fb := database.FilterBuilder{}

    // Search for cards with name containing "Dragon"
    fb.Contains("CardTitle", "Dragon").And()

    // With amber >= 2
    fb.Ge("Amber", 2).And()

    // Of type "Creature"
    fb.Eq("CardType", "Creature").And()

    // That are not anomalies
    fb.Eq("IsAnomaly", false)

    return fb.Build()
    // Generates: "contains('CardTitle', ?) AND 'Amber' >= ? AND 'CardType' = ? AND 'IsAnomaly' = ?"
    // With values: ["Dragon", 2, "Creature", false]
}
```

### Query Cards Function
```go
// Query cards from a specific set
func queryCards(set string, filter *database.Filter) ([]model.Card, error) {
    cards := make([]model.Card, 0)

    qr := database.QueryRequest{
        TableName:      "cards-en",
        Filter:         filter,
        PartitionKey:   "Set",
        PartitionValue: set,
    }

    err := database.Query(&qr, &cards)
    return cards, err
}
```

### Scan Cards Function
```go
// Scan all cards with a filter (when set is not specified)
func scanCards(filter *database.Filter) ([]model.Card, error) {
    cards := make([]model.Card, 0)

    sr := database.ScanRequest{
        TableName: "cards-en",
        Filter:    filter,
    }

    err := database.Scan(&sr, &cards)
    return cards, err
}
```
```

--------------------------------

### KeyForge Card Data Model

Source: https://context7.com/cardsofkeyforge/api/llms.txt

Defines the structure for a KeyForge card, including its attributes, house affiliations, and associated rules. Cards are stored in DynamoDB.

```go
type Card struct {
    CardTitle  string  `json:"card_title,omitempty"`
    Set        string  `json:"set,omitempty" dynamo:",hash"`
    Amber      int     `json:"amber,omitempty"`
    CardNumber string  `json:"card_number,omitempty" dynamo:",range"`
    CardText   string  `json:"card_text,omitempty"`
    CardType   string  `json:"card_type,omitempty"`
    Expansion  int64   `json:"expansion,omitempty"`
    FlavorText string  `json:"flavor_text,omitempty"`
    Houses     []House `json:"houses,omitempty"`
    IsAnomaly  bool    `json:"is_anomaly,omitempty"`
    IsMaverick bool    `json:"is_maverick,omitempty"`
    Power      string  `json:"power,omitempty"`
    Armor      string  `json:"armor,omitempty"`
    Rarity     string  `json:"rarity,omitempty"`
    Traits     string  `json:"traits,omitempty"`
    Errata     string  `json:"errata,omitempty"`
    Rules      []Rules `json:"rules,omitempty"`
}

// House represents a card's house affiliation with image URLs
type House struct {
    Id     string `json:"id,omitempty"`
    House  string `json:"house,omitempty"`
    Normal string `json:"normal,omitempty"`
    Zoom   string `json:"zoom,omitempty"`
}

// Rules contains official rulings for a card
type Rules struct {
    Title  string `json:"title,omitempty"`
    Text   string `json:"text,omitempty"`
    Source Source `json:"source,omitempty"`
}

// Valid KeyForge houses for filtering
var houses = []string{
    "Brobnar", "Dis", "Ekwidon", "Logos", "Mars",
    "Sanctum", "Saurian", "Shadows", "Star Alliance",
    "Untamed", "Unfathomable",
}
```

--------------------------------

### Generate TTS Deck Structure

Source: https://context7.com/cardsofkeyforge/api/llms.txt

Transforms Master Vault deck data into Tabletop Simulator compatible JSON. Requires a valid deck ID and specifies sleeve color for back image mapping.

```go
import (
    "keyforge-cards-backend/internal/model/tts"
    "keyforge-cards-backend/internal/service"
)

// Generate a TTS deck from a Master Vault deck ID
func generateTTSDeck(deckId string, language string, sleeveColor string) (*tts.ObjectTTS, error) {
    // ImportDeck fetches from Master Vault and generates TTS structure
    ttsDeck, err := service.ImportDeck(deckId, language, sleeveColor)
    if err != nil {
        return nil, err
    }
    return ttsDeck, nil
}

// TTS Object structure for Tabletop Simulator import
type ObjectTTS struct {
    ObjectStates []DeckTTS  // Main deck and optional side deck
}

type DeckTTS struct {
    Name             string              // "DeckCustom"
    ContainedObjects []CardTTS           // Individual card objects
    DeckIDs          []int               // Card IDs in deck order
    CustomDeck       map[string]CardDataTTS // Card face/back images
    Transform        TransformTTS        // Position and rotation
}

type CardTTS struct {
    CardID      int
    Name        string     // "Card"
    Nickname    string     // Card title
    Description string     // House name and special attributes
    Transform   TransformTTS
}

// Sleeve color options map to back images
// Available: red, blue, green, etc.
// URL pattern: https://raw.githubusercontent.com/cardsofkeyforge/json/master/decks/assets/{color}Back.png
```

--------------------------------

### Scan All Cards with Filter

Source: https://context7.com/cardsofkeyforge/api/llms.txt

Retrieves all cards from the 'cards-en' table in DynamoDB that match a given filter using a ScanRequest. Useful when the set is not specified.

```go
import "keyforge-cards-backend/internal/database"

// Scan all cards with a filter (when set is not specified)
func scanCards(filter *database.Filter) ([]model.Card, error) {
    cards := make([]model.Card, 0)

    sr := database.ScanRequest{
        TableName: "cards-en",
        Filter:    filter,
    }

    err := database.Scan(&sr, &cards)
    return cards, err
}
```

--------------------------------

### Query Cards by Set

Source: https://context7.com/cardsofkeyforge/api/llms.txt

Retrieves cards from a specific set in DynamoDB using a QueryRequest. Requires a set code and an optional filter.

```go
import "keyforge-cards-backend/internal/database"

// Query cards from a specific set
func queryCards(set string, filter *database.Filter) ([]model.Card, error) {
    cards := make([]model.Card, 0)

    qr := database.QueryRequest{
        TableName:      "cards-en",
        Filter:         filter,
        PartitionKey:   "Set",
        PartitionValue: set,
    }

    err := database.Query(&qr, &cards)
    return cards, err
}
```

--------------------------------

### Build DynamoDB Filter Expression

Source: https://context7.com/cardsofkeyforge/api/llms.txt

Constructs a DynamoDB filter expression using a fluent interface for various query conditions like contains, equality, and comparisons. Supports automatic AND/OR chaining.

```go
import "keyforge-cards-backend/internal/database"

// Build a filter for searching cards with multiple conditions
func buildCardFilter() *database.Filter {
    fb := database.FilterBuilder{}

    // Search for cards with name containing "Dragon"
    fb.Contains("CardTitle", "Dragon").And()

    // With amber >= 2
    fb.Ge("Amber", 2).And()

    // Of type "Creature"
    fb.Eq("CardType", "Creature").And()

    // That are not anomalies
    fb.Eq("IsAnomaly", false)

    return fb.Build()
    // Generates: "contains('CardTitle', ?) AND 'Amber' >= ? AND 'CardType' = ? AND 'IsAnomaly' = ?"
    // With values: ["Dragon", 2, "Creature", false]
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.