### Get Entry Response Example (JSONC)

Source: https://github.com/cavv-dev/crocdb-api/blob/main/API_DOCUMENTATION.md

An example response from the `/entry` endpoint, showing the details of a single ROM entry including its slug, title, platform, regions, and associated download links. This helps in understanding the structure for individual entries.

```jsonc
{
  "info": {},
  "data": {
    "entry": {
      "slug": "croc-legend-of-the-gobbos-ps1-us",
      "rom_id": "SLUS-00530",
      "title": "Croc - Legend of the Gobbos",
      "platform": "ps1",
      "boxart_url": "https://thumbnails.libretro.com/Sony%20-%20PlayStation/Named_Boxarts/Croc%20-%20Legend%20of%20the%20Gobbos%20%28USA%29.png",
      "regions": [
        "us"
      ],
      "links": [
        {
          "name": "Croc - Legend of the Gobbos (USA)",
          "type": "Game",
          "format": "bin/cue",
          "url": "https://myrient.erista.me/files/Redump/Sony%20-%20PlayStation/Croc%20-%20Legend%20of%20the%20Gobbos%20%28USA%29.zip",
          "filename": "Croc - Legend of the Gobbos (USA).zip",
          "host": "Myrient",
          "size": 388392550,
          "size_str": "370.4M",
          "source_url": "https://myrient.erista.me/files/Redump/Sony%20-%20PlayStation/"
        }
        // ...
      ]
    }
  }
}
```

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

### Get Available Platforms API Response

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

Example JSON response for the 'Get Available Platforms' API request, illustrating the structure of platform data including brand and name for each platform.

```json
{
  "info": {},
  "data": {
    "platforms": {
      "nes": {
        "brand": "Nintendo",
        "name": "Nintendo Entertainment System"
      },
      "snes": {
        "brand": "Nintendo",
        "name": "Super Nintendo Entertainment System"
      },
      "n64": {
        "brand": "Nintendo",
        "name": "Nintendo 64"
      },
      "ps1": {
        "brand": "Sony",
        "name": "PlayStation"
      },
      "ps2": {
        "brand": "Sony",
        "name": "PlayStation 2"
      },
      "genesis": {
        "brand": "Sega",
        "name": "Genesis"
      }
    }
  }
}
```

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

### Available Platforms Response Example (JSONC)

Source: https://github.com/cavv-dev/crocdb-api/blob/main/API_DOCUMENTATION.md

Example response from the `/platforms` endpoint, listing all supported platforms in the database with their associated brand and full name. Useful for populating platform selection UI elements.

```jsonc
{
  "info": {},
  "data": {
    "platforms": {
      "nes": {
        "brand": "Nintendo",
        "name": "Nintendo Entertainment System"
      },
      "fds": {
        "brand": "Nintendo",
        "name": "Famicom Disk System"
      },
      "snes": {
        "brand": "Nintendo",
        "name": "Super Nintendo Entertainment System"
      }
      // ...
    }
  }
}
```

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

### Available Regions Response Example (JSON)

Source: https://github.com/cavv-dev/crocdb-api/blob/main/API_DOCUMENTATION.md

Example response from the `/regions` endpoint, providing a mapping of region codes to their full names. This is helpful for understanding and displaying region information to users.

```json
{
  "info": {},
  "data": {
    "regions": {
      "eu": "Europe",
      "us": "USA",
      "jp": "Japan",
      "other": "Other"
    }
  }
}
```

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

### Search Entries Response Example (JSONC)

Source: https://github.com/cavv-dev/crocdb-api/blob/main/API_DOCUMENTATION.md

Example of a successful response from the `/search` endpoint, detailing ROM entries with their metadata, regions, and download links. This structure helps in parsing search results.

```jsonc
{
  "info": {},
  "data": {
    "results": [
      {
        "slug": "mario-is-missing-snes-eu",
        "rom_id": null,
        "title": "Mario Is Missing!",
        "platform": "snes",
        "boxart_url": "https://thumbnails.libretro.com/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System/Named_Boxarts/Mario%20Is%20Missing%21%20%28Europe%29.png",
        "regions": [
          "eu"
        ],
        "links": [
          {
            "name": "Mario Is Missing! (Europe)",
            "type": "Game",
            "format": "sfc",
            "url": "https://myrient.erista.me/files/No-Intro/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System/Mario%20Is%20Missing%21%20%28Europe%29.zip",
            "filename": "Mario Is Missing! (Europe).zip",
            "host": "Myrient",
            "size": 925491,
            "size_str": "903.8K",
            "source_url": "https://myrient.erista.me/files/No-Intro/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System/"
          }
          // ...
        ]
      }
      // ...
    ],
    "current_results": 50,
    "total_results": 75,
    "current_page": 1,
    "total_pages": 2
  }
}
```

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

