Open API Specification

Open API schema (formerly Swagger)

openapi: 3.0.0
info:
  title: BAN Price API
  version: 1.0.0
  description: |
    Provides access to Magic: The Gathering card prices across various vendors,
    supporting multiple data formats and detailed filtering options.

servers:
  - url: https://www.mtgban.com/api/mtgban
    description: BAN Price API Server

paths:
  /{endpoint}/{id | SetCode}.json:
    get:
      summary: Fetch card pricing details
      description: |
        Retrieve prices and details for specific cards or editions in JSON format, 
        with options to change the output ID system and include authentication signature.
      parameters:
        - name: endpoint
          in: path
          required: true
          description: The API endpoint to access, such as 'retail', 'buylist', or 'all'.
          schema:
            type: string
        - name: id | SetCode
          in: path
          required: true
          description: The card ID or set code for fetching prices or edition snapshot.
          schema:
            type: string
        - name: id_option
          in: query
          required: false
          description: Option to change the output ID of returned card objects to a specific system.
          schema:
            type: string
            enum: [tcg, scryfall, mtgjson, mkm, ck, mtgban]
        - name: sig
          in: query
          required: true
          description: The signature for authenticating the request.
          schema:
            type: string
      responses:
        '200':
          description: Successful response in JSON format.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  meta:
                    type: object
                    properties:
                      date:
                        type: string
                      version:
                        type: string
                      base_url:
                        type: string
                  retail:
                    type: object
                    additionalProperties: 
                      type: object
                      additionalProperties: 
                        type: object
                        properties:
                          regular:
                            type: number
                            format: float
                          foil:
                            type: number
                            format: float
                          etched:
                            type: number
                            format: float
                          qty:
                            type: integer
                          qty_foil:
                            type: integer
                          qty_etched:
                            type: integer
                          conditions:
                            type: object
                            additionalProperties:
                              type: number
                              format: float
                  buylist:
                    type: object
                    additionalProperties: 
                      type: object
                      additionalProperties: 
                        type: object
                        properties:
                          regular:
                            type: number
                            format: float
                          foil:
                            type: number
                            format: float
                          etched:
                            type: number
                            format: float
                          qty:
                            type: integer
                          qty_foil:
                            type: integer
                          qty_etched:
                            type: integer
                          conditions:
                            type: object
                            additionalProperties:
                              type: number
                              format: float
        '301':
          description: Moved permanently - Request was made over an insecure channel, use https.
        '492':
          description: Too many requests - Perform fewer requests at the same time.
        '502':
          description: Bad gateway - Server bootstrap, try again later.
        '503':
          description: Service unavailable - Server loading, try again later.

components:
  schemas: {}
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: sig

security:
  - ApiKeyAuth: []