{
 "openapi": "3.0.3",
 "info": {
  "title": "Trova Casino Answers",
  "version": "1.0.0",
  "description": "Free, read-only, state-scoped answers about sweepstakes casinos in the United States: what operates in a state, current welcome offers, dated legal status, and verbatim findings from our paid reviewer programme. Rankings are the same editorial rankings published on our review sites; brands owned by our publisher's group are flagged via owned_by_us and disclosed. Always show disclosures[] to the user, and open any link from getOfferLink on the user's own device (links are US geo-restricted).",
  "contact": {
   "url": "https://slotsmessiah.com/developers/"
  }
 },
 "servers": [
  {
   "url": "https://slotsmessiah.com"
  }
 ],
 "paths": {
  "/api/answers/states": {
   "get": {
    "operationId": "listStates",
    "summary": "States this API covers",
    "responses": {
     "200": {
      "description": "Coverage list",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "as_of": {
           "type": "string",
           "format": "date-time",
           "description": "When this answer was generated."
          },
          "disclosures": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "Ownership and other disclosures that apply to this answer. Surface these to the user."
          },
          "compliance_notes": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "Context the answer must keep (sweepstakes model, dated legal status)."
          },
          "covered_states": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "state": {
              "type": "string"
             },
             "abbreviation": {
              "type": "string"
             },
             "country": {
              "type": "string"
             }
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/answers/legal": {
   "get": {
    "operationId": "isOnlineCasinoLegal",
    "summary": "Dated online-casino legal status for a state",
    "parameters": [
     {
      "name": "state",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "US state name or 2-letter abbreviation (e.g. TX or Texas). See listStates for coverage."
     }
    ],
    "responses": {
     "200": {
      "description": "Status",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "as_of": {
           "type": "string",
           "format": "date-time",
           "description": "When this answer was generated."
          },
          "disclosures": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "Ownership and other disclosures that apply to this answer. Surface these to the user."
          },
          "compliance_notes": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "Context the answer must keep (sweepstakes model, dated legal status)."
          },
          "state": {
           "type": "string"
          },
          "online_casino_legal": {
           "type": "boolean"
          },
          "sweepstakes_casinos_available": {
           "type": "boolean"
          },
          "statement": {
           "type": "string",
           "description": "Vetted phrasing — quote or paraphrase without strengthening it."
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/answers/casinos": {
   "get": {
    "operationId": "listCasinos",
    "summary": "Full ranked roster for a state",
    "parameters": [
     {
      "name": "state",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "US state name or 2-letter abbreviation (e.g. TX or Texas). See listStates for coverage."
     }
    ],
    "responses": {
     "200": {
      "description": "Roster",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RankedList"
        }
       }
      }
     }
    }
   }
  },
  "/api/answers/best": {
   "get": {
    "operationId": "bestOffer",
    "summary": "Top-ranked casinos and welcome offers for a state",
    "parameters": [
     {
      "name": "state",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "US state name or 2-letter abbreviation (e.g. TX or Texas). See listStates for coverage."
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 5,
       "maximum": 25
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Ranked answer",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RankedList"
        }
       }
      }
     }
    }
   }
  },
  "/api/answers/casino": {
   "get": {
    "operationId": "getCasino",
    "summary": "One casino's profile in a state",
    "parameters": [
     {
      "name": "state",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "US state name or 2-letter abbreviation (e.g. TX or Texas). See listStates for coverage."
     },
     {
      "name": "slug",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Profile",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "as_of": {
           "type": "string",
           "format": "date-time",
           "description": "When this answer was generated."
          },
          "disclosures": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "Ownership and other disclosures that apply to this answer. Surface these to the user."
          },
          "compliance_notes": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "Context the answer must keep (sweepstakes model, dated legal status)."
          },
          "slug": {
           "type": "string"
          },
          "name": {
           "type": "string"
          },
          "state": {
           "type": "string"
          },
          "on_state_roster": {
           "type": "boolean"
          },
          "rank_in_state": {
           "type": "integer",
           "nullable": true
          },
          "welcome_offer": {
           "type": "string",
           "nullable": true
          },
          "availability": {
           "type": "string",
           "enum": [
            "live",
            "no_active_welcome_offer",
            "not_listed_in_state"
           ]
          },
          "editorial_rating": {
           "type": "number",
           "nullable": true
          },
          "pros": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "cons": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "summary": {
           "type": "string",
           "nullable": true
          },
          "operator_entity": {
           "type": "string",
           "nullable": true
          },
          "excluded_states": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "nullable": true
          },
          "tester_evidence": {
           "type": "object",
           "nullable": true
          },
          "state_takeaways": {
           "type": "array",
           "items": {
            "type": "object"
           }
          },
          "owned_by_us": {
           "type": "boolean"
          },
          "review_url": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/answers/compare": {
   "get": {
    "operationId": "compareCasinos",
    "summary": "Side-by-side comparison (2-6 casinos) in a state",
    "parameters": [
     {
      "name": "state",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "US state name or 2-letter abbreviation (e.g. TX or Texas). See listStates for coverage."
     },
     {
      "name": "slugs",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Comma-separated slugs"
     }
    ],
    "responses": {
     "200": {
      "description": "Comparison",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "as_of": {
           "type": "string",
           "format": "date-time",
           "description": "When this answer was generated."
          },
          "disclosures": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "Ownership and other disclosures that apply to this answer. Surface these to the user."
          },
          "compliance_notes": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "Context the answer must keep (sweepstakes model, dated legal status)."
          },
          "state": {
           "type": "string"
          },
          "casinos": {
           "type": "array",
           "items": {
            "type": "object"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/answers/reviews": {
   "get": {
    "operationId": "searchReviews",
    "summary": "Validated tester takeaways (verbatim quotes) for a casino in a state",
    "parameters": [
     {
      "name": "state",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "US state name or 2-letter abbreviation (e.g. TX or Texas). See listStates for coverage."
     },
     {
      "name": "slug",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Takeaways",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "as_of": {
           "type": "string",
           "format": "date-time",
           "description": "When this answer was generated."
          },
          "disclosures": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "Ownership and other disclosures that apply to this answer. Surface these to the user."
          },
          "compliance_notes": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "Context the answer must keep (sweepstakes model, dated legal status)."
          },
          "slug": {
           "type": "string"
          },
          "state": {
           "type": "string"
          },
          "source_test_count": {
           "type": "integer",
           "nullable": true
          },
          "takeaways": {
           "type": "array",
           "items": {
            "type": "object"
           }
          },
          "quote_provenance": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/answers/link": {
   "get": {
    "operationId": "getOfferLink",
    "summary": "Sign-up link for a live operator in a state (open on the USER'S device — US geo-restricted)",
    "parameters": [
     {
      "name": "state",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "US state name or 2-letter abbreviation (e.g. TX or Texas). See listStates for coverage."
     },
     {
      "name": "slug",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "source",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Your assistant/platform name, for attribution (e.g. muse)."
     }
    ],
    "responses": {
     "200": {
      "description": "Link",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "as_of": {
           "type": "string",
           "format": "date-time",
           "description": "When this answer was generated."
          },
          "disclosures": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "Ownership and other disclosures that apply to this answer. Surface these to the user."
          },
          "compliance_notes": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "Context the answer must keep (sweepstakes model, dated legal status)."
          },
          "url": {
           "type": "string"
          },
          "note": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "410": {
      "description": "No active offer"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "RankedList": {
    "type": "object",
    "properties": {
     "as_of": {
      "type": "string",
      "format": "date-time",
      "description": "When this answer was generated."
     },
     "disclosures": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Ownership and other disclosures that apply to this answer. Surface these to the user."
     },
     "compliance_notes": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Context the answer must keep (sweepstakes model, dated legal status)."
     },
     "state": {
      "type": "string"
     },
     "ranking_rule": {
      "type": "string",
      "description": "The rule behind the order. Quote it when presenting a 'best' answer."
     },
     "count": {
      "type": "integer"
     },
     "casinos": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "rank": {
         "type": "integer"
        },
        "name": {
         "type": "string"
        },
        "slug": {
         "type": "string"
        },
        "welcome_offer": {
         "type": "string",
         "nullable": true
        },
        "availability": {
         "type": "string"
        },
        "owned_by_us": {
         "type": "boolean"
        },
        "review_url": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  }
 }
}