### GET /info | POST /info

Source: https://github.com/cavv-dev/crocdb-api/blob/main/API_DOCUMENTATION.md

Retrieves general information about the database, such as the total number of entries. Supports both GET and POST methods.

```APIDOC
## GET /info | POST /info

### Description
Returns general information about the database, including the total number of entries.

### Method
GET, POST

### Endpoint
/info

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None required

### Request Example
```json
{} 
```

### Response
#### Success Response (200)
- **info** (object) - Contains general information or error details.
- **data** (object) - Contains database-specific data, such as `total_entries`.

#### Response Example
```json
{
  "info": {},
  "data": {
    "total_entries": 152241
  }
}
```

### Error Handling
If an error occurs, the API will return an appropriate HTTP status code along with an error message in the `info` object.

#### Error Response Example
```json
{
  "info": {
    "error": "An unexpected error occurred"
  },
  "data": {}
}
```
```

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

### Get Specific ROM Entry by Slug (API Request)

Source: https://github.com/cavv-dev/crocdb-api/blob/main/API_DOCUMENTATION.md

This example shows the JSON request body required to retrieve a specific ROM entry using its unique slug identifier. This is essential for clients targeting the `/entry` endpoint.

```json
{
  "slug": "croc-legend-of-the-gobbos-ps1-us"
}
```

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

### Get Available Platforms

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

Retrieves a comprehensive list of all gaming platforms supported by the database, including their brand and full names.

```APIDOC
## GET /platforms

### Description
Retrieves the complete list of gaming platforms available in the database with their brand and full names.

### Method
GET

### Endpoint
/platforms

### Parameters
#### Query Parameters
None

### Request Example
```bash
curl -X GET https://api.crocdb.net/platforms
```

### Response
#### Success Response (200)
- **platforms** (object) - An object containing platform IDs as keys and platform details (brand, name) as values.

#### Response Example
```json
{
  "info": {},
  "data": {
    "platforms": {
      "nes": {
        "brand": "Nintendo",
        "name": "Nintendo Entertainment System"
      },
      "snes": {
        "brand": "Nintendo",
        "name": "Super Nintendo Entertainment System"
      },
      "n64": {
        "brand": "Nintendo",
        "name": "Nintendo 64"
      },
      "ps1": {
        "brand": "Sony",
        "name": "PlayStation"
      },
      "ps2": {
        "brand": "Sony",
        "name": "PlayStation 2"
      },
      "genesis": {
        "brand": "Sega",
        "name": "Genesis"
      }
    }
  }
}
```
```

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

### Python Get Platforms, Regions, and Info

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

Shows how to use Python functions `api.get_platforms()`, `api.get_regions()`, and `api.get_info()` to retrieve metadata about available platforms, regions, and the total number of entries in the database. It then prints this information to the console.

```python
import api

# Get all available platforms
platforms_response = api.get_platforms()
platforms = platforms_response['data']['platforms']

print("Available platforms:")
for platform_id, platform_info in platforms.items():
    print(f"  {platform_id}: {platform_info['brand']} - {platform_info['name']}")

# Get all available regions
regions_response = api.get_regions()
regions = regions_response['data']['regions']

print("\nAvailable regions:")
for region_id, region_name in regions.items():
    print(f"  {region_id}: {region_name}")

# Get database statistics
info_response = api.get_info()
print(f"\nTotal entries in database: {info_response['data']['total_entries']}")
```

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

### Get Database Information

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

Retrieves general statistics and metadata about the ROM database, including the total number of entries.

```APIDOC
## GET /info

### Description
Retrieves general statistics and metadata about the current state of the ROM database.

### Method
GET

### Endpoint
/info

### Parameters
#### Query Parameters
None

### Request Example
```bash
curl -X GET https://api.crocdb.net/info
```

### Response
#### Success Response (200)
- **total_entries** (integer) - The total number of ROM entries currently in the database.

#### Response Example
```json
{
  "info": {},
  "data": {
    "total_entries": 152241
  }
}
```
```

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

### Get Database Information (JSON)

Source: https://github.com/cavv-dev/crocdb-api/blob/main/API_DOCUMENTATION.md

Retrieves general information about the database. This endpoint returns the total number of entries and can be accessed via POST or GET requests. No request body is required.

```json
{
  "info": {},
  "data": {
    "total_entries": 152241
  }
}
```

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

### Get Available Platforms API Request

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

Retrieves a list of all gaming platforms available in the database. This endpoint returns a JSON object containing platform IDs, their associated brands, and full names.

```bash
curl -X GET https://api.crocdb.net/platforms
```

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

### Search ROM Entries with Filters (API Request)

Source: https://github.com/cavv-dev/crocdb-api/blob/main/API_DOCUMENTATION.md

