{
  "openapi": "3.0.3",
  "info": {
    "title": "ghostcompiler-api Reference Docs",
    "description": "Welcome to the Developer Currency API engine. Our platform serves high-performance cached currency metrics mapping 150+ international countries. Authenticate requests using your developer tokens via Bearer Authentication.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "http://localhost:8000",
      "description": "Local Development Server"
    }
  ],
  "paths": {
    "/api/v1/authorize": {
      "get": {
        "summary": "Authorize / Validate Token",
        "description": "Check if a developer API key is valid and active. Requires providing the token in the Bearer Token request header.",
        "operationId": "authorizeToken",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Token is valid and active.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Token is valid."
                    },
                    "name": {
                      "type": "string",
                      "example": "Production Key"
                    },
                    "default_currency": {
                      "type": "string",
                      "example": "INR"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token is invalid, deactivated, or not provided.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean",
                      "example": false
                    },
                    "message": {
                      "type": "string",
                      "example": "Token is invalid or expired."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1": {
      "get": {
        "summary": "Get Rates by Default Currency",
        "description": "Retrieve all active currency rates relative to the API token's default currency. If the token does not specify a default currency, the system fallback (INR) is automatically used.",
        "operationId": "getCurrencies",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved rates.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean",
                      "example": true
                    },
                    "disclaimer": {
                      "type": "string",
                      "example": "Usage subject to terms: http://localhost:8000/terms"
                    },
                    "license": {
                      "type": "string",
                      "example": "Usage subject to license: http://localhost:8000/license"
                    },
                    "timestamp": {
                      "type": "integer",
                      "example": 1717206400
                    },
                    "base": {
                      "type": "string",
                      "example": "INR"
                    },
                    "rates": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string",
                            "example": "USD"
                          },
                          "name": {
                            "type": "string",
                            "example": "United States Dollar"
                          },
                          "rate": {
                            "type": "number",
                            "format": "float",
                            "example": 0.01201923
                          },
                          "country": {
                            "type": "string",
                            "example": "United States, Ecuador, El Salvador, Panama, Zimbabwe"
                          },
                          "flag": {
                            "type": "string",
                            "example": "🇺🇸"
                          },
                          "flag_png": {
                            "type": "string",
                            "example": "https://flagcdn.com/w320/us.png"
                          },
                          "flag_svg": {
                            "type": "string",
                            "example": "https://flagcdn.com/us.svg"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean",
                      "example": false
                    },
                    "message": {
                      "type": "string",
                      "example": "Sorry, But you forgot to provide a token."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No active currency rates found.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean",
                      "example": false
                    },
                    "message": {
                      "type": "string",
                      "example": "No active currency rates found in system."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/{code}": {
      "get": {
        "summary": "Get Rates by Custom Base Currency",
        "description": "Retrieve all active currency rates relative to a specific base currency code passed in the request path.",
        "operationId": "getCurrenciesByCustomBase",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "The 3-letter target base currency code (case-insensitive).",
            "schema": {
              "type": "string",
              "example": "USD"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved rates relative to custom base.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean",
                      "example": true
                    },
                    "disclaimer": {
                      "type": "string",
                      "example": "Usage subject to terms: http://localhost:8000/terms"
                    },
                    "license": {
                      "type": "string",
                      "example": "Usage subject to license: http://localhost:8000/license"
                    },
                    "timestamp": {
                      "type": "integer",
                      "example": 1717206400
                    },
                    "base": {
                      "type": "string",
                      "example": "USD"
                    },
                    "rates": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string",
                            "example": "INR"
                          },
                          "name": {
                            "type": "string",
                            "example": "Indian Rupee"
                          },
                          "rate": {
                            "type": "number",
                            "format": "float",
                            "example": 83.25
                          },
                          "country": {
                            "type": "string",
                            "example": "India, Bhutan"
                          },
                          "flag": {
                            "type": "string",
                            "example": "🇮🇳"
                          },
                          "flag_png": {
                            "type": "string",
                            "example": "https://flagcdn.com/w320/in.png"
                          },
                          "flag_svg": {
                            "type": "string",
                            "example": "https://flagcdn.com/in.svg"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unsupported or inactive base currency code.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean",
                      "example": false
                    },
                    "message": {
                      "type": "string",
                      "example": "Currency code 'XYZ' is not supported or active."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean",
                      "example": false
                    },
                    "message": {
                      "type": "string",
                      "example": "Sorry, But your token is not valid or expired. Please request a new token or check your token."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/{from}/{to}": {
      "post": {
        "summary": "Convert Currency",
        "description": "Calculate and convert a specified amount from a source currency to a target currency using the live synced rates.",
        "operationId": "convertCurrency",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "path",
            "required": true,
            "description": "The 3-letter source currency code.",
            "schema": {
              "type": "string",
              "example": "EUR"
            }
          },
          {
            "name": "to",
            "in": "path",
            "required": true,
            "description": "The 3-letter target currency code.",
            "schema": {
              "type": "string",
              "example": "INR"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amount": {
                    "type": "number",
                    "format": "float",
                    "description": "The amount to convert. Defaults to 1.0 if not provided.",
                    "example": 100
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Conversion successfully calculated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean",
                      "example": true
                    },
                    "from": {
                      "type": "string",
                      "example": "EUR"
                    },
                    "to": {
                      "type": "string",
                      "example": "INR"
                    },
                    "amount": {
                      "type": "number",
                      "example": 100
                    },
                    "converted": {
                      "type": "number",
                      "example": 9043.4783
                    },
                    "rate": {
                      "type": "number",
                      "example": 90.434783
                    },
                    "timestamp": {
                      "type": "integer",
                      "example": 1717206400
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input parameters (e.g. amount <= 0, or unsupported currency codes).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean",
                      "example": false
                    },
                    "message": {
                      "type": "string",
                      "example": "Amount must be greater than zero."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean",
                      "example": false
                    },
                    "message": {
                      "type": "string",
                      "example": "Sorry, But you forgot to provide a token."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/countries": {
      "get": {
        "summary": "Get Countries",
        "description": "Get all supported countries.",
        "operationId": "getCountries",
        "responses": {
          "200": {
            "description": "List of countries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean",
                      "example": true
                    },
                    "countries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string",
                            "example": "India"
                          },
                          "iso_code": {
                            "type": "string",
                            "example": "IN"
                          },
                          "currency": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string",
                                "example": "Indian Rupee"
                              },
                              "code": {
                                "type": "string",
                                "example": "INR"
                              },
                              "symbol": {
                                "type": "string",
                                "example": "₹"
                              },
                              "flag": {
                                "type": "string",
                                "example": "🇮🇳"
                              },
                              "flag_png": {
                                "type": "string",
                                "example": "https://flagcdn.com/w320/in.png"
                              },
                              "flag_svg": {
                                "type": "string",
                                "example": "https://flagcdn.com/in.svg"
                              },
                              "rate": {
                                "type": "number",
                                "example": 83.2
                              },
                              "country": {
                                "type": "string",
                                "example": "India, Bhutan"
                              },
                              "active": {
                                "type": "boolean",
                                "example": true
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/countries/{code}/states": {
      "get": {
        "summary": "Get Country States",
        "description": "Get all states of a specific country code or name.",
        "operationId": "getCountryStates",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "IN"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of states.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean",
                      "example": true
                    },
                    "country_code": {
                      "type": "string",
                      "example": "IN"
                    },
                    "states": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string",
                            "example": "Andhra Pradesh"
                          },
                          "country": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string",
                                "example": "India"
                              },
                              "iso_code": {
                                "type": "string",
                                "example": "IN"
                              },
                              "currency": {
                                "type": "object",
                                "properties": {
                                  "name": {
                                    "type": "string",
                                    "example": "Indian Rupee"
                                  },
                                  "code": {
                                    "type": "string",
                                    "example": "INR"
                                  },
                                  "symbol": {
                                    "type": "string",
                                    "example": "₹"
                                  },
                                  "flag": {
                                    "type": "string",
                                    "example": "🇮🇳"
                                  },
                                  "flag_png": {
                                    "type": "string",
                                    "example": "https://flagcdn.com/w320/in.png"
                                  },
                                  "flag_svg": {
                                    "type": "string",
                                    "example": "https://flagcdn.com/in.svg"
                                  },
                                  "rate": {
                                    "type": "number",
                                    "example": 83.2
                                  },
                                  "country": {
                                    "type": "string",
                                    "example": "India, Bhutan"
                                  },
                                  "active": {
                                    "type": "boolean",
                                    "example": true
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/states/{name}/cities": {
      "get": {
        "summary": "Get State Cities",
        "description": "Get all cities of a specific state name.",
        "operationId": "getStateCities",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "Andhra Pradesh"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of cities.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean",
                      "example": true
                    },
                    "state_name": {
                      "type": "string",
                      "example": "Andhra Pradesh"
                    },
                    "cities": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string",
                            "example": "Hyderabad"
                          },
                          "state": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string",
                                "example": "Andhra Pradesh"
                              },
                              "country": {
                                "type": "object",
                                "properties": {
                                  "name": {
                                    "type": "string",
                                    "example": "India"
                                  },
                                  "iso_code": {
                                    "type": "string",
                                    "example": "IN"
                                  },
                                  "currency": {
                                    "type": "object",
                                    "properties": {
                                      "name": {
                                        "type": "string",
                                        "example": "Indian Rupee"
                                      },
                                      "code": {
                                        "type": "string",
                                        "example": "INR"
                                      },
                                      "symbol": {
                                        "type": "string",
                                        "example": "₹"
                                      },
                                      "flag": {
                                        "type": "string",
                                        "example": "🇮🇳"
                                      },
                                      "flag_png": {
                                        "type": "string",
                                        "example": "https://flagcdn.com/w320/in.png"
                                      },
                                      "flag_svg": {
                                        "type": "string",
                                        "example": "https://flagcdn.com/in.svg"
                                      },
                                      "rate": {
                                        "type": "number",
                                        "example": 83.2
                                      },
                                      "country": {
                                        "type": "string",
                                        "example": "India, Bhutan"
                                      },
                                      "active": {
                                        "type": "boolean",
                                        "example": true
                                      }
                                    }
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/all": {
      "get": {
        "summary": "Get Merged Geo and Currency Data",
        "description": "Get all countries, currencies, and their nested state/city lists.",
        "operationId": "getAllGeoMerged",
        "responses": {
          "200": {
            "description": "Merged data mapping countries to their currencies, active rates, and geographic hierarchies.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "object",
                    "properties": {
                      "currency": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string",
                            "example": "Indian Rupee"
                          },
                          "code": {
                            "type": "string",
                            "example": "INR"
                          },
                          "symbol": {
                            "type": "string",
                            "example": "₹"
                          },
                          "flag": {
                            "type": "string",
                            "example": "🇮🇳"
                          },
                          "flag_png": {
                            "type": "string",
                            "example": "https://flagcdn.com/w320/in.png"
                          },
                          "flag_svg": {
                            "type": "string",
                            "example": "https://flagcdn.com/in.svg"
                          },
                          "rate": {
                            "type": "number",
                            "example": 83.2
                          },
                          "country": {
                            "type": "string",
                            "example": "India, Bhutan"
                          },
                          "active": {
                            "type": "boolean",
                            "example": true
                          }
                        }
                      },
                      "states": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "example": "Hyderabad"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API token",
        "description": "Provide your developer key generated from the dashboard."
      }
    }
  }
}