Skip to content

Enter a tool name, task, or method name.

Open BDE
On this page

Your first request and JSON response

Export a small BDEngine model, retrieve it with curl, inspect the JSON response, and save it before the temporary export ID expires.

Start with a small model, such as a single stone block. This makes the response easier to read before you work with animation frames and other optional data.

Prepare an export

  1. Open or create a small project in BDEngine.
  2. Select the target Minecraft version and a model-only export.
  3. Use Export to Minecraft Server and wait for publication to succeed.
  4. Copy the six-digit export ID. This is not the model’s catalog ID.

For the editor steps, see Export to Minecraft Server.

Request the data

Replace 123456 with the ID you just received:

Terminal window
curl "https://www.block-display.com/server-api?id=123456&tag=my_model"

In Windows PowerShell, use curl.exe if curl resolves to a PowerShell alias. Keep the URL in quotes so that & remains part of the query string.

The optional tag parameter defaults to bde. Here it is my_model. See Requests, parameters, and export lifetime for the request parameters.

To include response headers, add -i:

Terminal window
curl -i "https://www.block-display.com/server-api?id=123456&tag=my_model"

HTTP 200 indicates a successful response. HTTP 404 means the export cannot be found or its 10-minute lifetime has ended. For 429, wait for the interval specified in Retry-After. See Errors, versions, and compatibility.

Inspect the response

The following is an illustrative response, not a captured export:

{
  "content": {
    "version": "1.21.4",
    "type": "modelOnly",
    "passengers": [
      "{id:\"minecraft:block_display\",Tags:[\"my_model_0\"],block_state:{Name:\"minecraft:stone\"}}"
    ],
    "meta": {
      "schema": 1,
      "animations": {},
      "sounds": {}
    }
  }
}
  • content is the export object inside the HTTP response.
  • version is the Minecraft version selected for the export.
  • type: "modelOnly" identifies a model export.
  • passengers contains SNBT strings, not JSON entity objects.
  • meta contains metadata. Animation and sound maps can be empty.

Actual fields depend on the project and export mode. Continue with JSON structure for the complete structure.

Save the response

An export expires 10 minutes after publication. Downloading it does not extend its lifetime or remove it. You can request it again, including with another tag, while the ID is valid.

To save the response to a file:

Terminal window
curl --fail-with-body --output model.json "https://www.block-display.com/server-api?id=123456&tag=my_model"

Check the HTTP status and the command’s result: an error response can also be written to the output file. A successfully saved response remains yours to use after the ID expires. Publish again if the project changes or you need a new ID.

See Requests, parameters, and export lifetime for the export lifecycle.

Next steps

JSON structureLearn which fields are available and how models, frames, and metadata fit together.
Export support and limitationsCheck what the response includes and what your integration must provide.

The response gives you the export data. Your integration is responsible for using it in Minecraft.