openapi: 3.0.3
info:
  title: Amiibo API
  description: >-
    AmiiboAPI is a free RESTful API providing comprehensive data about Nintendo
    Amiibo figures, including character details, game series, amiibo series
    classifications, regional release dates, and compatible game information
    across 3DS, Wii U, and Nintendo Switch platforms. The API requires no
    authentication and supports filtering by name, character, game series, type,
    and hexadecimal identifiers.
  version: 1.0.0
  contact:
    name: Nevin Vu
    url: https://amiiboapi.org/
  license:
    name: MIT
    url: https://github.com/N3evin/AmiiboAPI/blob/master/LICENSE
externalDocs:
  description: Official AmiiboAPI Documentation
  url: https://amiiboapi.org/docs/
servers:
  - url: https://amiiboapi.org/api
    description: Production API server
tags:
  - name: Amiibo
    description: Endpoints for retrieving Amiibo figure data
  - name: Reference
    description: Reference data endpoints for types, series, characters, and game series
  - name: Metadata
    description: API metadata endpoints
paths:
  /amiibo/:
    get:
      operationId: getAmiibo
      summary: Get Amiibo figures
      description: >-
        Returns all Amiibo figures or filters by provided query parameters.
        Supports optional modifiers to include compatible game data and usage
        information. Results can be sorted by various fields.
      tags:
        - Amiibo
      parameters:
        - name: id
          in: query
          description: >-
            Full 16-character hexadecimal Amiibo identifier (combination of
            head and tail).
          required: false
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{16}$'
            example: '0000000000000002'
        - name: head
          in: query
          description: >-
            First 8 hexadecimal characters of the Amiibo ID representing game
            series, character, variant, and type.
          required: false
          schema:
            type: string
            pattern: '^(0x)?[0-9a-fA-F]{1,8}$'
            example: '00000000'
        - name: tail
          in: query
          description: >-
            Last 8 hexadecimal characters of the Amiibo ID representing the
            amiibo model and series.
          required: false
          schema:
            type: string
            pattern: '^(0x)?[0-9a-fA-F]{1,8}$'
            example: '00000002'
        - name: name
          in: query
          description: Filter by Amiibo name (case-insensitive substring match).
          required: false
          schema:
            type: string
            example: 'Link'
        - name: character
          in: query
          description: >-
            Filter by character name or hexadecimal character ID (prefix with
            0x for hex).
          required: false
          schema:
            type: string
            example: 'Link'
        - name: gameseries
          in: query
          description: >-
            Filter by game series name or hexadecimal game series ID (prefix
            with 0x for hex).
          required: false
          schema:
            type: string
            example: 'The Legend of Zelda'
        - name: amiiboSeries
          in: query
          description: >-
            Filter by Amiibo series name or hexadecimal amiibo series ID
            (prefix with 0x for hex).
          required: false
          schema:
            type: string
            example: 'Super Smash Bros.'
        - name: type
          in: query
          description: >-
            Filter by Amiibo type name (e.g., Figure, Card, Yarn) or
            hexadecimal type ID (prefix with 0x for hex).
          required: false
          schema:
            type: string
            example: 'Figure'
        - name: variant
          in: query
          description: Filter by hexadecimal variant ID.
          required: false
          schema:
            type: string
            pattern: '^(0x)?[0-9a-fA-F]+$'
        - name: amiibo_model
          in: query
          description: Filter by hexadecimal Amiibo model ID.
          required: false
          schema:
            type: string
            pattern: '^(0x)?[0-9a-fA-F]+$'
        - name: switch_titleid
          in: query
          description: Filter by Nintendo Switch game title ID.
          required: false
          schema:
            type: string
        - name: wiiu_titleid
          in: query
          description: Filter by Wii U game title ID.
          required: false
          schema:
            type: string
        - name: 3ds_titleid
          in: query
          description: Filter by Nintendo 3DS game title ID.
          required: false
          schema:
            type: string
        - name: showgames
          in: query
          description: >-
            When present, includes compatible game data for each Amiibo (games
            for 3DS, Wii U, and Switch with title IDs).
          required: false
          schema:
            type: boolean
        - name: showusage
          in: query
          description: >-
            When present, includes compatible game data along with usage
            information describing how the Amiibo is used in each game.
          required: false
          schema:
            type: boolean
        - name: sort
          in: query
          description: >-
            Comma-separated list of fields to sort by. Valid values: id, head,
            tail, name, gameseries, gameseries_id, gameseries_name, character,
            character_id, character_name, variant, variant_id, type, type_id,
            type_name, amiibo_model, amiibo_model_id, series, series_id,
            series_name, release_na, release_jp, release_eu, release_au.
          required: false
          schema:
            type: string
            example: 'name,release_na'
      responses:
        '200':
          description: Successful response with list of Amiibo figures
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmiiboListResponse'
              examples:
                basic:
                  $ref: '#/components/examples/AmiiboListExample'
                withGames:
                  $ref: '#/components/examples/AmiiboWithGamesExample'
        '400':
          description: Bad request — invalid hex identifier format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No Amiibo found matching the provided filters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /amiibofull/:
    get:
      operationId: getAmiiboFull
      summary: Get Amiibo figures with full game compatibility data
      description: >-
        Returns Amiibo figures with complete game compatibility information
        including games for 3DS, Wii U, and Nintendo Switch. Supports the
        same filtering and sorting parameters as /amiibo/.
      tags:
        - Amiibo
      parameters:
        - name: id
          in: query
          description: Full 16-character hexadecimal Amiibo identifier.
          required: false
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{16}$'
        - name: head
          in: query
          description: First 8 hexadecimal characters of the Amiibo ID.
          required: false
          schema:
            type: string
            pattern: '^(0x)?[0-9a-fA-F]{1,8}$'
        - name: tail
          in: query
          description: Last 8 hexadecimal characters of the Amiibo ID.
          required: false
          schema:
            type: string
            pattern: '^(0x)?[0-9a-fA-F]{1,8}$'
        - name: name
          in: query
          description: Filter by Amiibo name.
          required: false
          schema:
            type: string
        - name: character
          in: query
          description: Filter by character name or hex ID.
          required: false
          schema:
            type: string
        - name: gameseries
          in: query
          description: Filter by game series name or hex ID.
          required: false
          schema:
            type: string
        - name: amiiboSeries
          in: query
          description: Filter by Amiibo series name or hex ID.
          required: false
          schema:
            type: string
        - name: type
          in: query
          description: Filter by type name or hex ID.
          required: false
          schema:
            type: string
        - name: variant
          in: query
          description: Filter by variant hex ID.
          required: false
          schema:
            type: string
        - name: amiibo_model
          in: query
          description: Filter by Amiibo model hex ID.
          required: false
          schema:
            type: string
        - name: switch_titleid
          in: query
          description: Filter by Nintendo Switch game title ID.
          required: false
          schema:
            type: string
        - name: wiiu_titleid
          in: query
          description: Filter by Wii U game title ID.
          required: false
          schema:
            type: string
        - name: 3ds_titleid
          in: query
          description: Filter by Nintendo 3DS game title ID.
          required: false
          schema:
            type: string
        - name: sort
          in: query
          description: >-
            Comma-separated list of fields to sort by. Valid values: id, head,
            tail, name, gameseries, gameseries_id, gameseries_name,
            switch_titleid, 3ds_titleid, wiiu_titleid, character, character_id,
            character_name, variant, variant_id, type, type_id, type_name,
            amiibo_model, amiibo_model_id, series, series_id, series_name,
            release_na, release_jp, release_eu, release_au.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response with Amiibo figures including full game data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmiiboFullListResponse'
        '400':
          description: Bad request — invalid hex identifier format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No Amiibo found matching the provided filters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /type/:
    get:
      operationId: getAmiiboTypes
      summary: Get Amiibo types
      description: >-
        Returns all Amiibo type classifications or filters by key or name.
        Types include Figure, Card, Yarn, and Band.
      tags:
        - Reference
      parameters:
        - name: key
          in: query
          description: Hexadecimal key identifier for the type.
          required: false
          schema:
            type: string
            pattern: '^(0x)?[0-9a-fA-F]+$'
            example: '0x00'
        - name: name
          in: query
          description: Filter by type name.
          required: false
          schema:
            type: string
            example: 'Figure'
        - name: sort
          in: query
          description: Sort by key or name.
          required: false
          schema:
            type: string
            enum:
              - key
              - name
      responses:
        '200':
          description: Successful response with list of Amiibo types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferenceListResponse'
              examples:
                types:
                  $ref: '#/components/examples/TypeListExample'
        '404':
          description: Type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /gameseries/:
    get:
      operationId: getGameSeries
      summary: Get game series
      description: >-
        Returns all game series associated with Amiibo figures or filters by
        hexadecimal key or name.
      tags:
        - Reference
      parameters:
        - name: key
          in: query
          description: Hexadecimal key identifier for the game series.
          required: false
          schema:
            type: string
            pattern: '^(0x)?[0-9a-fA-F]+$'
            example: '0x0000'
        - name: name
          in: query
          description: Filter by game series name.
          required: false
          schema:
            type: string
            example: 'The Legend of Zelda'
        - name: sort
          in: query
          description: Sort by key or name.
          required: false
          schema:
            type: string
            enum:
              - key
              - name
      responses:
        '200':
          description: Successful response with list of game series
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferenceListResponse'
        '404':
          description: Game series not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /amiiboseries/:
    get:
      operationId: getAmiiboSeries
      summary: Get Amiibo series
      description: >-
        Returns all Amiibo series classifications or filters by hexadecimal
        key or name. Examples include Super Smash Bros., The Legend of Zelda,
        and Pokemon.
      tags:
        - Reference
      parameters:
        - name: key
          in: query
          description: Hexadecimal key identifier for the Amiibo series.
          required: false
          schema:
            type: string
            pattern: '^(0x)?[0-9a-fA-F]+$'
            example: '0x00'
        - name: name
          in: query
          description: Filter by Amiibo series name.
          required: false
          schema:
            type: string
            example: 'Super Smash Bros.'
        - name: sort
          in: query
          description: Sort by key or name.
          required: false
          schema:
            type: string
            enum:
              - key
              - name
      responses:
        '200':
          description: Successful response with list of Amiibo series
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferenceListResponse'
        '404':
          description: Amiibo series not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /character/:
    get:
      operationId: getCharacters
      summary: Get characters
      description: >-
        Returns all characters associated with Amiibo figures or filters by
        hexadecimal key or name.
      tags:
        - Reference
      parameters:
        - name: key
          in: query
          description: Hexadecimal key identifier for the character.
          required: false
          schema:
            type: string
            pattern: '^(0x)?[0-9a-fA-F]+$'
            example: '0x0000'
        - name: name
          in: query
          description: Filter by character name.
          required: false
          schema:
            type: string
            example: 'Link'
        - name: sort
          in: query
          description: Sort by key or name.
          required: false
          schema:
            type: string
            enum:
              - key
              - name
      responses:
        '200':
          description: Successful response with list of characters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferenceListResponse'
        '404':
          description: Character not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /lastupdated/:
    get:
      operationId: getLastUpdated
      summary: Get last updated timestamp
      description: >-
        Returns the timestamp indicating when the Amiibo database was last
        updated. Useful for cache invalidation.
      tags:
        - Metadata
      responses:
        '200':
          description: Successful response with last updated timestamp
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LastUpdatedResponse'
              examples:
                lastUpdated:
                  $ref: '#/components/examples/LastUpdatedExample'
