{
  "openapi": "3.0.3",
  "info": {
    "title": "CasinoRankr API",
    "description": "API for accessing community-ranked online casino data. Get information about sweepstakes casinos, crypto casinos, sportsbooks, and mystery box sites ranked by real player votes.",
    "version": "2.0.0",
    "contact": {
      "name": "CasinoRankr Support",
      "email": "contact@casinorankr.com",
      "url": "https://casinorankr.com"
    },
    "termsOfService": "https://casinorankr.com/terms-of-service",
    "license": {
      "name": "CasinoRankr API License",
      "url": "https://casinorankr.com/terms-of-service"
    }
  },
  "servers": [
    {
      "url": "https://casinorankr.com",
      "description": "Production server"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key for authentication (required for protected endpoints)"
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          },
          "statusCode": {
            "type": "integer",
            "description": "HTTP status code"
          }
        }
      },
      "Casino": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique casino identifier (slug)",
            "example": "chumba-casino"
          },
          "name": {
            "type": "string",
            "description": "Casino display name",
            "example": "Chumba Casino"
          },
          "casino_type": {
            "type": "string",
            "enum": [
              "sweepstakes",
              "crypto",
              "mystery",
              "sportsbooks"
            ],
            "description": "Casino category"
          },
          "rating": {
            "type": "number",
            "format": "float",
            "description": "Average rating from 1-5 based on community votes",
            "example": 4.2
          },
          "upvotes": {
            "type": "integer",
            "description": "Number of upvotes",
            "example": 1250
          },
          "downvotes": {
            "type": "integer",
            "description": "Number of downvotes",
            "example": 45
          },
          "total_votes": {
            "type": "integer",
            "description": "Total number of votes",
            "example": 1295
          },
          "bonus": {
            "type": "string",
            "description": "Current welcome bonus offer",
            "example": "2M Gold Coins + 2 Sweeps Coins FREE"
          },
          "logo": {
            "type": "string",
            "format": "uri",
            "description": "URL to casino logo image"
          },
          "review_summary": {
            "type": "string",
            "description": "Brief summary of the casino",
            "example": "Chumba Casino is one of the largest sweepstakes casinos with over 1 million players..."
          },
          "prohibited_states": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "US states where this casino is not available",
            "example": [
              "WA",
              "ID"
            ]
          },
          "is_new": {
            "type": "boolean",
            "description": "Whether this is a newly added casino",
            "example": false
          },
          "game_types": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Types of games available",
            "example": [
              "slots",
              "table games",
              "live dealer"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "casino_type",
          "rating"
        ]
      },
      "CitationResponse": {
        "type": "object",
        "properties": {
          "citation": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "type": {
                "type": "string",
                "enum": [
                  "review",
                  "category",
                  "guide",
                  "news"
                ]
              },
              "keyFacts": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "suggestedCitation": {
                "type": "string"
              }
            }
          },
          "casinoData": {
            "type": "object",
            "nullable": true,
            "properties": {
              "rating": {
                "type": "number"
              },
              "totalVotes": {
                "type": "integer"
              },
              "category": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "security": [],
  "paths": {
    "/api/casinos": {
      "get": {
        "operationId": "getCasinos",
        "summary": "Get casino listings",
        "description": "Retrieve a list of online casinos with their ratings, votes, and details. Can be filtered by category (sweepstakes, crypto, mystery, sportsbooks).",
        "parameters": [
          {
            "name": "casino_type",
            "in": "query",
            "description": "Casino category to filter by",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "sweepstakes",
                "crypto",
                "mystery",
                "sportsbooks"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "casinos": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Casino"
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total number of casinos in the category"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/casinos/{id}": {
      "get": {
        "operationId": "getCasinoById",
        "summary": "Get casino by ID",
        "description": "Retrieve detailed information about a specific casino by its ID",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Casino ID (slug)",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "chumba-casino"
          }
        ],
        "responses": {
          "200": {
            "description": "Casino details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Casino"
                }
              }
            }
          },
          "404": {
            "description": "Casino not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/casinos/state/{state}": {
      "get": {
        "operationId": "getCasinosByState",
        "summary": "Get casinos by state",
        "description": "Retrieve casinos available in a specific US state",
        "parameters": [
          {
            "name": "state",
            "in": "path",
            "description": "US state code (e.g., NY, CA, TX)",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{2}$"
            },
            "example": "NY"
          },
          {
            "name": "category",
            "in": "query",
            "description": "Casino category to filter by",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "sweepstakes",
                "crypto",
                "mystery",
                "sportsbooks"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Casinos available in state",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "casinos": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Casino"
                      }
                    },
                    "state": {
                      "type": "string",
                      "description": "State code"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/guides": {
      "get": {
        "operationId": "getGuides",
        "summary": "Get guides",
        "description": "Retrieve educational guides and tutorials",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "Guide category to filter by",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Guide listings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "guides": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string",
                            "description": "Guide slug"
                          },
                          "title": {
                            "type": "string",
                            "description": "Guide title"
                          },
                          "summary": {
                            "type": "string",
                            "description": "Guide summary"
                          },
                          "published_at": {
                            "type": "string",
                            "format": "date-time",
                            "description": "Publication date"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total number of guides"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/news": {
      "get": {
        "operationId": "getNews",
        "summary": "Get news articles",
        "description": "Retrieve latest news and industry updates",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "News category to filter by",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "News articles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "articles": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string",
                            "description": "Article slug"
                          },
                          "title": {
                            "type": "string",
                            "description": "Article title"
                          },
                          "summary": {
                            "type": "string",
                            "description": "Article summary"
                          },
                          "published_at": {
                            "type": "string",
                            "format": "date-time",
                            "description": "Publication date"
                          },
                          "category": {
                            "type": "string",
                            "description": "News category"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total number of articles"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "operationId": "searchCasinos",
        "summary": "Search casinos",
        "description": "Search for casinos by name or keywords",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2
            },
            "example": "chumba"
          },
          {
            "name": "category",
            "in": "query",
            "description": "Casino category to filter by",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "sweepstakes",
                "crypto",
                "mystery",
                "sportsbooks"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Casino"
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total number of results"
                    }
                  },
                  "example": {
                    "results": [
                      {
                        "id": "chumba-casino",
                        "name": "Chumba Casino",
                        "casino_type": "sweepstakes",
                        "rating": 4.2,
                        "upvotes": 1250,
                        "downvotes": 45,
                        "total_votes": 1295,
                        "bonus": "2M Gold Coins + 2 Sweeps Coins FREE"
                      }
                    ],
                    "total": 1
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid search query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/geo": {
      "get": {
        "operationId": "getGeoLocation",
        "summary": "Get user location",
        "description": "Detect user geographic location for displaying relevant casinos based on state/country restrictions",
        "responses": {
          "200": {
            "description": "Geographic location data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "country": {
                      "type": "string",
                      "description": "ISO country code (e.g., US, CA)",
                      "example": "US"
                    },
                    "region": {
                      "type": "string",
                      "description": "State or province code (e.g., NY, ON)",
                      "example": "NY"
                    },
                    "city": {
                      "type": "string",
                      "description": "City name",
                      "example": "New York"
                    }
                  },
                  "example": {
                    "country": "US",
                    "region": "NY",
                    "city": "New York"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/citations": {
      "get": {
        "operationId": "getCitation",
        "summary": "Get citation data for a page",
        "description": "Returns structured citation data for AI systems to properly attribute CasinoRankr content. Supports casino reviews and category pages.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "description": "Page path to get citation for (e.g., /reviews/chumba-casino)",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "/reviews/chumba-casino"
          },
          {
            "name": "type",
            "in": "query",
            "description": "Category type for category page citations",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "sweepstakes",
                "crypto",
                "mystery",
                "sportsbooks"
              ]
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Casino slug for review citations",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "chumba-casino"
          }
        ],
        "responses": {
          "200": {
            "description": "Citation data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "citation": {
                      "type": "object",
                      "properties": {
                        "title": {
                          "type": "string",
                          "description": "Page title"
                        },
                        "url": {
                          "type": "string",
                          "format": "uri",
                          "description": "Canonical URL"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "review",
                            "category",
                            "guide",
                            "news"
                          ]
                        },
                        "author": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "url": {
                              "type": "string"
                            },
                            "credentials": {
                              "type": "string"
                            }
                          }
                        },
                        "publisher": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "url": {
                              "type": "string"
                            }
                          }
                        },
                        "datePublished": {
                          "type": "string",
                          "format": "date"
                        },
                        "dateModified": {
                          "type": "string",
                          "format": "date"
                        },
                        "keyFacts": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "3-5 extractable factual statements"
                        },
                        "suggestedCitation": {
                          "type": "string",
                          "description": "Pre-formatted citation text"
                        }
                      }
                    },
                    "casinoData": {
                      "type": "object",
                      "description": "Present only for review/category citations",
                      "properties": {
                        "rating": {
                          "type": "number"
                        },
                        "totalVotes": {
                          "type": "integer"
                        },
                        "category": {
                          "type": "string"
                        },
                        "bonus": {
                          "type": "string",
                          "nullable": true
                        },
                        "verdict": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "CasinoRankr Documentation",
    "url": "https://casinorankr.com/llms.txt"
  }
}