Developer docs

The API index (api-index.json)

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} and api_type{name} answer from this file. Before the AI writes a ctx.* call it looks the type up, so the call it writes exists with that signature.

  • Search. api_search looks 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, -1 or false mean. "Unreadable" and "no" are different answers.
  • For an action, say that true means the dispatch was accepted, and what to check to confirm it landed.
  • Deprecate with @deprecated use {@link NewType#newMethod(Args)} so deprecatedReplacement is 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.