This example demonstrates how to construct a JSON request body to search for ROM entries using various filters like search keywords, platforms, regions, and pagination. It's useful for clients interacting with the `/search` endpoint.

```json
{
  "search_key": "mario",
  "platforms": ["snes", "n64"],
  "regions": ["us", "eu"],
  "max_results": 50,
  "page": 1
}
```

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

### Get Entry API

Source: https://github.com/cavv-dev/crocdb-api/blob/main/API_DOCUMENTATION.md

Retrieves a specific ROM entry by its unique slug identifier.

```APIDOC
## POST /entry

### Description
Retrieves a specific entry by its slug identifier.

### Method
POST

### Endpoint
/entry

#### Query Parameters
None

#### Request Body
- **slug** (string) - Yes - The unique slug identifier for the entry

### Request Example
```json
{
  "slug": "croc-legend-of-the-gobbos-ps1-us"
}
```

### Response
#### Success Response (200)
- **info** (object) - Information about the request or error messages
- **data** (object) - The actual data returned by the endpoint
  - **entry** (object) - The ROM entry object

#### Response Example
```json
{
  "info": {},
  "data": {
    "entry": {
      "slug": "croc-legend-of-the-gobbos-ps1-us",
      "rom_id": "SLUS-00530",
      "title": "Croc - Legend of the Gobbos",
      "platform": "ps1",
      "boxart_url": "https://thumbnails.libretro.com/Sony%20-%20PlayStation/Named_Boxarts/Croc%20-%20Legend%20of%20the%20Gobbos%20%28USA%29.png",
      "regions": [
        "us"
      ],
      "links": [
        {
          "name": "Croc - Legend of the Gobbos (USA)",
          "type": "Game",
          "format": "bin/cue",
          "url": "https://myrient.erista.me/files/Redump/Sony%20-%20PlayStation/Croc%20-%20Legend%20of%20the%20Gobbos%20%28USA%29.zip",
          "filename": "Croc - Legend of the Gobbos (USA).zip",
          "host": "Myrient",
          "size": 388392550,
          "size_str": "370.4M",
          "source_url": "https://myrient.erista.me/files/Redump/Sony%20-%20PlayStation/"
        }
      ]
    }
  }
}
```
```

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

### Build Standardized API Responses in Python

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

This Python code demonstrates how to build standardized success and error responses using the `build_response` function. It also shows an example of using the `@handle_exception` decorator to automatically format exceptions into API error responses. Dependencies include the `api` module for `build_response` and `handle_exception`.

```python
from api import build_response, handle_exception

# Build success response
success = build_response(
    info={},
    data={'entry': {'title': 'Super Mario 64', 'platform': 'n64'}}
)
print(success)
# Output: {'info': {}, 'data': {'entry': {'title': 'Super Mario 64', 'platform': 'n64'}}}

# Build error response
error = build_response(
    info={'error': 'Entry not found'},
    data={}
)
print(error)
# Output: {'info': {'error': 'Entry not found'}, 'data': {}}

# Example with error handling decorator
@handle_exception
def risky_operation():
    raise ValueError("Invalid input")

result = risky_operation()
print(result)
# Output: {'info': {'error': 'Invalid input provided'}, 'data': {}}
```

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

### Get Random ROM Entry (API Request)

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

This snippet demonstrates how to request a single, randomly selected ROM entry from the database using a GET request to the /entry/random endpoint. This is useful for features that encourage discovery of new ROMs.

```bash
curl -X GET https://api.crocdb.net/entry/random
```

```json
{
  "info": {},
  "data": {
    "entry": {
      "slug": "zelda-ocarina-of-time-n64-us",
      "rom_id": "NUS-NZLE-USA",
      "title": "The Legend of Zelda: Ocarina of Time",
      "platform": "n64",
      "boxart_url": "https://thumbnails.libretro.com/Nintendo%20-%20Nintendo%2064/Named_Boxarts/Legend%20of%20Zelda%2C%20The%20-%20Ocarina%20of%20Time%20%28USA%29.png",
      "regions": ["us"],
      "links": [
        {
          "name": "The Legend of Zelda: Ocarina of Time (USA)",
          "type": "Game",
          "format": "z64",
          "url": "https://myrient.erista.me/files/No-Intro/Nintendo%20-%20Nintendo%2064/Legend%20of%20Zelda%2C%20The%20-%20Ocarina%20of%20Time%20%28USA%29.zip",
          "filename": "Legend of Zelda, The - Ocarina of Time (USA).zip",
          "host": "Myrient",
          "size": 33554432,
          "size_str": "32.0M",
          "source_url": "https://myrient.erista.me/files/No-Intro/Nintendo%20-%20Nintendo%2064/"
        }
      ]
    }
  }
}
```

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

