### HeadDB API Examples: Querying Heads

Source: https://github.com/thesilentpro/headdb/blob/master/README.md

These Java examples showcase various ways to interact with the HeadDB API after the database is ready. It includes fetching total heads, heads by category, by ID, and by texture.

```java
api.onReady().thenAccept(heads -> {
    System.out.println("Total heads: " + heads.size());
    api.findByCategory("Alphabet")
       .thenAccept(catHeads -> System.out.println("Alphabet category: " + catHeads.size()));
});

api.onReady().thenRun(() -> {
    api.findById(1).thenAccept(optHead -> {
        optHead.ifPresentOrElse(
            head -> System.out.println("Head #1: " + head.getName()),
            ()   -> System.out.println("No head with ID 1 found")
        );
    });

    api.findByTexture("cbc826aaafb8dbf67881e68944414f13985064a3f8f044d8edfb4443e76ba")
       .thenAccept(optHead -> {
           optHead.ifPresentOrElse(
               head -> System.out.println("Texture match: " + head.getName()),
               ()   -> System.out.println("No head for that texture")
           );
       });
});
```

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

### Obtain HeadDB API Instance

Source: https://github.com/thesilentpro/headdb/blob/master/README.md

This Java code snippet shows how to retrieve the HeadAPI instance from Bukkit's Services Manager. It includes a check to ensure HeadDB is installed and registered.

```java
RegisteredServiceProvider<HeadAPI> rsp = Bukkit.getServicesManager().getRegistration(HeadAPI.class);
if (rsp == null) {
    // HeadDB is not installed or failed to register
    return;
}
HeadAPI api = rsp.getProvider();
```

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

### Complete Java HeadDB Plugin Integration

Source: https://context7.com/thesilentpro/headdb/llms.txt

A full Spigot plugin integration example demonstrating common patterns for using the HeadDB API. It includes enabling the plugin, retrieving the HeadAPI service, handling its ready state, and processing player commands for searching and browsing heads by category. This code requires the HeadDB plugin to be present on the server.

```java
import com.github.thesilentpro.headdb.api.HeadAPI;
import com.github.thesilentpro.headdb.api.model.Head;
import org.bukkit.Bukkit;
import org.bukkit.command.Command;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;
import org.bukkit.inventory.ItemStack;
import org.bukkit.plugin.RegisteredServiceProvider;
import org.bukkit.plugin.java.JavaPlugin;

import java.util.List;

public class HeadShopPlugin extends JavaPlugin {
    private HeadAPI headAPI;

    @Override
    public void onEnable() {
        // Get HeadAPI service
        RegisteredServiceProvider<HeadAPI> rsp =
            Bukkit.getServicesManager().getRegistration(HeadAPI.class);

        if (rsp == null) {
            getLogger().severe("HeadDB not installed!");
            setEnabled(false);
            return;
        }

        headAPI = rsp.getProvider();

        // Wait for database to load
        headAPI.onReady().thenAccept(heads -> {
            getLogger().info("HeadDB ready! " + heads.size() + " heads available");

            // List all categories for shop
            List<String> categories = headAPI.findKnownCategories();
            getLogger().info("Shop categories: " + String.join(", ", categories));
        }).exceptionally(ex -> {
            getLogger().severe("Failed to load HeadDB: " + ex.getMessage());
            return null;
        });
    }

    @Override
    public boolean onCommand(CommandSender sender, Command cmd,
                            String label, String[] args) {
        if (!(sender instanceof Player player)) {
            sender.sendMessage("Players only!");
            return true;
        }

        if (args.length == 0) {
            player.sendMessage("Usage: /headshop <search> or /headshop category <name>");
            return true;
        }

        if (!headAPI.isReady()) {
            player.sendMessage("HeadDB is still loading, please wait...");
            return true;
        }

        if (args[0].equalsIgnoreCase("category") && args.length > 1) {
            // Browse by category
            String category = args[1];
            headAPI.findByCategory(category).thenAccept(heads -> {
                if (heads.isEmpty()) {
                    player.sendMessage("No heads in category: " + category);
                    return;
                }

                player.sendMessage("Found " + heads.size() + " heads in " + category);
                // Give first 5 heads as samples
                for (int i = 0; i < Math.min(5, heads.size()); i++) {
                    Head head = heads.get(i);
                    player.getInventory().addItem(head.getItem());
                }
                player.sendMessage("Received first " + Math.min(5, heads.size()) + " heads");
            });
        } else {
            // Search by name
            String query = String.join(" ", args);
            headAPI.searchByName(query).thenAccept(results -> {
                if (results.isEmpty()) {
                    player.sendMessage("No heads found for: " + query);
                    return;
                }

                player.sendMessage("Found " + results.size() + " matching heads:");
                for (Head head : results) {
                    player.sendMessage("- " + head.getName() + " [" + head.getCategory() + "]");
                }

                // Give first result
                Head first = results.get(0);
                player.getInventory().addItem(first.getItem());
                player.sendMessage("Received: " + first.getName());
            });
        }

        return true;
    }
}
```

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

### Maven Dependency Configuration for HeadDB API

Source: https://context7.com/thesilentpro/headdb/llms.txt

Configuration for adding the HeadDB API as a dependency to a Maven project. This setup uses the JitPack repository to fetch the HeadDB library. The scope is set to 'provided', indicating that the HeadDB plugin itself should be present on the server at runtime, not bundled within the plugin.

```xml
<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.TheSilentPro.HeadDB</groupId>
        <artifactId>HeadDB</artifactId>
        <version>6.0.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
```

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

### Check and Interact with HeadDB Database Ready State

Source: https://context7.com/thesilentpro/headdb/llms.txt

This code provides methods to check if the HeadDB database is ready and to perform actions accordingly. It includes examples for a non-blocking check (`isReady()`), a blocking wait (`awaitReady()` - to be used cautiously), and an asynchronous callback using `onReady().thenAccept()` for recommended usage.

```java
import com.github.thesilentpro.headdb.api.HeadAPI;
import com.github.thesilentpro.headdb.api.model.Head;
import java.util.List;

// Non-blocking check
if (headAPI.isReady()) {
    // Database is loaded (successfully or failed)
    headAPI.getHeads().thenAccept(heads -> {
        System.out.println("Total heads available: " + heads.size());
    });
}

// Blocking wait (avoid on main thread)
// headAPI.awaitReady(); // Blocks until database loads
// System.out.println("Database is now ready");

// Async callback (recommended approach)
headAPI.onReady().thenAccept(heads -> {
    System.out.println("Database loaded: " + heads.size() + " heads");
    // Perform operations here
}).exceptionally(ex -> {
    System.err.println("Database failed to load: " + ex.getMessage());
    return null;
});
```

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

### Gradle Dependency Configuration for HeadDB API

Source: https://context7.com/thesilentpro/headdb/llms.txt

An alternative dependency configuration for integrating the HeadDB API into a Gradle-based project. This setup includes the JitPack repository and declares the HeadDB dependency using `compileOnly`. Similar to the Maven configuration, this ensures the HeadDB plugin is available at runtime without being bundled.

```gradle
repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
}

dependencies {
    compileOnly 'com.github.TheSilentPro.HeadDB:HeadDB:6.0.0'
}
```

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

### HeadDB Database Ready State

Source: https://context7.com/thesilentpro/headdb/llms.txt

Provides methods to check if the HeadDB database has finished loading and to get notified when it's ready for operations.

```APIDOC
## Checking Database Ready State

Verify database loading status before performing operations.

### Method
GET

### Endpoint
`/`

### Description
Checks the ready state of the HeadDB database and provides asynchronous callbacks for status updates.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
import com.github.thesilentpro.headdb.api.HeadAPI;
import com.github.thesilentpro.headdb.api.model.Head;
import java.util.List;

// Non-blocking check
if (headAPI.isReady()) {
    // Database is loaded (successfully or failed)
    headAPI.getHeads().thenAccept(heads -> {
        System.out.println("Total heads available: " + heads.size());
    });
}

// Blocking wait (avoid on main thread)
// headAPI.awaitReady(); // Blocks until database loads
// System.out.println("Database is now ready");

// Async callback (recommended approach)
headAPI.onReady().thenAccept(heads -> {
    System.out.println("Database loaded: " + heads.size() + " heads");
    // Perform operations here
}).exceptionally(ex -> {
    System.err.println("Database failed to load: " + ex.getMessage());
    return null;
});
```

