api-index.json is the plugin API as data: every public package, type and member, with its signature and doc
comment. It is generated from the shared library's sources, so it always matches the jar a plugin compiles
against. People can search it; AI tools answer from it instead of guessing method names.
PrivBot generates it for every release.
What is in it
Only the packages listed in privbot/api/public-packages.txt, the public API list.
It always includes privbot.api,
privbot.context, privbot.hooks, privbot.task, privbot.query, privbot.wrappers, privbot.ui,
privbot.ui.overlay, privbot.ui.fx and privbot.sdk; the file may list more (for example privbot.mechanics,
the pure mechanic types behind ctx.threats, ctx.hazards, ctx.targets, ctx.loot, ctx.sustain,
ctx.loadouts, ctx.restock, ctx.travel.go and ctx.recovery, such as GearSetup, RestockTarget,
Destination, DeathWatch, ProgressWatchdog and WorldFreeze; ctx.capture is privbot.hooks.Capture). When the file is absent, the
generator uses that minimum list. A type or member annotated @privbot.api.Internal is left out: it is public
only for technical reasons, and plugins must not use it.
{
"schema": 1,
"apiVersion": "1.0.0",
"generatedAt": "2026-11-04T00:00:00Z",
"packages": [{ "name": "privbot.hooks", "doc": "..." }],
"types": [{
"name": "privbot.hooks.Bank",
"kind": "class",
"package": "privbot.hooks",
"doc": "...",
"since": null,
"deprecated": false,
"members": [{
"kind": "method",
"name": "withdraw",
"signature": "boolean withdraw(int itemId, int qty)",
"returns": "boolean",
"params": [{ "name": "itemId", "type": "int" }, { "name": "qty", "type": "int" }],
"doc": "Withdraw qty of the first bank slot matching itemId. ...",
"since": null,
"deprecated": false,
"deprecatedReplacement": null
}]
}]
}
| Field | Meaning |
|---|---|
schema |
Format version, 1. |
apiVersion |
The PrivBot API version the index describes (PrivBot plugin API: versioning and compatibility). |
types[].name |
Canonical name; nested types use dots (privbot.hooks.container.ItemContainerSnapshot.Item). |
types[].kind |
class, interface, enum or annotation. |
members[].kind |
method, field, constructor or enumConstant. |
members[].signature |
The declaration as you would call it, with simple type names: static <T> T ensure(Supplier<T> fn). |
members[].returns, params[].type |
Fully qualified types, generics kept, java.lang. dropped. |
doc |
The doc comment's main text as plain text (no @param/@return text). null when there is none. |
since |
The @since of the member, else of its type or package. null when none. |
deprecated, deprecatedReplacement |
Deprecated by annotation or tag; the replacement named in @deprecated (Bank#withdraw(String, int)) or null. |
Every key is always present: null is written, never left out. Packages and types are sorted by name, members
keep source order, and two runs over the same sources with the same --generated-at are byte-identical.
Capabilities are not in the index. Which calls work on which server is a separate file,
privbot/api/capabilities.json, joined at query time (What works on each server). The two change at different speeds: the index changes
with the code, capabilities change with server verification.
Where it is
sdk/api-index.json in your starter project lists every public type and member.
How tools use it
The AI plugin builder. Its plugin-mode tools
api_search{query}andapi_type{name}answer from this file. Before the AI writes actx.*call it looks the type up, so the call it writes exists with that signature.Search.
api_searchlooks a query up in the index: by intent ("withdraw from bank", "is the player animating") or by name (Bank.withdraw). The fields it can match are the names, signatures and docs above, which is why the doc comments matter (see the end of this page).Type lookup.
api_type{name}returns one type with its members: what to read before calling into a facade you have not used.Your own tools. The file is plain JSON. For example, every member whose name mentions "withdraw":
import json index = json.load(open("sdk/api-index.json", encoding="utf-8")) for t in index["types"]: for m in t["members"]: if "withdraw" in m["name"].lower(): print(t["name"], m["signature"])
Writing docs that index well
The index is only as good as the doc comments:
- Start with what the member does, in one sentence. That sentence is what search shows.
- Say which thread may call it and what
null,-1orfalsemean. "Unreadable" and "no" are different answers. - For an action, say that
truemeans the dispatch was accepted, and what to check to confirm it landed. - Deprecate with
@deprecated use {@link NewType#newMethod(Args)}sodeprecatedReplacementis filled. - Mark new public members
@since <api version>.
The index includes Pvp, FightFrame, FightObservation, PvpFightHistory, PlayerView, ConsumePlanner, PvpArbiter,
StylePlanner, ThreatMemory, IncomingStyleDecision, PvpCues (from ctx.pvp.cues()), KnockoutRisk, WildernessModel, SpellEffects, SwitchCheck and Hotkeys for
PvP plugin authors. The index establishes that a type exists; the capability matrix and each method's nullable or
unreadable contract describe what has actually been verified for a server.
