# api overview

PracticeBot exposes a public Bukkit Services API under:

```
com.sheldera.practicebot.api.*
```

The public API version in this build is:

```
1.6.0
```

## What the API supports

| Capability                                    | Supported |
| --------------------------------------------- | --------: |
| Get API version                               |       Yes |
| Look up active bots by Citizens NPC UUID      |       Yes |
| Look up active bots by live entity UUID       |       Yes |
| List active runtime bots                      |       Yes |
| Read loaded templates                         |       Yes |
| Spawn a bot from a validated template request |       Yes |
| Despawn a runtime bot                         |       Yes |
| Apply a template to a runtime bot             |       Yes |
| Read immutable bot state snapshots            |       Yes |
| Read current target snapshot                  |       Yes |
| Attach namespaced metadata                    |       Yes |
| Listen to public lifecycle events             |       Yes |
| Update selected CPvP runtime settings         |       Yes |

## What the API does not expose

The API does not expose:

* internal combat engine classes
* Crystal PvP placement/breaking internals
* movement/pathing internals
* Citizens trait internals
* raw bot managers
* GUI editor internals
* license internals
* obfuscation/build details
* unsupported reflective hooks

{% hint style="warning" %}
Addons should import only `com.sheldera.practicebot.api.*`. Any import outside that package is unsupported and may break without notice.
{% endhint %}

## Main API classes

| Class                       | Purpose                                         |
| --------------------------- | ----------------------------------------------- |
| `PracticeBotApi`            | Main API entry point.                           |
| `PracticeBotApiProvider`    | Convenience Bukkit service resolver.            |
| `BotSpawnRequest`           | Validated spawn request builder.                |
| `PracticeBotHandle`         | Stable handle for an active bot.                |
| `PracticeBotStateSnapshot`  | Immutable runtime state snapshot.               |
| `PracticeBotTargetSnapshot` | Immutable target snapshot.                      |
| `BotTemplateView`           | Immutable public template view.                 |
| `CpvpSettingsUpdateRequest` | Validated CPvP runtime settings update request. |
| `PracticeBotMetadataType`   | Supported metadata types.                       |
| `PracticeBotMetadataValue`  | Immutable metadata value.                       |

## API access pattern

```java
PracticeBotApi api = PracticeBotApiProvider.get();
String version = api.getApiVersion();
```

Use Bukkit's `depend` or `softdepend` in your addon `plugin.yml` depending on whether PracticeBot is mandatory.

> **Media placeholder:** Add a screenshot of an addon logging `PracticeBot API 1.6.0 connected` on startup.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://edelweiss-network.gitbook.io/practicebot/developer-guide/api-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.