## ===----------------------------------------------------------------------===
## 
## 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.

        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 none, one or more amiibos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmiiboWrapper'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          description: Service is not available.
  /amiiboseries:
    get:
      tags:
        - Amiibo
      summary: Get the amiibo series.
      description: |
        Get a list of all the Amiibo series available in the database.

        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 key to include in the response.
      responses:
        '200':
          description: Successful response returning an object that contains one or more amiibo series.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmiiboSeriesWrapper'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          description: Service is not available.
  /character:
    get:
      tags:
        - Game
      summary: Get the game characters.
      description: |
        Get a list of all the game characters available in the database.

        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 key to include in the response.
        - $ref: '#/components/parameters/Name'
          description: A name of a game character key to include in the response.
      responses:
        '200':
          description: Successful response returning an object that contains one or more game characters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GameCharacterWrapper'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          description: Service is not available.
  /gameseries:
    get:
      tags:
        - Game
      summary: Get the game series.
      description: |
        Gets a list of all the Game series available in the database.

        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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GameSeriesWrapper'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          description: Service is not available.
  /type:
    get:
      tags:
        - Amiibo
      summary: Get the amiibo types.
      description: |
        Gets a list of all the amiibo types available in the database.

        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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmiiboTypeWrapper'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          description: Service is not available.
  /lastupdated:
    get:
      tags:
        - Service
      summary: Get the date of last updated.
      description: |
        Gets an ISO-formatted date+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 a date and time when the database was last updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LastUpdated'
        '500':
          description: Service is not available.
components:
  parameters:
    AmiiboSeries:
      description: An identifier or name of an amiibo series to include in the response
      name: amiiboSeries
      in: query
      required: false
      schema:
        type: string
    AmiiboType:
      description: An identifier or a name of an amiibo type to inclulde in the response.
      name: type
      in: query
      required: false
      schema:
        type: string
    GameCharacter:
      description: An identifier or name of a game character to include in the response.
      name: character
      in: query
      required: false
      schema:
        type: string
    GameSeries:
      description: An identifier or name of a game series to include in the response.
      name: gameseries
      in: query
      required: false
      schema:
        type: string
    Identifier:
      description: An identifier of an amiibo to include in the response.
      name: id
      in: query
      required: false
      schema:
        type: string
        maxLength: 18
    IdentifierHead:
      description: A first part for an identifier of an amiibo to include the response.
      name: head
      in: query
      required: false
      schema: 
        type: string
        maxLength: 10
    IdentifierTail:
      description: A last part for an identifier of an amiibo to include the response.
      name: tail
      in: query
      required: false
      schema: 
        type: string
        maxLength: 10
    Key:
      description: A key of a type to include in the response.
      name: key
      in: query
      required: false
      schema:
        type: string
    Name: 
      description: A name of a type to include in the response.
      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: One or more incorrect parameters have been sent.
      content: 
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceError'
    NotFound:
      description: No resource has been found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceError'
  schemas:
# Core Entities
    Amiibo:
      description: A type that represents an amiibo.
      type: object
      properties:
        amiiboSeries:
          description: A name of a series an amiibo belongs to.
          type: string
        character:
          description: |
            A name of a character of an amiibo.
            
            Multiple character have different amiibo design.
          type: string
        gameSeries:
          description: A name of a game series an amiibo belongs to.
          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: An image URL related to an amiibo.
          type: string
          format: uri
        name:
          description: A name of an Amiibo.
          type: string
        release:
          description: A type that contains the release dates of an amiibo, if any.
          $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: A name for the type an amiibo belongs to.
          type: string
      required:
        - amiiboSeries
        - character
        - gameSeries
        - head
        - image
        - name
        - release
        - tail
        - type
    AmiiboGame:
      description: A type that represents a game in which an amiibo is related to.
      type: object
      properties:
        amiiboUsage:
          description: A list of available usages an amiibo have in a game, if any.
          type: array
          items:
            $ref: '#/components/schemas/AmiiboUsage'
        gameID:
          description: A list of identifiers of a game an amiibo is related to.
          type: array
          items:
            type: string
        gameName:
          description: A name of a game an amiibo is related to.
          type: string
      required:
        - gameID
        - gameName
    AmiiboRelease:
      description: A type that contains the release dates of an amiibo throughout the world.
      type: object
      properties:
        au:
          description: A release date for Australia, if any.
          type: string
          format: date-time
        eu:
          description: A release date for Europe, if any.
          type: string
          format: date-time
        jp:
          description: A release date for Japan, if any.
          type: string
          format: date-time
        na:
          description: A release date for North America, if any.
          type: string
          format: date-time
    AmiiboSeries:
      description: A type that represents an amiibo series.
      allOf:
        - $ref: '#/components/schemas/Tuple'
        - type: object
          properties:
            key:
              description: A key of an amiibo series.
            name: 
              description: A name of an amiibo series.
    AmiiboType:
      description: A type that represents an amiibo type.
      allOf:
        - $ref: '#/components/schemas/Tuple'
        - type: object
          properties:
            key:
              description: A key of an amiibo type.
            name: 
              description: A name of an amiibo type.
    AmiiboUsage:
      description: A type that represents a use of an amiibo in a game.
      type: object
      properties:
        Usage:
          description: An explanation of the usage of an amiibo in a game.
          type: string
        write:
          description: A flag that indicates whether the data in an amiibo is writable or not.
          type: boolean
      required:
        - Usage
        - write
    GameCharacter:
      description: A type that represents a game character.
      allOf:
        - $ref: '#/components/schemas/Tuple'
        - type: object
          properties:
            key:
              description: A key of a game character.
            name: 
              description: A name of a game character.
    GameSeries:
      description: A type that represents a game series.
      allOf:
        - $ref: '#/components/schemas/Tuple'
        - type: object
          properties:
            key:
              description: A key of a game series.
            name: 
              description: A name of a game series.
    LastUpdated:
      description: A type that informs when the data in the service 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 type that is conformed only by the `key` and `name` properties.
        
        This type represents either `AmiiboSeries`, `AmiiboType`, `GameCharacter`, and `GameSeries` types.
      type: object
      properties:
        key:
          description: A key assigned to a tuple.
          type: string
          pattern: "^0x[0-9a-fA-F]+$"
          minLength: 3
        name:
          description: A name assigned to a tuple.
          type: string
      required:
        - key
        - name
# Wrapper Entities
    AmiiboWrapper:
      description: A type that wraps either none, one or a list of amiibos.
      type: object
      properties:
        amiibo: 
          description: A container that have 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 type that wraps either one or a list of amiibo series.
      type: object
      properties:
        amiibo: 
          description: A container that have 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 type that wraps either one or a list of amiibo types.
      type: object
      properties:
        amiibo: 
          description: A container that have 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 type that wraps either one or a list of game characters.
      type: object
      properties:
        amiibo: 
          description: A container that have 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 type that wraps either one or a list of game series.
      type: object
      properties:
        amiibo: 
          description: A container that have 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 provided by the service.
      type: object
      properties:
        code:
          description: A number of an error code.
          type: integer
        error:
          description: An explanation of an error.
          type: string
      required:
        - code
        - error