openapi.yml

openapi: 3.0.3
info:
  title: MineSkin API
  version: 1.0.0
  description: |
    Client implementations: 
    Java: https://github.com/InventivetalentDev/MineskinClient
    NodeJS: https://github.com/InventivetalentDev/mineskin-client
    
    Examples: https://github.com/MineSkin/examples
  contact:
    name: inventivetalent
    url: https://discord.gg/nzAdvPc
    email: info@mineskin.org
  license:
    name: MIT
    url: https://github.com/MineSkin/api.mineskin.org/blob/master/LICENSE
servers:
  - url: https://api.mineskin.org
tags:
  - name: generate
  - name: get
  - name: util

security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      description: API key auth header - Get your key from https://mineskin.org/apikey
      type: http
      scheme: bearer

  schemas:
    PartialSkinInfo:
      type: object
      required: [ id, name, url, time ]
      properties:
        id:
          type: integer
        name:
          type: string
        url:
          type: string
        time:
          type: integer
    SkinInfo:
      type: object
      required: [ id, model, data ]
      properties:
        id:
          type: integer
        idStr:
          type: string
        uuid:
          type: string
        name:
          type: string
        model:
          type: string
          deprecated: true
          enum: [ "slim", "steve", "unknown" ]
        variant:
          type: string
          enum: [ "classic", "slim" ]
        data:
          $ref: '#/components/schemas/SkinData'
        timestamp:
          type: number
        duration:
          type: number
        accountId:
          type: integer
          deprecated: true
        account:
          type: integer
        server:
          type: string
        private:
          type: boolean
        views:
          type: number
    SkinData:
      type: object
      properties:
        uuid:
          type: string
        texture:
          $ref: '#/components/schemas/TextureInfo'
    TextureInfo:
      type: object
      properties:
        value:
          type: string
        signature:
          type: string
        url:
          type: string
    Stats:
      type: object
      properties:
        server:
          type: string
        delay:
          type: number
    GenerateOptions:
      type: object
      properties:
        model:
          deprecated: true
          type: string
          enum: [ "steve", "slim" ]
          default: "steve"
        variant:
          description: Skin variant - automatically determined based on the image if not specified
          type: string
          enum: [ "classic", "slim" ]
        name:
          type: string
          maxLength: 20
        visibility:
          description: "Visibility of the generated skin. 0 for public, 1 for private"
          type: integer
          enum: [ 0, 1 ]
          default: 0
      example:
        variant: "classic"
        name: "My Example Skin"
        visibility: 0
    UserValidation:
      type: object
      required: [ valid ]
      properties:
        valid:
          type: boolean
        uuid:
          type: string
        name:
          type: string
    DelayInfo:
        properties:
          millis:
            type: integer
          seconds:
            type: integer

  parameters:
    userAgent:
      name: User-Agent
      description: Custom User-Agent for your application, see [user-agent.dev](https://user-agent.dev/) for implementation examples
      example: "ExampleApp/v1.0"
      in: header
      required: true
      schema:
        type: string
    apiKey:
      name: Authorization
      description: API Key - Get your key from https://mineskin.org/apikey
      example: "Bearer [YOUR API KEY]"
      in: header
      required: false
      schema:
        type: string


  responses:
    ErrorResponse:
      description: Response if an error occurred
      content:
        application/json:
          schema:
            required: [ error ]
            properties:
              errorCode:
                type: string
                description: Consistent error code, see [AuthError](https://github.com/MineSkin/api.mineskin.org/blob/793a926cbe4b90887ed8164c9eccfcb542fdeadb/src/generator/Authentication.ts#L580) & [GenError](https://github.com/MineSkin/api.mineskin.org/blob/47a5f51dc664e0f730b0073f70b2fc295e14ca3b/src/generator/Generator.ts#L1093)
              error:
                type: string
                description: Error message
    RateLimitResponse:
      description: Response if the client sent a request too soon
      content:
        application/json:
          schema:
            required: [ error ]
            properties:
              error:
                type: string
                description: Error message
              nextRequest:
                deprecated: true
                type: integer
                description: Unix timestamp when the next request is allowed
              delayInfo:
                type: object
                description: Info about the current API delay and when the next request is allowed
                properties:
                  millis:
                    type: integer
                    description: Milliseconds to wait before the next request
                  seconds:
                    type: integer
                    description: Seconds to wait before the next request
              delay:
                type: integer
                description: The API's current delay in seconds

    GeneratedSkin:
      description: Successfully generated skin info
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/SkinInfo'
              - properties:
                  nextRequest:
                    deprecated: true
                    type: integer
                  duplicate:
                    type: boolean
                  delayInfo:
                    $ref: '#/components/schemas/DelayInfo'

paths:
  /generate/url:
    post:
      tags:
        - generate
      parameters:
        - $ref: '#/components/parameters/userAgent'
        - $ref: '#/components/parameters/apiKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/GenerateOptions'
                - properties:
                    url:
                      type: string
            example:
              url: "https://i.imgur.com/kQPrtYw.png"
              visibility: 0
              name: ""
              variant: "classic"
      responses:
        200:
          $ref: '#/components/responses/GeneratedSkin'
        400:
          $ref: '#/components/responses/ErrorResponse'
        429:
          $ref: '#/components/responses/RateLimitResponse'
        500:
          $ref: '#/components/responses/ErrorResponse'
  /generate/upload:
    post:
      tags:
        - generate
      parameters:
        - $ref: '#/components/parameters/userAgent'
        - $ref: '#/components/parameters/apiKey'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              allOf:
                - $ref: '#/components/schemas/GenerateOptions'
                - properties:
                    file:
                      description: Image file to upload
                      type: string
                      format: binary
                      externalDocs:
                        description: Example implementations
                        url: https://github.com/MineSkin/examples
      responses:
        200:
          $ref: '#/components/responses/GeneratedSkin'
        400:
          $ref: '#/components/responses/ErrorResponse'
        429:
          $ref: '#/components/responses/RateLimitResponse'
        500:
          $ref: '#/components/responses/ErrorResponse'
  /generate/user:
    post:
      tags:
        - generate
      parameters:
        - $ref: '#/components/parameters/userAgent'
        - $ref: '#/components/parameters/apiKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/GenerateOptions'
                - properties:
                    uuid:
                      type: string
                      minLength: 32
                      maxLength: 36
              example:
                uuid: "bcd2033c63ec4bf88aca680b22461340"
                visibility: 0
                name: ""
                variant: "slim"
      responses:
        200:
          $ref: '#/components/responses/GeneratedSkin'
        400:
          $ref: '#/components/responses/ErrorResponse'
        429:
          $ref: '#/components/responses/RateLimitResponse'
        500:
          $ref: '#/components/responses/ErrorResponse'

  /get/delay:
    get:
      tags:
        - get
      parameters:
        - $ref: '#/components/parameters/userAgent'
        - $ref: '#/components/parameters/apiKey'
      responses:
        200:
          content:
            application/json:
              schema:
                type: object
                properties:
                  millis:
                    type: integer
                  seconds:
                    type: integer
                  nextRequest:
                    type: object
                    properties:
                      time:
                        type: integer
                      relative:
                        type: integer
                  lastRequest:
                    type: object
                    required: false,
                    properties:
                      time:
                        type: integer
  /get/id/{id}:
    get:
      deprecated: true
      description: Deprecated. Use /get/uuid instead.
      tags:
        - get
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: number
            format: integer
        - $ref: '#/components/parameters/userAgent'
      responses:
        200:
          description: Skin Info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkinInfo'
  /get/uuid/{uuid}:
    get:
      tags:
        - get
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/userAgent'
        - $ref: '#/components/parameters/apiKey'
      responses:
        200:
          description: Skin Info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkinInfo'
  /get/list/{page}:
    get:
      tags:
        - get
      parameters:
        - name: page
          in: path
          required: true
          description: For reference pagination, the uuid of the last skin in the previous page. For numeric pagination (deprecated), the page number or 'start'.
          schema:
            type: number
            format: integer
        - $ref: '#/components/parameters/userAgent'
      responses:
        200:
          description: Skin Info List
          content:
            application/json:
              schema:
                required: [ skins, page ]
                properties:
                  skins:
                    type: array
                    items:
                      $ref: '#/components/schemas/PartialSkinInfo'
                  page:
                    type: object
                    properties:
                      index:
                        type: integer
                      amount:
                        type: integer
                      total:
                        type: integer
                  filter:
                    type: string

  /validate/name/{name}:
    get:
      tags:
        - util
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/userAgent'
      responses:
        200:
          description: Validation info about the requested user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserValidation'
  /validate/uuid/{uuid}:
    get:
      tags:
        - util
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/userAgent'
      responses:
        200:
          description: Validation info about the requested user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserValidation'