## ===----------------------------------------------------------------------===
## 
## This source file is part of the Amiibo Service open source project
## 
## Copyright (c) 2026 Röck+Cöde VoF. and the Amiibo Service project authors
## Licensed under Apache license v2.0
## 
## See LICENSE for license information
## See CONTRIBUTORS for the list of Amiibo Service project authors
##
## SPDX-License-Identifier: Apache-2.0
## 
## ===----------------------------------------------------------------------===

openapi: '3.1.1'
info:
  title: Amiibo API
  summary: A RESTFul API for Amiibo.
  description: |
    # Information

    The [AmiiboAPI](https://www.amiiboapi.org) service is primarily used for educational purposes.

    This is a **reading-only API**. Only HTTP GET method is allowed by this API.
    **No authentication** is required to use this API. All resources are allowed to access.
    If you are going to be calling this API regularly. We recommend that you use **caching** on your system.

    # Terms & Conditions

    By using our API, you hereby accepted the following terms and conditions:
    
    * *This API has no affiliation with Nintendo or any other companies that own the rights to it.*
    * *Other reports collected by the respective companies that own the rights are not our responsibility.*
    * *User agrees that the use of this API is entirely at user's own risks.*
    * *You will require your end users to comply with (and not knowingly enable them to violate) applicable law, regulation, and the Terms.*
    * *You will comply with all applicable law, regulation, and third party rights (including without limitation laws regarding the import or export of data or software, privacy, and local laws). You will not use the APIs to encourage or promote illegal activity or violation of third party rights.*
    * *These Terms and Conditions are subject to change without notice, from time to time in our sole discretion.*
  version: v1.0.0
  termsOfService: https://www.amiiboapi.org/docs/#termscondition
  contact:
    name: FAQ
    url: https://www.amiiboapi.org/faq/
  license:
    name: MIT license
    identifier: MIT
externalDocs:
  url: https://www.amiiboapi.org/docs
  description: Amiibo API documentation
servers:
  - url: https://www.amiiboapi.org/api
    description: Live service
tags:
  - name: Amiibo
    description: Amiibo-related endpoints.
  - name: Game
    description: Game-related endpoints.
  - name: Service
    description: Service-related endpoints.
paths:
  /amiibo:
    get:
      summary: Get a list of amiibos.
      description: |
        Get a list of all the amiibo items available in the database, optionally filtered by various criteria such as name, type, series, or game.

        Please refer to [the documentation of the endpoint](https://www.amiiboapi.org/docs/#amiibo) for further information.
      operationId: getAmiibos
      tags:
        - Amiibo
      parameters:
        - $ref: '#/components/parameters/Identifier'
        - $ref: '#/components/parameters/IdentifierHead'
        - $ref: '#/components/parameters/IdentifierTail'
        - $ref: '#/components/parameters/Name'
          description: A name of an amiibo to include in the response.
        - $ref: '#/components/parameters/AmiiboType'
        - $ref: '#/components/parameters/AmiiboSeries'
        - $ref: '#/components/parameters/GameCharacter'
        - $ref: '#/components/parameters/GameSeries'
        - $ref: '#/components/parameters/ShowGames'
        - $ref: '#/components/parameters/ShowUsage'
      responses:
        '200':
          description: Successful response returning an object that contains zero, one or more amiibos matching the filter criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmiiboWrapper'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          description: The service is currently unavailable.
  /amiiboseries:
    get:
      tags:
        - Amiibo
      summary: Get the amiibo series.
      description: |
        Get a list of all the amiibo series available in the database, optionally filtered by key or name.

        Please refer to [the documentation of the endpoint](https://www.amiiboapi.org/docs/#series) for further information.
      operationId: getAmiiboSeries
      parameters:
        - $ref: '#/components/parameters/Key'
          description: A key of an amiibo series to include in the response.
        - $ref: '#/components/parameters/Name'
          description: A name of an amiibo series to include in the response.
      responses:
        '200':
          description: Successful response returning an object that contains one or more amiibo series matching the filter criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmiiboSeriesWrapper'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          description: The service is currently unavailable.
  /character:
    get:
      tags:
        - Game
      summary: Get the game characters.
      description: |
        Get a list of all the game characters available in the database, optionally filtered by key or name.

        Please refer to [the documentation of the endpoint](https://www.amiiboapi.org/docs/#character) for further information.
      operationId: getGameCharacters
      parameters:
        - $ref: '#/components/parameters/Key'
          description: A key of a game character to include in the response.
        - $ref: '#/components/parameters/Name'
          description: A name of a game character to include in the response.
      responses:
        '200':
          description: Successful response returning an object that contains one or more game characters matching the filter criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GameCharacterWrapper'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          description: The service is currently unavailable.
  /gameseries:
    get:
      tags:
        - Game
      summary: Get the game series.
      description: |
        Get a list of all the game series available in the database, optionally filtered by key or name.

        Please refer to [the documentation of the endpoint](https://www.amiiboapi.org/docs/#gameSeries) for further information.
      operationId: getGameSeries
      parameters:
        - $ref: '#/components/parameters/Key'
          description: A key of a game series to include in the response.
        - $ref: '#/components/parameters/Name'
          description: A name of a game series to include in the response.
      responses:
        '200':
          description: Successful response returning an object that contains one or more game series matching the filter criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GameSeriesWrapper'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          description: The service is currently unavailable.
  /type:
    get:
      tags:
        - Amiibo
      summary: Get the amiibo types.
      description: |
        Get a list of all the amiibo types available in the database, optionally filtered by key or name.

        Please refer to [the documentation of the endpoint](https://www.amiiboapi.org/docs/#type) for further information.
      operationId: getAmiiboTypes
      parameters:
        - $ref: '#/components/parameters/Key'
          description: A key of an amiibo type to include in the response.
        - $ref: '#/components/parameters/Name'
          description: A name of an amiibo type to include in the response.
      responses:
        '200':
          description: Successful response returning an object that contains one or more amiibo types matching the filter criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmiiboTypeWrapper'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          description: The service is currently unavailable.
  /lastupdated:
    get:
      tags:
        - Service
      summary: Get the date when data was last updated.
      description: |
        Get an ISO-formatted date and time when the amiibo data was last updated.

        Please refer to [the documentation of the endpoint](https://www.amiiboapi.org/docs/#lastUpdated) for further information.
      operationId: getLastUpdated
      responses:
        '200':
          description: Successful response returning an object that contains the date and time when the database was last updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LastUpdated'
        '500':
          description: The service is currently unavailable.
components:
  parameters:
    AmiiboSeries:
      description: A hexadecimal key or name of an amiibo series to include in the response.
      name: amiiboSeries
      in: query
      required: false
      schema:
        type: string
    AmiiboType:
      description: A hexadecimal key or name of an amiibo type to include in the response.
      name: type
      in: query
      required: false
      schema:
        type: string
    GameCharacter:
      description: A hexadecimal key or name of a game character to include in the response.
      name: character
      in: query
      required: false
      schema:
        type: string
    GameSeries:
      description: A hexadecimal key or name of a game series to include in the response.
      name: gameseries
      in: query
      required: false
      schema:
        type: string
    Identifier:
      description: The full 16-character hexadecimal identifier of an amiibo to include in the response.
      name: id
      in: query
      required: false
      schema:
        type: string
        maxLength: 18
    IdentifierHead:
      description: The first 8 hexadecimal characters of an amiibo identifier to include in the response.
      name: head
      in: query
      required: false
      schema: 
        type: string
        maxLength: 10
    IdentifierTail:
      description: The last 8 hexadecimal characters of an amiibo identifier to include in the response.
      name: tail
      in: query
      required: false
      schema: 
        type: string
        maxLength: 10
    Key:
      description: A hexadecimal key to filter the results by.
      name: key
      in: query
      required: false
      schema:
        type: string
    Name: 
      description: A name to filter the results by.
      name: name
      in: query
      required: false
      schema:
        type: string
    ShowGames:
      description: A flag that indicates whether to include information about related games.
      name: showgames
      in: query
      required: false
      schema:
        type: boolean
    ShowUsage:
      description: A flag that indicates whether to include information about amiibo usages in related games.
      name: showusage
      in: query
      required: false
      schema:
        type: boolean
  responses:
    BadRequest:
      description: The request was malformed or contained invalid parameters.
      content: 
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceError'
    NotFound:
      description: No results were found matching the given filter criteria.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceError'
  schemas:
# Core Entities
    Amiibo:
      description: A type that represents an amiibo figurine, card, or other collectible.
      type: object
      properties:
        amiiboSeries:
          description: The name of the amiibo series this amiibo belongs to.
          type: string
        character:
          description: |
            The name of the game character associated with this amiibo.
            
            Multiple characters can have different amiibo designs.
          type: string
        gameSeries:
          description: The name of the game series associated with this amiibo.
          type: string
        games3DS:
          description: A list of 3DS games an amiibo could be used in, if any.
          type: array
          items:
            $ref: '#/components/schemas/AmiiboGame'
        gamesSwitch:
          description: A list of Switch games an amiibo could be used in, if any.
          type: array
          items:
            $ref: '#/components/schemas/AmiiboGame'
        gamesSwitch2:
          description: A list of Switch 2 games an amiibo could be used in, if any.
          type: array
          items:
            $ref: '#/components/schemas/AmiiboGame'
        gamesWiiU:
          description: A list of Wii U games an amiibo could be used in, if any.
          type: array
          items:
            $ref: '#/components/schemas/AmiiboGame'
        head:
          description: |
            The first 8 characters of the hexadecimal value that identifies an amiibo.

            The positions 0 to 7 of the hexadecimal string.
          type: string
          pattern: "^[0-9a-fA-F]+$"
          minLength: 8
          maxLength: 8
        image:
          description: A URL pointing to an image of this amiibo.
          type: string
          format: uri
        name:
          description: The name of this amiibo.
          type: string
        release:
          description: The regional release dates of this amiibo, if known.
          $ref: '#/components/schemas/AmiiboRelease'
        tail:
          description: |
            The last 8 characters of the hexadecimal value that identifies an amiibo.

            The positions 8 to 15 of the hexadecimal string.
          type: string
          pattern: "^[0-9a-fA-F]+$"
          minLength: 8
          maxLength: 8
        type:
          description: The type of this amiibo (e.g., Figure, Card, Yarn, Band).
          type: string
      required:
        - amiiboSeries
        - character
        - gameSeries
        - head
        - image
        - name
        - release
        - tail
        - type
    AmiiboGame:
      description: A type that represents a game in which an amiibo can be used.
      type: object
      properties:
        amiiboUsage:
          description: A list of available usages an amiibo has in a game, if any.
          type: array
          items:
            $ref: '#/components/schemas/AmiiboUsage'
        gameID:
          description: A list of identifiers for the game.
          type: array
          items:
            type: string
        gameName:
          description: The name of the game.
          type: string
      required:
        - gameID
        - gameName
    AmiiboRelease:
      description: A type that contains the regional release dates of an amiibo.
      type: object
      properties:
        au:
          description: The release date in Australia, if known.
          type: string
          format: date-time
        eu:
          description: The release date in Europe, if known.
          type: string
          format: date-time
        jp:
          description: The release date in Japan, if known.
          type: string
          format: date-time
        na:
          description: The release date in North America, if known.
          type: string
          format: date-time
    AmiiboSeries:
      description: A type that represents an amiibo series.
      allOf:
        - $ref: '#/components/schemas/Tuple'
        - type: object
          properties:
            key:
              description: The hexadecimal key that uniquely identifies this amiibo series.
            name: 
              description: The name of this amiibo series.
    AmiiboType:
      description: A type that represents an amiibo type (e.g., Figure, Card, Yarn, Band).
      allOf:
        - $ref: '#/components/schemas/Tuple'
        - type: object
          properties:
            key:
              description: The hexadecimal key that uniquely identifies this amiibo type.
            name: 
              description: The name of this amiibo type.
    AmiiboUsage:
      description: A type that represents how an amiibo is used within a game.
      type: object
      properties:
        Usage:
          description: A description of how the amiibo is used within the game.
          type: string
        write:
          description: A flag that indicates whether the amiibo can save game data.
          type: boolean
      required:
        - Usage
        - write
    GameCharacter:
      description: A type that represents a game character.
      allOf:
        - $ref: '#/components/schemas/Tuple'
        - type: object
          properties:
            key:
              description: The hexadecimal key that uniquely identifies this game character.
            name: 
              description: The name of this game character.
    GameSeries:
      description: A type that represents a game series.
      allOf:
        - $ref: '#/components/schemas/Tuple'
        - type: object
          properties:
            key:
              description: The hexadecimal key that uniquely identifies this game series.
            name: 
              description: The name of this game series.
    LastUpdated:
      description: A type that contains the date and time when the service data was last updated.
      type: object
      properties:
        lastUpdated:
          description: The date and time when the data in the database was last updated.
          type: string
          format: date-time
      required:
        - lastUpdated
    Tuple:
      description: |
        A base type composed of a `key` and `name` pair.
        
        This type is the base schema for the `AmiiboSeries`, `AmiiboType`, `GameCharacter`, and `GameSeries` types.
      type: object
      properties:
        key:
          description: A hexadecimal key that uniquely identifies this resource.
          type: string
          pattern: "^0x[0-9a-fA-F]+$"
          minLength: 3
        name:
          description: A display name for this resource.
          type: string
      required:
        - key
        - name
# Wrapper Entities
    AmiiboWrapper:
      description: A response wrapper that contains zero, one, or more amiibos.
      type: object
      properties:
        amiibo: 
          description: A container that holds zero, one or more amiibos.
          oneOf:
            - $ref: '#/components/schemas/Amiibo'
              description: A certain amiibo.
            - type: array
              description: A list that contains amiibos.
              items:
                $ref: '#/components/schemas/Amiibo'
    AmiiboSeriesWrapper:
      description: A response wrapper that contains one or more amiibo series.
      type: object
      properties:
        amiibo: 
          description: A container that holds one or more amiibo series.
          oneOf:
            - $ref: '#/components/schemas/AmiiboSeries'
              description: A certain amiibo series.
            - type: array
              description: A list that contains amiibo series.
              items:
                $ref: '#/components/schemas/AmiiboSeries'
      required: 
        - amiibo    
    AmiiboTypeWrapper:
      description: A response wrapper that contains one or more amiibo types.
      type: object
      properties:
        amiibo: 
          description: A container that holds one or more amiibo types.
          oneOf:
            - $ref: '#/components/schemas/AmiiboType'
              description: A certain amiibo type.
            - type: array
              description: A list that contains amiibo types.
              items:
                $ref: '#/components/schemas/AmiiboType'
      required: 
        - amiibo
    GameCharacterWrapper:
      description: A response wrapper that contains one or more game characters.
      type: object
      properties:
        amiibo: 
          description: A container that holds one or more game characters.
          oneOf:
            - $ref: '#/components/schemas/GameCharacter'
              description: A certain game character.
            - type: array
              description: A list that contains game characters.
              items:
                $ref: '#/components/schemas/GameCharacter'
      required: 
        - amiibo
    GameSeriesWrapper:
      description: A response wrapper that contains one or more game series.
      type: object
      properties:
        amiibo: 
          description: A container that holds one or more game series.
          oneOf:
            - $ref: '#/components/schemas/GameSeries'
              description: A certain game series.
            - type: array
              description: A list that contains game series.
              items:
                $ref: '#/components/schemas/GameSeries'
      required: 
        - amiibo
# Error Entities
    ServiceError:
      description: A type that represents an error response from the service.
      type: object
      properties:
        code:
          description: The HTTP status code of the error.
          type: integer
        error:
          description: A human-readable message describing the error.
          type: string
      required:
        - code
        - error