This section is currently being written and will be updated frequently.

Important: Server API is primarily intended for developers of server plugins and custom integrations. There are no official plugins for this API.

Server API allows you to retrieve a published model by its ID in JSON format.
This JSON can then be used server-side to create your own integration: spawning the model, adding hitboxes, playing sounds, and running animations.

The model ID is temporary and remains valid for only 5 minutes after publication. After that time expires, the ID is removed from the service and can no longer be used to retrieve the model.

Publishing a model

After exporting to Minecraft Server, the model is published on the service side and becomes available via a unique ID.
The user sees a successful publication message, the model ID, and a quick command as an integration example.

Getting the model ID

The main model identifier is a numeric ID, for example 241235.
This is the ID that must be passed to the Server API to retrieve the model JSON description.

Important: the received ID is valid for only 5 minutes. If the plugin or server does not request the model data within this time, the model must be published again to obtain a new ID.

A quick command like /bde spawn 241235 is only an example of how a server plugin may use the model ID. The actual behavior of this command fully depends on the plugin implementation.

To retrieve model data, perform a GET request to the following endpoint:

GET https://block-display.com/server-api/?id=MODEL_ID

Example:

GET https://block-display.com/server-api/?id=241235

The tag parameter is optional.
It allows you to define a custom tag that will be inserted into the model data.
If the parameter is not specified, the value bde is used.

Example request with a custom tag:

GET https://block-display.com/server-api/?id=241235&tag=my_model_1

The ID passed in the request is valid for only 5 minutes after the model is published.

On success, the API returns a JSON object with a content field containing the model data.

Main fields

content.version — версия формата данных.
content.type — тип экспортированного содержимого.
content.passengers — визуальные части модели.
content.datapack.anim_keyframes — ключевые кадры анимаций.
content.datapack.sound_keyframes — ключевые кадры звуков.
content.hitbox — данные для создания хитбоксов.

The exact interpretation of these fields depends on your server-side implementation. The API does not enforce a specific way of processing the data.

The passengers field contains a list of model parts.
Each entry is a string with entity data that can be used to build the visual part of the model on the server.

{
  "passengers": [
    "{id:\"minecraft:block_display\",block_state:{Name:\"minecraft:oak_log\",Properties:{axis:\"x\"}},transformation:[1f,0f,0f,0.5625f,0f,1f,0f,0f,0f,0f,1f,0.25f,0f,0f,0f,1f],Tags:[\"bde_0\"]}"
  ]
}

The content.datapack.anim_keyframes field contains animations and their keyframes.
Each frame contains a list of commands that should be applied to the relevant model entities.

{
  "anim_keyframes": {
    "default": {
      "0": [
        "data merge entity @e[type=block_display,tag=bde_0,distance=..1,limit=1,sort=nearest] {transformation:[1f,0f,0f,0.5625f,0f,1f,0f,0f,0f,0f,1f,0.25f,0f,0f,0f,1f],interpolation_duration:0}"
      ]
    }
  }
}

The server plugin may execute these commands directly, transform them into its own data structures, or use any other logic for animation playback.

The content.datapack.sound_keyframes field contains sound events distributed across frames.
Usually, each frame stores a list of sound playback commands.

{
  "sound_keyframes": {
    "default": {
      "3": [
        "playsound ambient.basalt_deltas.additions block @a ~ ~ ~ 1 1.125"
      ]
    }
  }
}

The hitbox field contains data for creating hitboxes.
These are separate entities that may be used for collision, interaction, or other server-side purposes.

{
  "hitbox": [
    "summon block_display ~1.4375 ~-0.3125 ~1.5 {Passengers:[{id:\"minecraft:shulker\",NoGravity:1b,Silent:1b,NoAI:1b,Invulnerable:1b,AttachFace:0b,active_effects:[{id:\"minecraft:invisibility\",amplifier:0,duration:-1,show_particles:0b}],attributes:[{id:\"minecraft:scale\",base:3}]}],Tags:[\"bde\",\"bde_hitbox\"]}"
  ]
}

Project functions are not included in the Server API response, even if they exist inside the project.

Server API only provides the data required for custom server-side implementation: model parts, animations, sounds, and hitboxes.

Plugin developers are free to decide how to use the API data.
You may:

- create the model yourself using passengers;
- use anim_keyframes in your own animation system;
- connect sound_keyframes to sound playback;
- create separate hitbox entities from hitbox.

{
  "content": {
    "version": "26.1",
    "type": "full",
    "passengers": [
      "{id:\"minecraft:block_display\",block_state:{Name:\"minecraft:oak_log\",Properties:{axis:\"x\"}},transformation:[1f,0f,0f,0.5625f,0f,1f,0f,0f,0f,0f,1f,0.25f,0f,0f,0f,1f],Tags:[\"bde_0\"]}"
    ],
    "datapack": {
      "anim_keyframes": {
        "default": {
          "0": [
            "data merge entity @e[type=block_display,tag=bde_0,distance=..1,limit=1,sort=nearest] {transformation:[1f,0f,0f,0.5625f,0f,1f,0f,0f,0f,0f,1f,0.25f,0f,0f,0f,1f],interpolation_duration:0}"
          ],
          "1": [
            "data merge entity @e[type=block_display,tag=bde_0,distance=..1,limit=1,sort=nearest] {transformation:[1f,0f,0f,0.504375f,0f,1f,0f,0f,0f,0f,1f,0.358125f,0f,0f,0f,1f],interpolation_duration:2,start_interpolation:0}"
          ]
        }
      },
      "sound_keyframes": {
        "default": {
          "3": [
            "playsound ambient.basalt_deltas.additions block @a ~ ~ ~ 1 1.125"
          ]
        }
      }
    },
    "hitbox": [
      "summon block_display ~1.4375 ~-0.3125 ~1.5 {Passengers:[{id:\"minecraft:shulker\",NoGravity:1b,Silent:1b,NoAI:1b,Invulnerable:1b,AttachFace:0b,active_effects:[{id:\"minecraft:invisibility\",amplifier:0,duration:-1,show_particles:0b}],attributes:[{id:\"minecraft:scale\",base:3}]}],Tags:[\"bde\",\"bde_hitbox\"]}"
    ]
  }
}