### Response
#### Success Response (200)
- **readyState** (boolean) - Indicates if the database is ready.
- **allHeads** (List<Head>) - A list of all available heads if the database is ready.

#### Response Example
`isReady()` returns a boolean. `onReady()` returns a `CompletableFuture<List<Head>>`.
```

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

### Database Readiness Checks

Source: https://github.com/thesilentpro/headdb/blob/master/README.md

Methods to check if the HeadDB database is ready and to block until it is.

```APIDOC
## GET /database/ready

### Description
Checks if the HeadDB database has finished its initial load and is ready for queries.

### Method
GET

### Endpoint
/database/ready

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **ready** (boolean) - True if the database is ready, false otherwise.

#### Response Example
```json
{
  "ready": true
}
```

## POST /database/await-ready

### Description
Blocks the current thread until the HeadDB database finishes its initial load.

### Method
POST

### Endpoint
/database/await-ready

### Parameters
None

### Request Example
None

### Response
#### Success Response (204)
No content returned on successful completion.

#### Response Example
None
```

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

### Check and Wait for HeadDB Database Ready Status

Source: https://github.com/thesilentpro/headdb/blob/master/README.md

This Java code demonstrates how to check if the HeadDB database is ready for use, block until it's loaded, or asynchronously wait for the loading process to complete.

```java
// Check if ready without blocking
boolean ready = api.isReady();

// Block until initial load completes
api.awaitReady();

// Asynchronously wait; returns CompletableFuture<List<Head>>
api.onReady().thenAccept(headList -> {
    System.out.println("Loaded " + headList.size() + " heads!");
});
```

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

### HeadDB API Service Integration

Source: https://context7.com/thesilentpro/headdb/llms.txt

Demonstrates how to obtain an instance of the HeadAPI service using Bukkit's ServiceManager, which is essential for interacting with the HeadDB plugin.

```APIDOC
## Obtaining the HeadAPI Service

Access the HeadAPI through Bukkit's ServiceManager for plugin integration.

### Method
GET

### Endpoint
`/`

### Description
Retrieves the `HeadAPI` service provider from Bukkit's ServiceManager.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
import com.github.thesilentpro.headdb.api.HeadAPI;
import org.bukkit.Bukkit;
import org.bukkit.plugin.RegisteredServiceProvider;

public class MyPlugin extends JavaPlugin {
    private HeadAPI headAPI;

    @Override
    public void onEnable() {
        RegisteredServiceProvider<HeadAPI> rsp = Bukkit.getServicesManager()
            .getRegistration(HeadAPI.class);

        if (rsp == null) {
            getLogger().severe("HeadDB not found! Disabling plugin.");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }

        this.headAPI = rsp.getProvider();

        // Wait for database to load before using API
        headAPI.onReady().thenAccept(heads -> {
            getLogger().info("HeadDB loaded with " + heads.size() + " heads");
            // Now safe to use the API
        });
    }
}
```

### Response
#### Success Response (200)
- **headAPI** (HeadAPI) - An instance of the HeadAPI service.

#### Response Example
`HeadAPI instance obtained via rsp.getProvider()`
```

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

### Add Gradle Dependency for HeadDB

Source: https://github.com/thesilentpro/headdb/blob/master/README.md

This snippet demonstrates how to include the HeadDB API as a dependency in your Gradle project. It involves adding the JitPack repository to your build script.

```gradle
repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation "com.github.TheSilentPro.HeadDB:HeadDB:VERSION"
```

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

### Access HeadAPI Service via Bukkit ServiceManager

Source: https://context7.com/thesilentpro/headdb/llms.txt