### Get Database Information API Request

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

Retrieves general statistics and metadata about the ROM database. This endpoint returns a JSON object containing information like the total number of entries.

```bash
curl -X GET https://api.crocdb.net/info
```

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

### Python Get Entry by Slug or Random

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

Illustrates how to use the `api.get_entry` function in Python to retrieve a specific ROM entry by its slug or to fetch a random entry. It prints details of the retrieved entry, including title, platform, ROM ID, boxart, and download links.

```python
import api

# Get specific entry by slug
response = api.get_entry(slug="croc-legend-of-the-gobbos-ps1-us", random=False)

if 'entry' in response['data']:
    entry = response['data']['entry']
    print(f"Title: {entry['title']}")
    print(f"Platform: {entry['platform']}")
    print(f"ROM ID: {entry['rom_id']}")
    print(f"Boxart: {entry['boxart_url']}")
    print(f"Available regions: {', '.join(entry['regions'])}")

    print("\nDownload links:")
    for link in entry['links']:
        print(f"  {link['name']} ({link['format']}) - {link['size_str']}")
        print(f"  URL: {link['url']}")
        print(f"  Host: {link['host']}")

# Get random entry
random_response = api.get_entry(slug=None, random=True)
if 'entry' in random_response['data']:
    print(f"\nRandom game: {random_response['data']['entry']['title']}")
```

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

### GET /entry/random

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

Retrieve a randomly selected ROM entry from the database, useful for discovery features.

```APIDOC
## GET /entry/random

### Description
Retrieve a randomly selected ROM entry from the database, useful for discovery features.

### Method
GET

### Endpoint
/entry/random

### Response
#### Success Response (200)
- **info** (object) - Contains general information about the request.
- **data** (object)
  - **entry** (object) - A randomly selected ROM entry object.

#### Response Example
```json
{
  "info": {},
  "data": {
    "entry": {
      "slug": "zelda-ocarina-of-time-n64-us",
      "rom_id": "NUS-NZLE-USA",
      "title": "The Legend of Zelda: Ocarina of Time",
      "platform": "n64",
      "boxart_url": "https://thumbnails.libretro.com/Nintendo%20-%20Nintendo%2064/Named_Boxarts/Legend%20of%20Zelda%2C%20The%20-%20Ocarina%20of%20Time%20%28USA%29.png",
      "regions": ["us"],
      "links": [
        {
          "name": "The Legend of Zelda: Ocarina of Time (USA)",
          "type": "Game",
          "format": "z64",
          "url": "https://myrient.erista.me/files/No-Intro/Nintendo%20-%20Nintendo%2064/Legend%20of%20Zelda%2C%20The%20-%20Ocarina%20of%20Time%20%28USA%29.zip",
          "filename": "Legend of Zelda, The - Ocarina of Time (USA).zip",
          "host": "Myrient",
          "size": 33554432,
          "size_str": "32.0M",
          "source_url": "https://myrient.erista.me/files/No-Intro/Nintendo%20-%20Nintendo%2064/"
        }
      ]
    }
  }
}
```
```

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

### Get Available Regions

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

Fetches a list of geographical regions available for filtering ROM entries based on their release location.

```APIDOC
## GET /regions

### Description
Retrieves the list of regions available in the database for filtering ROM entries by geographic release.

### Method
GET

### Endpoint
/regions

### Parameters
#### Query Parameters
None

### Request Example
```bash
curl -X GET https://api.crocdb.net/regions
```

### Response
#### Success Response (200)
- **regions** (object) - An object mapping region codes to their full names.

#### Response Example
```json
{
  "info": {},
  "data": {
    "regions": {
      "eu": "Europe",
      "us": "USA",
      "jp": "Japan",
      "other": "Other"
    }
  }
}
```
```

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

### Get Entry by Slug or Random

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

Retrieves a specific ROM entry using its unique slug identifier or fetches a random entry from the database.

