{"openapi":"3.1.0","info":{"title":"NitroCraft API","version":"1.2.6","description":"Minecraft avatars, skins, capes, renders, player lookup, formatting, and server status endpoints.","license":{"name":"MIT"}},"servers":[{"url":"https://nitrocraft.uk"}],"tags":[{"name":"images","description":"Avatar, skin, cape, and render image endpoints."},{"name":"players","description":"Player lookup and profile endpoints."},{"name":"status","description":"Java/Bedrock server status probes."},{"name":"formatting","description":"Minecraft formatting conversion and stripping."},{"name":"meta","description":"Operational and metadata endpoints."}],"paths":{"/avatars/{id}":{"get":{"tags":["images"],"summary":"Fetch player avatar by UUID.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Mojang UUID (dashed or undashed)."},{"name":"size","in":"query","required":false,"schema":{"type":"string"},"description":"Avatar size in pixels."},{"name":"overlay","in":"query","required":false,"schema":{"type":"string"},"description":"Apply overlay layer when present."},{"name":"default","in":"query","required":false,"schema":{"type":"string"},"description":"Fallback UUID/default name/URL when the target has no skin."}],"responses":{"200":{"description":"Avatar PNG","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"307":{"description":"Redirect to fallback URL."},"422":{"description":"Invalid input."}}}},"/skins/{id}":{"get":{"tags":["images"],"summary":"Fetch player skin by UUID.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Mojang UUID (dashed or undashed)."},{"name":"default","in":"query","required":false,"schema":{"type":"string"},"description":"Fallback UUID/default name/URL when the target has no skin."}],"responses":{"200":{"description":"Skin PNG","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"307":{"description":"Redirect to fallback URL."},"422":{"description":"Invalid input."}}}},"/capes/{id}":{"get":{"tags":["images"],"summary":"Fetch player cape by UUID.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Mojang UUID (dashed or undashed)."},{"name":"default","in":"query","required":false,"schema":{"type":"string"},"description":"Fallback UUID or URL."}],"responses":{"200":{"description":"Cape PNG","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"307":{"description":"Redirect to fallback URL."},"404":{"description":"No cape found and no fallback configured."},"422":{"description":"Invalid input."}}}},"/renders/head/{id}":{"get":{"tags":["images"],"summary":"Fetch isometric head render by UUID.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Mojang UUID (dashed or undashed)."},{"name":"scale","in":"query","required":false,"schema":{"type":"string"},"description":"Render scale factor."},{"name":"overlay","in":"query","required":false,"schema":{"type":"string"},"description":"Apply overlay layer when present."},{"name":"default","in":"query","required":false,"schema":{"type":"string"},"description":"Fallback UUID/default name/URL."}],"responses":{"200":{"description":"Head render PNG","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"307":{"description":"Redirect to fallback URL."},"422":{"description":"Invalid input."}}}},"/renders/body/{id}":{"get":{"tags":["images"],"summary":"Fetch isometric body render by UUID.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Mojang UUID (dashed or undashed)."},{"name":"scale","in":"query","required":false,"schema":{"type":"string"},"description":"Render scale factor."},{"name":"overlay","in":"query","required":false,"schema":{"type":"string"},"description":"Apply overlay layer when present."},{"name":"default","in":"query","required":false,"schema":{"type":"string"},"description":"Fallback UUID/default name/URL."}],"responses":{"200":{"description":"Body render PNG","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"307":{"description":"Redirect to fallback URL."},"422":{"description":"Invalid input."}}}},"/players/{id}":{"get":{"tags":["players"],"summary":"Resolve player identity and texture URLs.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"UUID or Minecraft username."}],"responses":{"200":{"description":"Player identity + texture payload."},"422":{"description":"Invalid player input."}}}},"/players/{id}/profile":{"get":{"tags":["players"],"summary":"Fetch Mojang profile payload.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"UUID or Minecraft username."}],"responses":{"200":{"description":"Mojang profile response."},"422":{"description":"Invalid player input."}}}},"/players/{id}/history":{"get":{"tags":["players"],"summary":"Fetch player name history.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"UUID or Minecraft username."}],"responses":{"200":{"description":"Name history list."},"422":{"description":"Invalid player input."}}}},"/players/{id}/skin-metadata":{"get":{"tags":["players"],"summary":"Fetch skin metadata and optional color sample.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"UUID or Minecraft username."},{"name":"dominantColor","in":"query","required":false,"schema":{"type":"string"},"description":"Whether to compute dominant color."},{"name":"x","in":"query","required":false,"schema":{"type":"string"},"description":"Sample region X."},{"name":"y","in":"query","required":false,"schema":{"type":"string"},"description":"Sample region Y."},{"name":"width","in":"query","required":false,"schema":{"type":"string"},"description":"Sample region width."},{"name":"height","in":"query","required":false,"schema":{"type":"string"},"description":"Sample region height."}],"responses":{"200":{"description":"Skin metadata payload."},"422":{"description":"Invalid input."}}}},"/status/mc":{"get":{"tags":["status"],"summary":"NitroCraft upstream Mojang health report.","responses":{"200":{"description":"Health report payload."}}}},"/status/java":{"get":{"tags":["status"],"summary":"Probe Java server status.","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string"},"description":"Server host or host:port."},{"name":"port","in":"query","required":false,"schema":{"type":"string"},"description":"Optional explicit port."},{"name":"timeoutMs","in":"query","required":false,"schema":{"type":"string"},"description":"Probe timeout in milliseconds."},{"name":"protocolVersion","in":"query","required":false,"schema":{"type":"string"},"description":"Optional protocol override."}],"responses":{"200":{"description":"Java status payload."},"422":{"description":"Invalid input."}}}},"/status/bedrock":{"get":{"tags":["status"],"summary":"Probe Bedrock server status.","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string"},"description":"Server host or host:port."},{"name":"port","in":"query","required":false,"schema":{"type":"string"},"description":"Optional explicit port."},{"name":"timeoutMs","in":"query","required":false,"schema":{"type":"string"},"description":"Probe timeout in milliseconds."}],"responses":{"200":{"description":"Bedrock status payload."},"422":{"description":"Invalid input."}}}},"/status/server":{"get":{"tags":["status"],"summary":"Probe status with edition auto-detection.","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string"},"description":"Server host or host:port."},{"name":"edition","in":"query","required":false,"schema":{"type":"string"},"description":"java, bedrock, or auto."},{"name":"port","in":"query","required":false,"schema":{"type":"string"},"description":"Optional explicit port."},{"name":"timeoutMs","in":"query","required":false,"schema":{"type":"string"},"description":"Probe timeout in milliseconds."},{"name":"protocolVersion","in":"query","required":false,"schema":{"type":"string"},"description":"Optional Java protocol override."}],"responses":{"200":{"description":"Java or Bedrock status payload."},"422":{"description":"Invalid input."}}}},"/status/browser":{"get":{"tags":["status"],"summary":"Batch probe multiple server addresses with bounded concurrency.","parameters":[{"name":"address","in":"query","required":false,"schema":{"type":"string"},"description":"Server target. Repeat this query for multiple hosts."},{"name":"addresses","in":"query","required":false,"schema":{"type":"string"},"description":"Alternative comma/newline-separated target list."},{"name":"source","in":"query","required":false,"schema":{"type":"string"},"description":"Configured source id. Repeat to ingest multiple provider feeds."},{"name":"sources","in":"query","required":false,"schema":{"type":"string"},"description":"Alternative comma/newline-separated source id list."},{"name":"dataset","in":"query","required":false,"schema":{"type":"string"},"description":"Built-in list selection: java or bedrock."},{"name":"list","in":"query","required":false,"schema":{"type":"string"},"description":"Alias for dataset."},{"name":"edition","in":"query","required":false,"schema":{"type":"string"},"description":"java, bedrock, or auto."},{"name":"page","in":"query","required":false,"schema":{"type":"string"},"description":"1-based page index used with dataset mode."},{"name":"perPage","in":"query","required":false,"schema":{"type":"string"},"description":"Page size used with dataset mode (max 100)."},{"name":"limit","in":"query","required":false,"schema":{"type":"string"},"description":"Maximum number of parsed targets to probe."},{"name":"concurrency","in":"query","required":false,"schema":{"type":"string"},"description":"Maximum in-flight probes for this request."},{"name":"port","in":"query","required":false,"schema":{"type":"string"},"description":"Optional explicit port override applied to all targets."},{"name":"timeoutMs","in":"query","required":false,"schema":{"type":"string"},"description":"Probe timeout in milliseconds."},{"name":"protocolVersion","in":"query","required":false,"schema":{"type":"string"},"description":"Optional Java protocol override."}],"responses":{"200":{"description":"Batch status payload with per-target success/error results."},"422":{"description":"Invalid query input."}}}},"/status/icon":{"get":{"tags":["status"],"summary":"Fetch Java server list icon.","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string"},"description":"Java server host or host:port."},{"name":"port","in":"query","required":false,"schema":{"type":"string"},"description":"Optional explicit port."},{"name":"timeoutMs","in":"query","required":false,"schema":{"type":"string"},"description":"Probe timeout in milliseconds."},{"name":"protocolVersion","in":"query","required":false,"schema":{"type":"string"},"description":"Optional Java protocol override."}],"responses":{"200":{"description":"Icon payload (data URI + Base64)."},"422":{"description":"Invalid input."}}}},"/format/html":{"get":{"tags":["formatting"],"summary":"Convert Minecraft formatting codes to HTML.","parameters":[{"name":"text","in":"query","required":true,"schema":{"type":"string"},"description":"Input text with § or & formatting codes."},{"name":"mode","in":"query","required":false,"schema":{"type":"string"},"description":"inline or class."},{"name":"classPrefix","in":"query","required":false,"schema":{"type":"string"},"description":"Class prefix when mode=class."}],"responses":{"200":{"description":"HTML output payload."},"422":{"description":"Invalid input."}}}},"/format/strip":{"get":{"tags":["formatting"],"summary":"Strip Minecraft formatting codes from text.","parameters":[{"name":"text","in":"query","required":true,"schema":{"type":"string"},"description":"Input text with formatting codes."}],"responses":{"200":{"description":"Stripped text payload."},"422":{"description":"Invalid input."}}}},"/format/css":{"get":{"tags":["formatting"],"summary":"Generate CSS classes for formatting mode.","responses":{"200":{"description":"CSS stylesheet.","content":{"text/css":{"schema":{"type":"string"}}}}}}},"/openapi.json":{"get":{"tags":["meta"],"summary":"OpenAPI schema for NitroCraft endpoints.","responses":{"200":{"description":"OpenAPI JSON."}}}},"/metrics":{"get":{"tags":["meta"],"summary":"Prometheus-compatible runtime metrics.","responses":{"200":{"description":"Prometheus text exposition.","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/metrics/api-calls":{"get":{"tags":["meta"],"summary":"Current persisted API call count for homepage stat refresh.","responses":{"200":{"description":"API call count payload.","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}