This snippet demonstrates how to obtain an instance of the HeadAPI service using Bukkit's ServiceManager. It includes error handling if the HeadDB plugin is not found and shows how to use `onReady()` to ensure the database is loaded before interacting with the API.

```java
import com.github.thesilentpro.headdb.api.HeadAPI;
import org.bukkit.Bukkit;
import org.bukkit.plugin.RegisteredServiceProvider;
import org.bukkit.plugin.java.JavaPlugin;

public class MyPlugin extends JavaPlugin {
    private HeadAPI headAPI;

    @Override
    public void onEnable() {
        RegisteredServiceProvider<HeadAPI> rsp = Bukkit.getServicesManager()
            .getRegistration(HeadAPI.class);

        if (rsp == null) {
            getLogger().severe("HeadDB not found! Disabling plugin.");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }

        this.headAPI = rsp.getProvider();

        // Wait for database to load before using API
        headAPI.onReady().thenAccept(heads -> {
            getLogger().info("HeadDB loaded with " + heads.size() + " heads");
            // Now safe to use the API
        });
    }
}
```

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

### Search Heads by Name in HeadDB

Source: https://context7.com/thesilentpro/headdb/llms.txt

This snippet illustrates how to search for heads in the HeadDB database by name. It covers both lenient (fuzzy) matching and exact, case-insensitive matching. It also shows how to retrieve a list of results or a single optional head.

```java
import com.github.thesilentpro.headdb.api.model.Head;
import java.util.List;

// Lenient search (fuzzy matching, default behavior)
headAPI.searchByName("dragon").thenAccept(results -> {
    System.out.println("Found " + results.size() + " dragon heads:");
    for (Head head : results) {
        System.out.println("- " + head.getName() + " (ID: " + head.getId() + ")");
    }
});

// Exact search (case-insensitive)
headAPI.searchByName("Red Dragon", false).thenAccept(results -> {
    if (results.isEmpty()) {
        System.out.println("No exact match found");
    } else {
        System.out.println("Exact matches: " + results.size());
    }
});

// Find first match only
headAPI.findByName("creeper").thenAccept(optHead -> {
    optHead.ifPresentOrElse(
        head -> System.out.println("Found: " + head.getName()),
        () -> System.out.println("No head found")
    );
});

// Exact name lookup
headAPI.findByName("Steve Head", false).thenAccept(optHead -> {
    optHead.ifPresent(head -> {
        System.out.println("ID: " + head.getId());
        System.out.println("Texture: " + head.getTexture());
        System.out.println("Category: " + head.getCategory());
    });
});
```

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

### Add Maven Dependency for HeadDB

Source: https://github.com/thesilentpro/headdb/blob/master/README.md

This snippet shows how to add the HeadDB API as a dependency to your Maven project. It requires configuring the JitPack repository.

```xml
<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.github.TheSilentPro.HeadDB</groupId>
    <artifactId>HeadDB</artifactId>
    <version>VERSION</version>
  </dependency>
</dependencies>
```

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

### HeadDB API Reference

Source: https://github.com/thesilentpro/headdb/blob/master/README.md

This section details how to obtain and use the HeadDB API to interact with the Minecraft head database.

```APIDOC
## HeadDB API Integration

### Description
This section details how to obtain and use the HeadDB API to interact with the Minecraft head database.

### Obtaining the API
HeadDB's main `HeadAPI` is registered with Bukkit's Services Manager. You can retrieve it as follows:

```java
import com.thesilentpro.headdb.api.HeadAPI;
import org.bukkit.Bukkit;
import org.bukkit.plugin.RegisteredServiceProvider;

// ... inside your plugin class

RegisteredServiceProvider<HeadAPI> rsp = Bukkit.getServicesManager().getRegistration(HeadAPI.class);
if (rsp == null) {
    // HeadDB is not installed or failed to register
    getLogger().severe("HeadDB not found!");
    return;
}
HeadAPI api = rsp.getProvider();
```

### Waiting for Database Ready
The head database loads asynchronously. You can check its status or wait for it to be ready before making requests.

```java
// Check if ready without blocking
boolean ready = api.isReady();

// Block until initial load completes
api.awaitReady();