```APIDOC
## GET /entry

### Description
Retrieve a specific ROM entry by its slug identifier or fetch a random entry for discovery.

### Method
GET

### Endpoint
/entry

### Parameters
#### Query Parameters
- **slug** (string) - Optional - The unique slug identifier of the ROM entry to retrieve. If not provided, a random entry is returned.
- **random** (boolean) - Optional - If set to true, a random entry is returned, ignoring the 'slug' parameter.

### Request Example
Get specific entry by slug:
```bash
curl -X GET https://api.crocdb.net/entry?slug=croc-legend-of-the-gobbos-ps1-us
```

Get a random entry:
```bash
curl -X GET https://api.crocdb.net/entry?random=true
```

### Response
#### Success Response (200)
- **entry** (object) - Details of the ROM entry.
  - **title** (string) - The title of the ROM.
  - **platform** (string) - The platform ID.
  - **rom_id** (string) - The unique ROM identifier.
  - **boxart_url** (string) - URL to the boxart image.
  - **regions** (array of strings) - Available regions for the ROM.
  - **links** (array) - Download links.
    - **name** (string) - Name of the download link.
    - **format** (string) - File format of the download.
    - **size_str** (string) - Human-readable file size.
    - **url** (string) - The direct download URL.
    - **host** (string) - The host of the download link.

#### Response Example (Specific Entry)
```json
{
  "info": {},
  "data": {
    "entry": {
      "title": "Croc: Legend of the Gobbos",
      "platform": "ps1",
      "rom_id": "croc-ps1-us",
      "boxart_url": "https://images.crocdb.net/boxart/ps1/croc.jpg",
      "regions": ["us"],
      "links": [
        {
          "name": "Download (USA)",
          "format": "bin",
          "size_str": "500MB",
          "url": "http://example.com/croc.bin",
          "host": "example.com"
        }
      ]
    }
  }
}
```

#### Response Example (Random Entry)
```json
{
  "info": {},
  "data": {
    "entry": {
      "title": "Ape Escape",
      "platform": "ps1",
      "rom_id": "apeescape-ps1-jp",
      "boxart_url": "https://images.crocdb.net/boxart/ps1/apeescape.jpg",
      "regions": ["jp"],
      "links": [
        {
          "name": "Download (Japan)",
          "format": "img",
          "size_str": "400MB",
          "url": "http://example.com/apeescape.img",
          "host": "example.com"
        }
      ]
    }
  }
}
```
```

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

### Get Available Regions API Request

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

Fetches a list of all available regions used for filtering ROM entries. This endpoint returns a JSON object mapping region codes to their full names.

```bash
curl -X GET https://api.crocdb.net/regions
```

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

### Get Specific ROM Entry by Slug (API Request)

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

This snippet shows how to retrieve detailed information for a single ROM entry by providing its unique slug identifier in a POST request to the /entry endpoint. The response contains the complete data for the requested entry.

```bash
curl -X POST https://api.crocdb.net/entry \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "croc-legend-of-the-gobbos-ps1-us"
  }'
```

```json
{
  "info": {},
  "data": {
    "entry": {
      "slug": "croc-legend-of-the-gobbos-ps1-us",
      "rom_id": "SLUS-00530",
      "title": "Croc - Legend of the Gobbos",
      "platform": "ps1",
      "boxart_url": "https://thumbnails.libretro.com/Sony%20-%20PlayStation/Named_Boxarts/Croc%20-%20Legend%20of%20the%20Gobbos%20%28USA%29.png",
      "regions": ["us"],
      "links": [
        {
          "name": "Croc - Legend of the Gobbos (USA)",
          "type": "Game",
          "format": "bin/cue",
          "url": "https://myrient.erista.me/files/Redump/Sony%20-%20PlayStation/Croc%20-%20Legend%20of%20the%20Gobbos%20%28USA%29.zip",
          "filename": "Croc - Legend of the Gobbos (USA).zip",
          "host": "Myrient",
          "size": 388392550,
          "size_str": "370.4M",
          "source_url": "https://myrient.erista.me/files/Redump/Sony%20-%20PlayStation/"
        }
      ]
    }
  }
}
```

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

### Available Platforms API

Source: https://github.com/cavv-dev/crocdb-api/blob/main/API_DOCUMENTATION.md

Retrieves a list of all available platforms in the database.

```APIDOC
## POST /platforms or GET /platforms

### Description
Returns a list of all available platforms in the database.

### Method
POST, GET

### Endpoint
/platforms

#### Query Parameters
None

#### Request Body
None required

### Response
#### Success Response (200)
- **info** (object) - Information about the request or error messages
- **data** (object) - The actual data returned by the endpoint
  - **platforms** (object) - An object where keys are platform IDs and values are platform details

#### Response Example
```json
{
  "info": {},
  "data": {
    "platforms": {
      "nes": {
        "brand": "Nintendo",
        "name": "Nintendo Entertainment System"
      },
      "fds": {
        "brand": "Nintendo",
        "name": "Famicom Disk System"
      },
      "snes": {
        "brand": "Nintendo",
        "name": "Super Nintendo Entertainment System"
      }
    }
  }
}
```
```

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

### POST /search

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

Search for ROM entries using various filters including search terms, platforms, regions, ROM IDs, with pagination support.

