Requests, parameters, and export lifetime

The public API returns an export using the ID issued by the editor. No authorization or API key is required.

GET endpoint

GET https://www.block-display.com/server-api?id=123456&tag=my_model

Parameter	Required	Value
id	Yes	Six-digit publication ID from the export dialog
tag	No	Value to substitute into export strings; defaults to bde

123456 is a placeholder in every example. Replace it with a valid export ID.

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

The API also supports HEAD and preflight OPTIONS requests. Use GET to retrieve JSON: a HEAD response has no body.

The id parameter and export lifetime

The export ID differs from both the model’s catalog ID and content.project_id. Copy it after a successful publication through Export to Minecraft Server.

An export remains available for 10 minutes from publication:

• You can retrieve it multiple times, including with different tag values.
• Downloading does not delete the export or extend its lifetime.
• Publish again to export an updated project.
• Once an export expires, publishing again provides a new ID.

The ID is intended for retrieving published data. For long-term use, save the export itself. Your integration determines how that data is stored.

The optional tag parameter

The API replaces [BDESERVERTAG] in export strings with the tag value. For example, with tag=my_model:

[BDESERVERTAG]_root → my_model_root
[BDESERVERTAG]_0    → my_model_0

Rule	Behavior
Allowed characters	ASCII letters, digits, _, and -
Letter case	Preserved
Other characters	Removed
Maximum length	100 characters
Missing or empty value	Replaced with bde

Substitution applies to data strings, not just Tags arrays: the placeholder can also appear in selectors and commands. It does not modify the stored export. Requesting the same ID with different tag values produces different substituted strings.

tag does not create a model instance or manage its lifecycle. See passengers: visual entities for the role of entity tags.

Successful response

A successful GET returns HTTP 200 and JSON containing a content object. See JSON structure for field types and illustrative examples. Animation, sound, and other optional data depend on the export.

Quick commands in the editor

Alongside the ID, the editor displays a ready-to-copy command. Its default form is /bde spawn {ID}, with the publication ID substituted. Use the quick-command setting to replace the bde spawn prefix with your own value.

This setting changes the text available for copying. Your server plugin handles the command in Minecraft; changing it does not change the HTTP API. See Quick-command settings in the editor.

Request limits

Two limits apply simultaneously to each external IP address:

Limit	Window
120 requests	60 seconds
1200 requests	3600 seconds

Each window starts with the first request after its counter resets. Exceeding either limit is enough to receive 429.

Requests for different IDs or tag values share the same quota. Requests with invalid IDs also count. Clients behind NAT or another shared external IP share the limits. GET and HEAD consume quota; OPTIONS does not.

For 429, the Retry-After header specifies the wait in seconds. The same value appears in error.retryAfterSeconds.

Retry-After: 45

45 is an example, not a fixed delay. Use the value in the response you receive.

Header	Meaning
X-RateLimit-Limit	The limit described by the response headers
X-RateLimit-Remaining	Requests remaining under that limit
X-RateLimit-Reset	Seconds remaining until the corresponding limit resets

X-RateLimit-Reset is a remaining duration, not a Unix timestamp. One set of headers does not override the other limit. For 429, follow Retry-After.

Browser requests

The public API permits requests from any website:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, HEAD, OPTIONS
Access-Control-Allow-Headers: *

A preflight OPTIONS request returns 204. Cookies are not required, and credentials: "include" is not supported. Use credentials: "omit" for browser requests.

const url = new URL('https://www.block-display.com/server-api');
url.searchParams.set('id', '123456'); // Replace with your export ID.
url.searchParams.set('tag', 'my_model');

const response = await fetch(url, { credentials: 'omit' });
console.log(response.status, await response.text());

This example retrieves and displays the response, including any error text. It does not create a model in Minecraft.

Browser JavaScript can read Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Unsuccessful responses

Check the HTTP status before using content. An error response may contain error as a string or an object. During infrastructure failures, the body may be empty or use a format other than JSON. See Errors, versions, and compatibility for documented statuses and examples.