// Asynchronously wait; returns CompletableFuture<List<Head>>
api.onReady().thenAccept(headList -> {
    System.out.println("Loaded " + headList.size() + " heads!");
});
```

### Examples
Here are some examples of how to use the HeadAPI to query head data:

```java
// Assuming 'api' is your obtained HeadAPI instance

api.onReady().thenAccept(heads -> {
    System.out.println("Total heads: " + heads.size());
    
    // Find heads by category
    api.findByCategory("Alphabet")
       .thenAccept(catHeads -> System.out.println("Alphabet category: " + catHeads.size()));
});

api.onReady().thenRun(() -> {
    // Find head by ID
    api.findById(1).thenAccept(optHead -> {
        optHead.ifPresentOrElse(
            head -> System.out.println("Head #1: " + head.getName()),
            ()   -> System.out.println("No head with ID 1 found")
        );
    });

    // Find head by texture
    api.findByTexture("cbc826aaafb8dbf67881e68944414f13985064a3f8f044d8edfb4443e76ba")
       .thenAccept(optHead -> {
           optHead.ifPresentOrElse(
               head -> System.out.println("Texture match: " + head.getName()),
               ()   -> System.out.println("No head for that texture")
           );
       });
});
```

### Method
`GET` (Conceptual - these are Java method calls, not HTTP requests)

### Endpoint
N/A (These are API calls within a Java environment)

### Parameters

#### Query Parameters
- **category** (String) - Optional - The category to filter heads by.
- **id** (Integer) - Optional - The unique ID of the head.
- **texture** (String) - Optional - The texture hash of the head.

### Request Example
N/A

### Response

#### Success Response (200)
- **Head** (Object) - Represents a single Minecraft head with properties like name, ID, texture, etc.
- **List<Head>** (Array) - A list of Head objects.
- **Optional<Head>** (Object) - An optional object that may contain a Head object or be empty.

#### Response Example
```json
{
  "id": 1,
  "name": "Example Head",
  "texture": "cbc826aaafb8dbf67881e68944414f13985064a3f8f044d8edfb4443e76ba",
  "categories": ["Example"],
  "tags": ["custom"]
}
```
```

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

### Head Item Generation

Source: https://github.com/thesilentpro/headdb/blob/master/README.md

Methods for generating `ItemStack` objects for player heads.

```APIDOC
## POST /heads/generate/local

### Description
Generates `ItemStack` objects for all currently online players.

### Method
POST

### Endpoint
/heads/generate/local

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **generatedHeads** (Map<String, ItemStack>) - A map where keys are player UUIDs and values are the generated `ItemStack` objects for their heads.

#### Response Example
```json
{
  "generatedHeads": {
    "player_uuid_1": { /* ItemStack object details */ },
    "player_uuid_2": { /* ItemStack object details */ }
  }
}
```

## POST /heads/generate/local/{uniqueId}

### Description
Generates an `ItemStack` object for a specific player identified by their UUID.

### Method
POST

### Endpoint
/heads/generate/local/{uniqueId}

### Path Parameters
- **uniqueId** (UUID) - Required - The unique identifier (UUID) of the player.

### Request Example
`POST /heads/generate/local/a1b2c3d4-e5f6-7890-1234-567890abcdef`

### Response
#### Success Response (200)
- **itemStack** (ItemStack) - The generated `ItemStack` object for the specified player's head.

#### Response Example
```json
{
  "itemStack": { /* ItemStack object details */ }
}
```
```

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

### Category and Executor Access

Source: https://github.com/thesilentpro/headdb/blob/master/README.md

Methods for listing known categories and accessing the internal executor service.

```APIDOC
## GET /categories

### Description
Lists all known category names within HeadDB.

### Method
GET

### Endpoint
/categories

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **categories** (List<String>) - A list of available category names.

#### Response Example
```json
{
  "categories": ["Player", "Blocks", "Mobs"]
}
```

## GET /executor

### Description
Provides access to the internal `ExecutorService` for advanced workflow management.

### Method
GET

### Endpoint
/executor

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **executor** (ExecutorService) - Access to the internal executor service. (Note: Actual return type is an ExecutorService object, not directly serializable to JSON. This indicates programmatic access.)

#### Response Example
(Programmatic access, no direct JSON example)
```

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

