Do I need to require API keys for my plugin, or is the App UUID sufficient?

No, your plugin does not need to require an API key. The App UUID alone is sufficient. However, depending on whether a user provides an API key or not, the API response may differ, so the plugin should be able to handle both scenarios gracefully. 

The documentation says the API key is optional, but also says it’s required to access the endpoint. Yet requests work without one—why?

There are two main cases:

1. Endpoints that do not require a license
   Most API endpoints work without a license—for example, the regular heads endpoint.
   However, some parameters within these endpoints do require a license. If such a parameter is requested without a license, it is simply ignored, and a warning message is returned.
   For testing purposes, developers can enable demo mode, which returns a limited dataset while still allowing access to all parameters.

2. Endpoints that require a license
   Some endpoints—such as the tag endpoint—normally require a license. If no license is provided, demo mode is automatically enabled so the endpoint can still be tested without purchasing a license.

This approach ensures that developers can test all functionality before deciding to buy a license.

Should plugin developers rely only on the App UUID, or allow users to configure their own API key?

Plugin developers are required to send their App UUID so we can identify plugins that generate problematic requests.
That said, additional features are unlocked only through a license, so plugin users should be given the option to configure their own API key or license key in the plugin settings.

"It is not permitted to embed API response data statically within the mod or plugin." What does that mean? Is caching allowed?

This term from our TOS means, that it is not allowed to permanently include large amounts of our data directly inside your plugin or mod so that the data ships with it.

Caching, however, is allowed and encouraged.

It is also acceptable to permanently store individual heads for menu icons or a small number of heads when they serve a specific purpose — for example, potion heads used in a custom potion plugin.