canonical: https://jentic.com/apis/mineskin.org/mineskin # MineSkin API Jentic publishes the only available OpenAPI specification for MineSkin API, keeping it validated and agent-ready. MineSkin generates Minecraft player skin textures and signed Mojang skin data from URLs, file uploads, or existing player accounts. The API exposes generation, lookup, validation, and pagination endpoints so developers and agents can produce ready-to-use skin payloads for Minecraft servers, plugins, and avatar tools without managing Mojang's signing flow directly. ## For AI agents Generate signed Minecraft skin textures from a URL, an uploaded image, or a player UUID, and look up previously generated skins by id. Used by Minecraft plugins and avatar tools. ## Scope Does not handle Minecraft authentication, server management, or in-game commands - use for skin texture generation and lookup only. ## Capabilities - Generate a signed Minecraft skin from an image URL with POST `/generate/url` - Upload an image file directly and receive a signed skin payload via POST `/generate/upload` - Reuse an existing Mojang account skin with POST `/generate/user` given a player UUID - Look up a previously generated skin by id with GET `/get/id/{id}` - Resolve a Mojang UUID to its skin record via GET `/get/uuid/{uuid}` - Page through historical skin generations with GET `/get/list/{page}` - Validate a Minecraft username or UUID before submitting it to a generation endpoint ## Use cases ### Minecraft Plugin Avatar Generation Server plugins call `/generate/url` or `/generate/upload` to mint signed skin payloads on demand for cosmetic items, NPCs, or trail effects. MineSkin returns the value and signature pair Mojang expects on the player profile properties, so plugins do not need to handle Mojang authentication themselves. Example prompt: Submit a skin URL via POST `/generate/url` and pass the returned value+signature to a Minecraft plugin's NPC creation call ### Player Skin Lookup Resolve any Minecraft player's current skin from a UUID through GET `/get/uuid/{uuid}.` Useful for leaderboards, profile pages, and avatar caches that render player heads alongside scores or stats. The signed payload can be re-used wherever a Mojang skin is expected. Example prompt: Call GET `/get/uuid/{uuid}` and surface the skin texture URL on a leaderboard avatar ### Skin History Pagination Browse historical generations with GET `/get/list/{page}` for moderation queues, gallery features, or analytics over generated skins. Each page returns a fixed-size set of records that the agent can iterate through to enumerate all skins on the account. Example prompt: Iterate GET `/get/list/{page}` from page 1 onwards until the response returns no records, collecting all skin ids ### Agent-Driven Skin Generation An AI agent receives a player avatar request and uses Jentic to find and call the MineSkin generator without learning the API by hand. Jentic isolates the bearer token, so the agent calls `/generate/url` through a scoped execution request and returns the signed skin payload to the calling app. Example prompt: Search Jentic for 'generate a Minecraft skin from a URL', load the MineSkin schema, and execute against a 64x64 PNG hosted on Imgur ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/generate/url` | Generate a skin from an image URL | | POST | `/generate/upload` | Generate a skin from an uploaded file | | POST | `/generate/user` | Generate from an existing user UUID | | GET | `/get/id/{id}` | Get a skin by id | | GET | `/get/uuid/{uuid}` | Get a skin record by player UUID | | GET | `/get/list/{page}` | Page through generated skins | | GET | `/get/delay` | Get current generation delay | ## Key resources - **Generate** — Create signed skins from a URL, an uploaded file, or an existing player UUID - **Get** — Look up signed skins by skin id, by player UUID, by name, or paged history - **Validate** — Validate Minecraft usernames and UUIDs before sending them to the generator ## Why Jentic - **Setup:** Wiring MineSkin by hand means handling its bearer auth against api.mineskin.org, choosing between the URL, upload, and user generate variants, and respecting the rate delay yourself. Through Jentic you install once, import MineSkin from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** MineSkin puts the skin id and uuid in the URL path (`/get/id/{id}`), so a rule can pin your agent to lookups of a specific skin. You choose the operations it may call, so a generate operation like `/generate/upload` is not included unless you add it. - **Credential handling:** Your MineSkin bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'generate a Minecraft skin' or 'look up a skin by uuid', and Jentic returns the right generate variant with its input schema so the agent picks the correct flow without browsing the reference docs. ## Related APIs - **Cloudinary Upload API** — Cloudinary hosts and transforms the source PNG before it is sent to MineSkin - **Filestack** — Filestack provides upload widgets and CDN URLs that feed into MineSkin generation - **Mux** — Mux focuses on video processing and signed URLs rather than skin textures ## FAQ ### Why is there no official OpenAPI spec for MineSkin API? MineSkin does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call MineSkin API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the MineSkin API use? MineSkin uses HTTP bearer token authentication. The token goes in the Authorization header as `Bearer `. Through Jentic the token is stored in the vault and injected per call so the agent does not handle the raw secret. ### Can I generate a skin from a hosted image URL? Yes. POST `/generate/url` accepts an image URL and returns the signed Minecraft skin texture payload (value and signature) that Mojang expects on a player's profile properties. ### What is `/get/delay` used for? GET `/get/delay` returns the current per-account delay in seconds before the next generation request is allowed. Agents should call it before bursts of /generate calls and back off if the delay is non-zero. ### How do I generate a Minecraft skin through Jentic? Run `pip install jentic`, search Jentic for 'generate a Minecraft skin from a URL', and Jentic returns the MineSkin `/generate/url` operation. Pass the image URL and execute; the signed payload comes back as JSON. ### Can I limit what my agent is allowed to do with the MineSkin API? Yes. Because Jentic One is self-hosted, your own rules decide which MineSkin operations and credentials the agent may use, so you can allow read-only lookups like GET `/get/id/{id}` and GET `/get/uuid/{uuid}` while excluding generation calls such as POST `/generate/upload` or POST `/generate/url.` Since MineSkin puts the skin id and UUID in the URL path, a rule can pin the agent to a specific skin or player record. Your bearer token stays under your control and is injected only for the operations you have permitted.