### Head Retrieval and Search

Source: https://github.com/thesilentpro/headdb/blob/master/README.md

Methods for asynchronously retrieving all heads or searching for specific heads by name, ID, texture, category, or tags.

```APIDOC
## GET /heads

### Description
Asynchronously retrieves the full list of loaded heads.

### Method
GET

### Endpoint
/heads

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **heads** (List<Head>) - A list of all loaded head objects.

#### Response Example
```json
{
  "heads": [
    {
      "id": 1,
      "name": "Steve",
      "texture": "texture_hash_1",
      "category": "Player",
      "tags": ["player", "default"]
    }
    // ... more heads
  ]
}
```

## GET /heads/search/name

### Description
Performs a fuzzy or exact name search for heads.

### Method
GET

### Endpoint
/heads/search/name

### Query Parameters
- **name** (String) - Required - The name to search for.
- **lenient** (boolean) - Optional - If true, performs a fuzzy search. Defaults to false.

### Request Example
`GET /heads/search/name?name=Steve&lenient=true`

### Response
#### Success Response (200)
- **heads** (List<Head>) - A list of heads matching the search criteria.

#### Response Example
```json
{
  "heads": [
    {
      "id": 1,
      "name": "Steve",
      "texture": "texture_hash_1",
      "category": "Player",
      "tags": ["player", "default"]
    }
  ]
}
```

## GET /heads/{id}

### Description
Looks up a head by its internal ID.

### Method
GET

### Endpoint
/heads/{id}

### Path Parameters
- **id** (int) - Required - The internal ID of the head to retrieve.

### Request Example
`GET /heads/1`

### Response
#### Success Response (200)
- **head** (Head) - The head object corresponding to the provided ID.

#### Response Example
```json
{
  "head": {
    "id": 1,
    "name": "Steve",
    "texture": "texture_hash_1",
    "category": "Player",
    "tags": ["player", "default"]
  }
}
```

## GET /heads/search/texture/{textureHash}

### Description
Looks up a head by its skin texture hash.

### Method
GET

### Endpoint
/heads/search/texture/{textureHash}

### Path Parameters
- **textureHash** (String) - Required - The texture hash of the skin.

### Request Example
`GET /heads/search/texture/texture_hash_1`

### Response
#### Success Response (200)
- **head** (Head) - The head object corresponding to the provided texture hash.

#### Response Example
```json
{
  "head": {
    "id": 1,
    "name": "Steve",
    "texture": "texture_hash_1",
    "category": "Player",
    "tags": ["player", "default"]
  }
}
```

## GET /heads/search/category/{categoryName}

### Description
Retrieves all heads belonging to a specific category.

### Method
GET

### Endpoint
/heads/search/category/{categoryName}

### Path Parameters
- **categoryName** (String) - Required - The name of the category to search within.

### Request Example
`GET /heads/search/category/Player`

### Response
#### Success Response (200)
- **heads** (List<Head>) - A list of heads within the specified category.

#### Response Example
```json
{
  "heads": [
    {
      "id": 1,
      "name": "Steve",
      "texture": "texture_hash_1",
      "category": "Player",
      "tags": ["player", "default"]
    }
  ]
}
```

## GET /heads/search/tags

### Description
Retrieves heads matching any of the supplied tags.

### Method
GET

### Endpoint
/heads/search/tags

### Query Parameters
- **tags** (String...) - Required - One or more tags to search for.

### Request Example
`GET /heads/search/tags?tags=player&tags=default`

### Response
#### Success Response (200)
- **heads** (List<Head>) - A list of heads matching at least one of the provided tags.

#### Response Example
```json
{
  "heads": [
    {
      "id": 1,
      "name": "Steve",
      "texture": "texture_hash_1",
      "category": "Player",
      "tags": ["player", "default"]
    }
  ]
}
```
```

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

### Search Heads by Tags - Java

Source: https://context7.com/thesilentpro/headdb/llms.txt

Find heads that match one or more specified tags using OR logic. This method is useful for retrieving heads associated with particular themes or attributes.

```java
// Single tag search
headAPI.findByTags("scary").thenAccept(heads -> {
    System.out.println("Scary heads: " + heads.size());
    heads.forEach(head ->
        System.out.println(head.getName() + " - " + String.join(", ", head.getTags()))
    );
});

// Multiple tags (returns heads matching ANY tag)
headAPI.findByTags("halloween", "zombie", "skeleton").thenAccept(heads -> {
    System.out.println("Halloween-themed heads: " + heads.size());
    for (Head head : heads) {
        System.out.println("- " + head.getName() +
            " [" + head.getCategory() + "]");
    }
});
```

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

### HeadDB Search by Name

Source: https://context7.com/thesilentpro/headdb/llms.txt

Allows searching for player heads by their names, supporting both lenient (fuzzy) and exact matching.

```APIDOC
## Searching Heads by Name

Find heads using exact or fuzzy name matching.

### Method
GET

### Endpoint
`/heads/search/name`

### Description
Searches the HeadDB for heads matching the provided name. Supports fuzzy and exact matching.

### Parameters
#### Path Parameters
None

#### Query Parameters
- **name** (string) - Required - The name of the head to search for.
- **exact** (boolean) - Optional - If true, performs an exact, case-insensitive match. Defaults to false (lenient/fuzzy matching).

#### Request Body
None

### Request Example
```java
import com.github.thesilentpro.headdb.api.model.Head;
import java.util.List;

// Lenient search (fuzzy matching, default behavior)
headAPI.searchByName("dragon").thenAccept(results -> {
    System.out.println("Found " + results.size() + " dragon heads:");
    for (Head head : results) {
        System.out.println("- " + head.getName() + " (ID: " + head.getId() + ")");
    }
});

// Exact search (case-insensitive)
headAPI.searchByName("Red Dragon", false).thenAccept(results -> {
    if (results.isEmpty()) {
        System.out.println("No exact match found");
    } else {
        System.out.println("Exact matches: " + results.size());
    }
});

// Find first match only (lenient)
headAPI.findByName("creeper").thenAccept(optHead -> {
    optHead.ifPresentOrElse(
        head -> System.out.println("Found: " + head.getName()),
        () -> System.out.println("No head found")
    );
});

// Exact name lookup
headAPI.findByName("Steve Head", false).thenAccept(optHead -> {
    optHead.ifPresent(head -> {
        System.out.println("ID: " + head.getId());
        System.out.println("Texture: " + head.getTexture());
        System.out.println("Category: " + head.getCategory());
    });
});
```

### Response
#### Success Response (200)
- **results** (List<Head>) - A list of `Head` objects matching the search criteria.
- **firstMatch** (Optional<Head>) - An optional `Head` object representing the first match found (for `findByName` variants).

#### Response Example
```json
{
  "results": [
    {
      "id": "some_head_id",
      "name": "Dragon Head",
      "texture": "some_texture_data",
      "category": "Fantasy",
      "tags": ["dragon", "mythical"],
      "uuid": "player_uuid"
    }
  ]
}
```
OR
```json
{
  "firstMatch": {
      "id": "another_head_id",
      "name": "Creeper Head",
      "texture": "creeper_texture_data",
      "category": "Monsters",
      "tags": ["creeper", "mob"],
      "uuid": "creeper_uuid"
    }
}
```
```

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

### Work with Head Objects and ItemStacks - Java

Source: https://context7.com/thesilentpro/headdb/llms.txt

Access detailed properties of a Head object, such as ID, name, texture, category, and tags. Includes functionality to convert a Head object into a Bukkit ItemStack for in-game use.