```APIDOC
## POST /search

### Description
Search for ROM entries using various filters including search terms, platforms, regions, ROM IDs, with pagination support.

### Method
POST

### Endpoint
/search

### Parameters
#### Request Body
- **search_key** (string) - Optional - The search term to look for in ROM titles.
- **platforms** (array of strings) - Optional - A list of platform slugs to filter by.
- **regions** (array of strings) - Optional - A list of region codes to filter by.
- **max_results** (integer) - Optional - The maximum number of results to return per page.
- **page** (integer) - Optional - The page number for pagination.

### Request Example
```json
{
  "search_key": "mario",
  "platforms": ["snes", "n64"],
  "regions": ["us", "eu"],
  "max_results": 50,
  "page": 1
}
```

### Response
#### Success Response (200)
- **info** (object) - Contains general information about the request.
- **data** (object)
  - **results** (array of objects) - A list of ROM entry objects matching the search criteria.
  - **current_results** (integer) - The number of results on the current page.
  - **total_results** (integer) - The total number of results available.
  - **current_page** (integer) - The current page number.
  - **total_pages** (integer) - The total number of pages available.

#### Response Example
```json
{
  "info": {},
  "data": {
    "results": [
      {
        "slug": "super-mario-64-n64-us",
        "rom_id": "NUS-NSME-USA",
        "title": "Super Mario 64",
        "platform": "n64",
        "boxart_url": "https://thumbnails.libretro.com/Nintendo%20-%20Nintendo%2064/Named_Boxarts/Super%20Mario%2064%20%28USA%29.png",
        "regions": ["us"],
        "links": [
          {
            "name": "Super Mario 64 (USA)",
            "type": "Game",
            "format": "z64",
            "url": "https://myrient.erista.me/files/No-Intro/Nintendo%20-%20Nintendo%2064/Super%20Mario%2064%20%28USA%29.zip",
            "filename": "Super Mario 64 (USA).zip",
            "host": "Myrient",
            "size": 8388608,
            "size_str": "8.0M",
            "source_url": "https://myrient.erista.me/files/No-Intro/Nintendo%20-%20Nintendo%2064/"
          }
        ]
      }
    ],
    "current_results": 1,
    "total_results": 45,
    "current_page": 1,
    "total_pages": 1
  }
}
```
```

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

### POST /entry

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

Retrieve detailed information about a specific ROM entry using its unique slug identifier.

```APIDOC
## POST /entry

### Description
Retrieve detailed information about a specific ROM entry using its unique slug identifier.

### Method
POST

### Endpoint
/entry

### Parameters
#### Request Body
- **slug** (string) - Required - The unique slug identifier for the ROM entry.

### Request Example
```json
{
  "slug": "croc-legend-of-the-gobbos-ps1-us"
}
```

### Response
#### Success Response (200)
- **info** (object) - Contains general information about the request.
- **data** (object)
  - **entry** (object) - The ROM entry object matching the provided slug.

#### Response Example
```json
{
  "info": {},
  "data": {
    "entry": {
      "slug": "croc-legend-of-the-gobbos-ps1-us",
      "rom_id": "SLUS-00530",
      "title": "Croc - Legend of the Gobbos",
      "platform": "ps1",
      "boxart_url": "https://thumbnails.libretro.com/Sony%20-%20PlayStation/Named_Boxarts/Croc%20-%20Legend%20of%20the%20Gobbos%20%28USA%29.png",
      "regions": ["us"],
      "links": [
        {
          "name": "Croc - Legend of the Gobbos (USA)",
          "type": "Game",
          "format": "bin/cue",
          "url": "https://myrient.erista.me/files/Redump/Sony%20-%20PlayStation/Croc%20-%20Legend%20of%20the%20Gobbos%20%28USA%29.zip",
          "filename": "Croc - Legend of the Gobbos (USA).zip",
          "host": "Myrient",
          "size": 388392550,
          "size_str": "370.4M",
          "source_url": "https://myrient.erista.me/files/Redump/Sony%20-%20PlayStation/"
        }
      ]
    }
  }
}
```
```

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

### Python Search Key Processing and Normalization

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

Demonstrates the usage of Python functions `get_valid_search_key`, `create_db_search_key`, and `prepare_search_key` from the `api` module for cleaning, normalizing, and formatting search strings to match the database's requirements for accurate querying.

```python
from api import get_valid_search_key, create_db_search_key, prepare_search_key

# Clean and normalize user input
user_input = "  Super  Mario™  Bros.  &  Friends  "
valid_key = get_valid_search_key(user_input)
print(f"Valid search key: {valid_key}")
# Output: "Super Mario Bros. and Friends"

# Create database-compatible search key
db_key = create_db_search_key(user_input)
print(f"Database search key: {db_key}")
# Output: "supermariobrosfriends"

# Prepare for SQL MATCH operator
sql_search = prepare_search_key("super mario")
print(f"SQL MATCH format: {sql_search}")
# Output: "super" "mario"
```

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

### Search Entries API

Source: https://github.com/cavv-dev/crocdb-api/blob/main/API_DOCUMENTATION.md

