Uploading

Upload an asset

Puts a file you already have into the pack — the Studio's Upload button. Free: nothing is generated, though it counts toward the pack's asset limit.

What file must be, and what else each type needs:

- block — a PNG. target is the vanilla block texture it replaces (stone_bricks); without one it is a texture of your own, named name. Square, 1–256px, or send size to resample. faceSlot with a target replaces one face only. - item — a PNG. target is the vanilla item it replaces (diamond_sword); without one it is a custom item named name. Square, 8–256px, or send size. - icon — a PNG of any shape, drawn as a chat glyph. Needs name. Kept at its own size when 32px tall or less, else 16 tall; height overrides it (1–256). - model — Minecraft block model JSON, or a Blockbench .bbmodel (its embedded textures come in with it). - sound — Ogg Vorbis, or WAV (converted to Ogg). Needs event. MP3 is not accepted; convert it first. - gui — a 256x256 PNG sheet. target is the vanilla screen it reskins (generic_54, furnace…). - hud — a PNG of the HUD sheet, at its own size. - armor — a PNG armour sheet (64x32). target is the vanilla set (iron, diamond…). - armor3d — a Blockbench .bbmodel of a 3D armour set.

Images must be PNG. Answers 201 with the asset ready — there is no job to wait for.

POST/packs/{pack}/assets

Path parameters

packstringrequired

The pack's slug, as returned by the packs endpoints.

Body

typestringrequired

What the file is.

Options: block, item, icon, model, sound, gui, hud, armor, armor3d

fileobjectrequired

The file. Exactly one of upload, url, base64 or text.

uploadstring

The upload id from POST /uploads, after PUTting the file to its URL. The way to send anything big, or anything already on disk.

urlstring

A public https URL to fetch the file from.

base64string

The file's bytes as base64 (a data: URI is fine). Up to 8MB.

textstring

The file as text, for formats that are text (model JSON, .bbmodel). Up to 8MB.

namestring

Your label, and the name of a texture, item or icon of your own. Defaults to the file's name when it came from a url.

targetstring

The vanilla thing it replaces: a block texture, an item, a GUI screen id or an armour set.

sizeinteger1–256

Resample a block or item image to this square edge.

heightinteger1–256

An icon's height in pixels; its width follows the picture's shape.

faceSlotstring

With a block target: replace one face only.

Options: top, bottom, side

eventstring

A sound's Minecraft event name. Required for sound.

categorystring

A sound's volume slider.

Options: master, music, record, weather, block, hostile, neutral, player, ambient, voice

carrierKindstring

How a model is placed in game. Defaults to item for a .bbmodel and full for block model JSON.

Options: item, full, partial

charstring

An icon's character, if you want a particular one.

Response · 201

The asset, ready.

idstringrequired

The asset's id, which also works as a job handle.

typestringrequired

What the asset is.

Options: model, vehicle, block, block_face, model_texture, item, item_model, item3d, armor, armor3d, gui, hud, dialog, icon, sound

kindstringrequired

The file format it is stored as.

Options: texture, model, font, sound

namestringrequired

Its stored name, for GET /packs/{pack}/assets/{kind}/{name}.

statusstringrequired

Always ready.

packstringrequired

The pack it was written into.

Error codes

Branch on error.code, never on the message.

file_fetch_failed400

A file given by url couldn't be downloaded.

invalid_request400

Something in the body or query is wrong. message says what.

invalid_api_key401

The key isn't one of ours, or it has been revoked.

missing_api_key401

No Authorization: Bearer header was sent.

wrong_key_kind401

An MCP key sent to the REST API, or an API key sent to the MCP server. Each only opens its own.

asset_limit_reached403

The pack is at its asset limit.

forbidden403

Valid key, but not permitted to do this in this pack.

plan_required403

The key is valid, but its account is on Starter. The API needs a paid plan.

not_found404

No such pack, asset or job.

upload_not_found404

No upload by that id. Uploads expire after fifteen minutes and are used once.

conflict409

That vanilla target is already reskinned in this pack. Change it in the Studio rather than overwriting it.

file_too_large413

The file is over the limit for what it's being used as. message says the limit.