```java
import org.bukkit.entity.Player;
import org.bukkit.inventory.ItemStack;
import java.util.List;

headAPI.findById(42).thenAccept(optHead -> {
    if (optHead.isEmpty()) return;

    Head head = optHead.get();

    // Access head properties
    int id = head.getId();
    String name = head.getName();
    String texture = head.getTexture(); // Base64 texture value
    String category = head.getCategory();
    List<String> tags = head.getTags();

    System.out.println("Head: " + name);
    System.out.println("ID: " + id);
    System.out.println("Category: " + category);
    System.out.println("Tags: " + String.join(", ", tags));
    System.out.println("Texture: " + texture.substring(0, 20) + "...");

    // Get as Minecraft ItemStack
    ItemStack headItem = head.getItem();

    // Give to player
    player.getInventory().addItem(headItem);
    player.sendMessage("Received: " + name);
});
```

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

### Find Heads by ID or Texture - Java

Source: https://context7.com/thesilentpro/headdb/llms.txt

Retrieve specific heads from the database using their internal ID or a texture hash. This method returns an Optional Head object, allowing for null-safe handling.

```java
import org.bukkit.inventory.ItemStack;
import java.util.Optional;

// Lookup by internal database ID
headAPI.findById(1337).thenAccept(optHead -> {
    optHead.ifPresentOrElse(
        head -> {
            System.out.println("Head #1337: " + head.getName());
            ItemStack item = head.getItem();
            // Use the ItemStack in inventory, menus, etc.
        },
        () -> System.out.println("Head ID 1337 not found")
    );
});

// Lookup by texture hash (Minecraft skin texture value)
String texture = "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJl";
headAPI.findByTexture(texture).thenAccept(optHead -> {
    if (optHead.isPresent()) {
        Head head = optHead.get();
        System.out.println("Found head: " + head.getName());
        System.out.println("Category: " + head.getCategory());
        System.out.println("Tags: " + String.join(", ", head.getTags()));
    } else {
        System.out.println("Unknown texture");
    }
});
```

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

### Filter Heads by Category - Java

Source: https://context7.com/thesilentpro/headdb/llms.txt

Fetch all available categories and retrieve heads belonging to a specific category. Supports chaining category queries for complex filtering.

```java
import java.util.List;

// Get all known categories
List<String> categories = headAPI.findKnownCategories();
System.out.println("Available categories: " + String.join(", ", categories));

// Get all heads in a category
headAPI.findByCategory("Animals").thenAccept(heads -> {
    System.out.println("Animal heads: " + heads.size());
    heads.forEach(head -> {
        System.out.println("- " + head.getName());
    });
});

// Chain category queries
headAPI.findByCategory("Alphabet").thenAccept(alphabetHeads -> {
    System.out.println("Alphabet: " + alphabetHeads.size() + " heads");
}).thenCompose(v -> headAPI.findByCategory("Food"))
  .thenAccept(foodHeads -> {
      System.out.println("Food: " + foodHeads.size() + " heads");
  });
```

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

### Retrieve Local Player Heads - Java

Source: https://context7.com/thesilentpro/headdb/llms.txt

Generate ItemStacks representing heads for online and offline players on the server. This method utilizes player UUIDs to uniquely identify and create player heads.

```java
import org.bukkit.Bukkit;
import org.bukkit.OfflinePlayer;
import org.bukkit.inventory.ItemStack;
import java.util.List;
import java.util.UUID;

// Get heads for all known players
List<ItemStack> allPlayerHeads = headAPI.computeLocalHeads();
System.out.println("Generated " + allPlayerHeads.size() + " player heads");

// Get head for specific player by UUID
UUID playerUUID = UUID.fromString("069a79f4-44e9-4726-a5be-fca90e38aaf5");
headAPI.computeLocalHead(playerUUID).ifPresentOrElse(
    headItem -> {
        System.out.println("Created head for player UUID: " + playerUUID);
        // Use the ItemStack
    },
    () -> System.out.println("Player not found")
);

// Get head for online player
Player onlinePlayer = Bukkit.getPlayer("Notch");
if (onlinePlayer != null) {
    headAPI.computeLocalHead(onlinePlayer.getUniqueId()).ifPresent(headItem -> {
        onlinePlayer.getInventory().addItem(headItem);
        onlinePlayer.sendMessage("Here's your head!");
    });
}
```

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