components:
  schemas:
    AmiiboRelease:
      type: object
      description: Regional release dates for the Amiibo figure.
      properties:
        au:
          type: string
          format: date
          nullable: true
          description: Release date in Australia (YYYY-MM-DD) or null if not released.
          example: '2014-11-29'
        eu:
          type: string
          format: date
          nullable: true
          description: Release date in Europe (YYYY-MM-DD) or null if not released.
          example: '2014-11-28'
        jp:
          type: string
          format: date
          nullable: true
          description: Release date in Japan (YYYY-MM-DD) or null if not released.
          example: '2014-05-29'
        na:
          type: string
          format: date
          nullable: true
          description: >-
            Release date in North America (YYYY-MM-DD) or null if not
            released.
          example: '2014-11-21'
    Amiibo:
      type: object
      description: Core Amiibo figure data.
      properties:
        amiiboSeries:
          type: string
          description: Name of the Amiibo series this figure belongs to.
          example: 'Super Smash Bros.'
        character:
          type: string
          description: Name of the character represented by this Amiibo.
          example: 'Link'
        gameSeries:
          type: string
          description: Name of the game series this Amiibo is associated with.
          example: 'The Legend of Zelda'
        head:
          type: string
          description: >-
            First 8 hexadecimal characters of the Amiibo ID encoding game
            series, character, variant, and type.
          pattern: '^[0-9a-fA-F]{8}$'
          example: '01000000'
        tail:
          type: string
          description: >-
            Last 8 hexadecimal characters of the Amiibo ID encoding model and
            series.
          pattern: '^[0-9a-fA-F]{8}$'
          example: '03560902'
        image:
          type: string
          format: uri
          description: URL to the JPEG image of the Amiibo figure.
          example: 'https://raw.githubusercontent.com/N3evin/AmiiboAPI/master/images/icon_01000000-03560902.png'
        imgwebp:
          type: string
          format: uri
          description: URL to the WebP image of the Amiibo figure.
          example: 'https://raw.githubusercontent.com/N3evin/AmiiboAPI/master/images/icon_01000000-03560902.webp'
        name:
          type: string
          description: Display name of the Amiibo figure.
          example: 'Link'
        type:
          type: string
          description: >-
            Type classification of the Amiibo (e.g., Figure, Card, Yarn,
            Band).
          example: 'Figure'
        release:
          $ref: '#/components/schemas/AmiiboRelease'
      required:
        - amiiboSeries
        - character
        - gameSeries
        - head
        - tail
        - image
        - name
        - type
        - release
    GameEntry:
      type: object
      description: A game compatible with the Amiibo.
      properties:
        gameID:
          type: array
          description: List of title IDs for this game on the platform.
          items:
            type: string
          example:
            - '0004000000086300'
        gameName:
          type: string
          description: Name of the compatible game.
          example: 'The Legend of Zelda: Breath of the Wild'
    GameUsageEntry:
      type: object
      description: A game compatible with the Amiibo including usage information.
      properties:
        gameID:
          type: array
          description: List of title IDs for this game on the platform.
          items:
            type: string
        gameName:
          type: string
          description: Name of the compatible game.
        usage:
          type: array
          description: List of usage descriptions for this Amiibo in the game.
          items:
            type: object
            properties:
              Usage:
                type: string
                description: Description of how the Amiibo is used in this game.
              write:
                type: boolean
                description: Whether this Amiibo can be written to by this game.
    AmiiboGames:
      type: object
      description: Compatible games organized by platform.
      properties:
        gamesSwitch:
          type: array
          description: Compatible Nintendo Switch games.
          items:
            $ref: '#/components/schemas/GameEntry'
        games3DS:
          type: array
          description: Compatible Nintendo 3DS games.
          items:
            $ref: '#/components/schemas/GameEntry'
        gamesWiiU:
          type: array
          description: Compatible Wii U games.
          items:
            $ref: '#/components/schemas/GameEntry'
    AmiiboGamesWithUsage:
      type: object
      description: Compatible games with usage data organized by platform.
      properties:
        gamesSwitch:
          type: array
          description: Compatible Nintendo Switch games with usage info.
          items:
            $ref: '#/components/schemas/GameUsageEntry'
        games3DS:
          type: array
          description: Compatible Nintendo 3DS games with usage info.
          items:
            $ref: '#/components/schemas/GameUsageEntry'
        gamesWiiU:
          type: array
          description: Compatible Wii U games with usage info.
          items:
            $ref: '#/components/schemas/GameUsageEntry'
    AmiiboFull:
      allOf:
        - $ref: '#/components/schemas/Amiibo'
        - $ref: '#/components/schemas/AmiiboGamesWithUsage'
      description: Complete Amiibo data including game compatibility and usage information.
    AmiiboListResponse:
      type: object
      description: Response envelope for a list of Amiibo figures.
      properties:
        amiibo:
          type: array
          items:
            $ref: '#/components/schemas/Amiibo'
      required:
        - amiibo
    AmiiboFullListResponse:
      type: object
      description: Response envelope for a list of Amiibo figures with full game data.
      properties:
        amiibo:
          type: array
          items:
            $ref: '#/components/schemas/AmiiboFull'
      required:
        - amiibo
    ReferenceItem:
      type: object
      description: A reference data item with a hexadecimal key and name.
      properties:
        key:
          type: string
          description: Hexadecimal key identifier.
          example: '0x00'
        name:
          type: string
          description: Human-readable name.
          example: 'Figure'
      required:
        - key
        - name
    ReferenceListResponse:
      type: object
      description: Response envelope for a list of reference data items.
      properties:
        amiibo:
          type: array
          items:
            $ref: '#/components/schemas/ReferenceItem'
      required:
        - amiibo
    LastUpdatedResponse:
      type: object
      description: Response containing the last database update timestamp.
      properties:
        lastUpdated:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last database update.
          example: '2023-10-01T00:00:00+01:00'
      required:
        - lastUpdated
    ErrorResponse:
      type: object
      description: Error response body.
      properties:
        error:
          type: string
          description: Human-readable error message.
          example: 'Not Found: The requested URL was not found on the server.'
        code:
          type: integer
          description: HTTP status code.
          example: 404
      required:
        - error
        - code
  examples:
    AmiiboListExample:
      summary: List of Amiibo figures (basic)
      value:
        amiibo:
          - amiiboSeries: 'The Legend of Zelda'
            character: 'Link'
            gameSeries: 'The Legend of Zelda'
            head: '01000000'
            tail: '03560902'
            image: 'https://raw.githubusercontent.com/N3evin/AmiiboAPI/master/images/icon_01000000-03560902.png'
            imgwebp: 'https://raw.githubusercontent.com/N3evin/AmiiboAPI/master/images/icon_01000000-03560902.webp'
            name: 'Link'
            type: 'Figure'
            release:
              au: '2014-11-29'
              eu: '2014-11-28'
              jp: '2014-12-06'
              na: '2014-11-21'
    AmiiboWithGamesExample:
      summary: Amiibo with game compatibility data (showgames)
      value:
        amiibo:
          - amiiboSeries: 'The Legend of Zelda'
            character: 'Link'
            gameSeries: 'The Legend of Zelda'
            head: '01000000'
            tail: '03560902'
            image: 'https://raw.githubusercontent.com/N3evin/AmiiboAPI/master/images/icon_01000000-03560902.png'
            imgwebp: 'https://raw.githubusercontent.com/N3evin/AmiiboAPI/master/images/icon_01000000-03560902.webp'
            name: 'Link'
            type: 'Figure'
            release:
              au: '2014-11-29'
              eu: '2014-11-28'
              jp: '2014-12-06'
              na: '2014-11-21'
            gamesSwitch:
              - gameID:
                  - '01007EF00011E000'
                gameName: 'The Legend of Zelda: Breath of the Wild'
            games3DS:
              - gameID:
                  - '000400000018BF00'
                gameName: 'Hyrule Warriors Legends'
            gamesWiiU:
              - gameID:
                  - '0005000010145F00'
                gameName: 'Hyrule Warriors'
    TypeListExample:
      summary: List of Amiibo types
      value:
        amiibo:
          - key: '0x00'
            name: 'Figure'
          - key: '0x01'
            name: 'Card'
          - key: '0x02'
            name: 'Yarn'
          - key: '0x03'
            name: 'Band'
    LastUpdatedExample:
      summary: Last updated timestamp
      value:
        lastUpdated: '2023-10-01T00:00:00+01:00'