Searches for ROM entries using various filters such as search key, platforms, regions, ROM ID, and pagination parameters.

```APIDOC
## POST /search

### Description
Searches for ROM entries using various filters.

### Method
POST

### Endpoint
/search

#### Query Parameters
None

#### Request Body
- **search_key** (string) - Optional - Search term to find matching entries
- **platforms** (array of strings) - Optional - List of platform IDs to filter by
- **regions** (array of strings) - Optional - List of region IDs to filter by
- **rom_id** (string) - Optional - Filter by specific ROM ID
- **max_results** (integer) - Optional - Maximum number of results per page (default: 100, max: 100)
- **page** (integer) - Optional - Page number for pagination (default: 1)

### Request Example
```json
{
  "search_key": "mario",
  "platforms": ["snes", "n64"],
  "regions": ["us", "eu"],
  "max_results": 50,
  "page": 1
}
```

### Response
#### Success Response (200)
- **info** (object) - Information about the request or error messages
- **data** (object) - The actual data returned by the endpoint
  - **results** (array) - List of ROM entry objects
  - **current_results** (integer) - Number of results in the current page
  - **total_results** (integer) - Total number of matching results
  - **current_page** (integer) - The current page number
  - **total_pages** (integer) - The total number of pages

#### Response Example
```json
{
  "info": {},
  "data": {
    "results": [
      {
        "slug": "mario-is-missing-snes-eu",
        "rom_id": null,
        "title": "Mario Is Missing!",
        "platform": "snes",
        "boxart_url": "https://thumbnails.libretro.com/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System/Named_Boxarts/Mario%20Is%20Missing%21%20%28Europe%29.png",
        "regions": [
          "eu"
        ],
        "links": [
          {
            "name": "Mario Is Missing! (Europe)",
            "type": "Game",
            "format": "sfc",
            "url": "https://myrient.erista.me/files/No-Intro/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System/Mario%20Is%20Missing%21%20%28Europe%29.zip",
            "filename": "Mario Is Missing! (Europe).zip",
            "host": "Myrient",
            "size": 925491,
            "size_str": "903.8K",
            "source_url": "https://myrient.erista.me/files/No-Intro/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System/"
          }
        ]
      }
    ],
    "current_results": 50,
    "total_results": 75,
    "current_page": 1,
    "total_pages": 2
  }
}
```
```

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

### Search ROM Entries with Filters (API Request)

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

This snippet demonstrates how to send a POST request to the /search endpoint to find ROM entries. It includes parameters for search terms, platforms, regions, and pagination. The API returns a JSON object with search results, current metadata, and total counts.

```bash
curl -X POST https://api.crocdb.net/search \
  -H "Content-Type: application/json" \
  -d '{
    "search_key": "mario",
    "platforms": ["snes", "n64"],
    "regions": ["us", "eu"],
    "max_results": 50,
    "page": 1
  }'
```

```json
{
  "info": {},
  "data": {
    "results": [
      {
        "slug": "super-mario-64-n64-us",
        "rom_id": "NUS-NSME-USA",
        "title": "Super Mario 64",
        "platform": "n64",
        "boxart_url": "https://thumbnails.libretro.com/Nintendo%20-%20Nintendo%2064/Named_Boxarts/Super%20Mario%2064%20%28USA%29.png",
        "regions": ["us"],
        "links": [
          {
            "name": "Super Mario 64 (USA)",
            "type": "Game",
            "format": "z64",
            "url": "https://myrient.erista.me/files/No-Intro/Nintendo%20-%20Nintendo%2064/Super%20Mario%2064%20%28USA%29.zip",
            "filename": "Super Mario 64 (USA).zip",
            "host": "Myrient",
            "size": 8388608,
            "size_str": "8.0M",
            "source_url": "https://myrient.erista.me/files/No-Intro/Nintendo%20-%20Nintendo%2064/"
          }
        ]
      }
    ],
    "current_results": 1,
    "total_results": 45,
    "current_page": 1,
    "total_pages": 1
  }
}
```

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

### Python Search Function with Filters

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

Demonstrates how to use the `api.get_search` function in Python to perform complex searches with multiple filters including text search, platform, region, and ROM ID, with pagination support. It iterates through the results and prints details for each entry.

```python
import api

# Search for Mario games on SNES and N64 in US region
response = api.get_search(
    search_key="super mario",
    platforms=["snes", "n64"],
    regions=["us"],
    max_results=25,
    page=1
)

if response['data'].get('results'):
    for entry in response['data']['results']:
        print(f"Title: {entry['title']}")
        print(f"Platform: {entry['platform']}")
        print(f"ROM ID: {entry['rom_id']}")
        print(f"Regions: {', '.join(entry['regions'])}")
        print(f"Download links: {len(entry['links'])}")
        print("---")

    print(f"\nPage {response['data']['current_page']} of {response['data']['total_pages']}")
    print(f"Showing {response['data']['current_results']} of {response['data']['total_results']} results")
```

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

