# ProSports Trivia Engine - API Integration Spec

## 1. Overview
The ProSports Trivia Engine generates factual multiple-choice trivia questions via a structured REST API.

- **Base URL:** http://geoplay-ai.547games.com:8005
- **Endpoint:** POST /api/v1/prosports/trivia
- **Spec Endpoint:** GET /api/v1/prosports/spec
- **Content-Type:** application/json
- **Authentication:** HTTP Bearer Token

---

## 2. Authentication
All requests require a static Bearer Token passed in the Authorization header:

    Authorization: Bearer prosports_sec_key_9f8d7c6b5a4e3d2c1

---

## 3. Request Schema

| Field | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| topic | string | Yes | - | Topic or prompt entered in UI. `subject` is supported as an alias. |
| num_questions | integer | No | 5 | Number of questions to generate (Min: 1, Max: 20) |
| difficulty | string | No | "Medium" | Target difficulty level: "Easy", "Medium", "Hard", or "Expert" |
| batch_id | string | No | null | Optional tracking/session ID. Auto-generated if omitted. |

### Request Payload Example:

    {
      "topic": "Austin Peay State University Football",
      "num_questions": 5,
      "difficulty": "Medium",
      "batch_id": "session_9942"
    }

---

## 4. Response Schema

| Field | Type | Description |
| :--- | :--- | :--- |
| status | string | Execution status ("success", "partial_success", or "error") |
| batch_id | string | Returns the provided batch_id or an auto-generated tracking string |
| topic | string | Echoes the input topic/prompt |
| difficulty | string | Echoes the difficulty level applied |
| total_generated | integer | Total questions returned in the array |
| questions | array | List of generated trivia question objects |

### Success Response Example (200 OK):

    {
      "status": "success",
      "batch_id": "session_9942",
      "topic": "Austin Peay State University Football",
      "difficulty": "Medium",
      "total_generated": 1,
      "questions": [
        {
          "id": 1,
          "question": "What is the name of the stadium where the Austin Peay football team plays home games?",
          "options": {
            "A": "The Stadium at Governors Stadium",
            "B": "Fortera Stadium",
            "C": "The Governors Gridiron",
            "D": "Murray Austin Stadium"
          },
          "correct_answer": "B",
          "explanation": "The Governors football team plays home games at Fortera Stadium in Clarksville, TN.",
          "verification_status": "verified",
          "verification_source": "Austin Peay State University Athletics",
          "verification_url": "https://www.apsu.edu/athletics",
          "verified_fact": "The team plays home games at Fortera Stadium.",
          "as_of_date": "2026-07-29"
        }
      ]
    }

---

## 5. Implementation Example (PHP)

    <?php
    $apiUrl = "http://geoplay-ai.547games.com:8005/api/v1/prosports/trivia";
    $apiKey = "prosports_sec_key_9f8d7c6b5a4e3d2c1";

    $payload = json_encode([
        "topic" => $_POST["topic"] ?? "Austin Peay State University Football",
        "num_questions" => intval($_POST["num_questions"] ?? 5),
        "difficulty" => $_POST["difficulty"] ?? "Medium",
        "batch_id" => "ui_request_" . time()
    ]);

    $ch = curl_init($apiUrl);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Content-Type: application/json",
        "Authorization: Bearer " . $apiKey
    ]);

    $response = curl_exec($ch);
    curl_close($ch);
    ?>