### Crocdb API Response Structure

Source: https://github.com/cavv-dev/crocdb-api/blob/main/API_DOCUMENTATION.md

Illustrates the standard JSON structure returned by all Crocdb API endpoints. It includes an 'info' object for metadata or errors and a 'data' object containing the actual requested information.

```jsonc
{
  "info": {
    // Information about the request or error messages
  },
  "data": {
    // The actual data returned by the endpoint
  }
}
```

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

### Available Regions API

Source: https://github.com/cavv-dev/crocdb-api/blob/main/API_DOCUMENTATION.md

Retrieves a list of all available regions in the database.

```APIDOC
## POST /regions or GET /regions

### Description
Returns a list of all available regions in the database.

### Method
POST, GET

### Endpoint
/regions

#### Query Parameters
None

#### Request Body
None required

### Response
#### Success Response (200)
- **info** (object) - Information about the request or error messages
- **data** (object) - The actual data returned by the endpoint
  - **regions** (object) - An object where keys are region codes and values are region names

#### Response Example
```json
{
  "info": {},
  "data": {
    "regions": {
      "eu": "Europe",
      "us": "USA",
      "jp": "Japan",
      "other": "Other"
    }
  }
}
```
```

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

### Random Entry API

Source: https://github.com/cavv-dev/crocdb-api/blob/main/API_DOCUMENTATION.md

Returns a randomly selected ROM entry from the database.

```APIDOC
## POST /entry/random or GET /entry/random

### Description
Returns a randomly selected entry from the database.

### Method
POST, GET

### Endpoint
/entry/random

#### Query Parameters
None

#### Request Body
None required

### Response
#### Success Response (200)
- **info** (object) - Information about the request or error messages
- **data** (object) - The actual data returned by the endpoint
  - **entry** (object) - The ROM entry object

#### Response Example
(Same format as the `/entry` endpoint response, containing a single random entry)
```

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

### Search Function with Multiple Filters

Source: https://context7.com/cavv-dev/crocdb-api/llms.txt

Allows for complex searches using full-text search, platform filtering, region filtering, and ROM ID matching, with pagination support.

```APIDOC
## POST /search

### Description
Execute complex searches with full-text search, platform filtering, region filtering, and ROM ID matching with pagination.

### Method
POST

### Endpoint
/search

### Parameters
#### Query Parameters
- **search_key** (string) - Required - The text to search for within ROM titles.
- **platforms** (array of strings) - Optional - A list of platform IDs to filter results by.
- **regions** (array of strings) - Optional - A list of region codes to filter results by.
- **rom_id** (string) - Optional - Filters results by a specific ROM ID.
- **max_results** (integer) - Optional - The maximum number of results to return per page (default 25).
- **page** (integer) - Optional - The page number of results to retrieve (default 1).

### Request Body
```json
{
  "search_key": "super mario",
  "platforms": ["snes", "n64"],
  "regions": ["us"],
  "max_results": 25,
  "page": 1
}
```

### Response
#### Success Response (200)
- **data** (object)
  - **results** (array) - A list of matching ROM entries.
    - **title** (string) - The title of the ROM.
    - **platform** (string) - The platform ID the ROM belongs to.
    - **rom_id** (string) - The unique identifier for the ROM.
    - **regions** (array of strings) - The regions the ROM is available in.
    - **links** (array) - Download links for the ROM.
  - **current_page** (integer) - The current page number of the results.
  - **total_pages** (integer) - The total number of pages available.
  - **current_results** (integer) - The number of results on the current page.
  - **total_results** (integer) - The total number of results found.

#### Response Example
```json
{
  "info": {},
  "data": {
    "results": [
      {
        "title": "Super Mario 64",
        "platform": "n64",
        "rom_id": "sm64-usa-rev2",
        "regions": ["us"],
        "links": [
          {
            "name": "Download",
            "format": "zip",
            "size_str": "30MB",
            "url": "http://example.com/download/sm64.zip",
            "host": "example.com"
          }
        ]
      }
    ],
    "current_page": 1,
    "total_pages": 5,
    "current_results": 1,
    "total_results": 20
  }
}
```
```

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

### API Error Response (JSON)

Source: https://github.com/cavv-dev/crocdb-api/blob/main/API_DOCUMENTATION.md

Illustrates the structure of an error response from the API. Upon encountering an error, the API returns an appropriate HTTP status code and an error message within the 'info' object.

```json
{
  "info": {
    "error": "An unexpected error occurred"
  },
  "data": {}
}
```