openapi: 3.0.0
info:
  title: Active8 Matchmaking API
  description: Core Engine API for the 'Uber of Padel' platform. Connects players based on Skill (ELO), Availability, and Location.
  version: 1.0.0
  contact:
    name: Active8 Dev Team
    email: admin@active8.com
servers:
  - url: https://api.active8.com/v1
    description: Production Server
  - url: http://localhost:888/active8/backend/api
    description: Local Development Engine

paths:
  /create_match.php:
    post:
      summary: Host a new match
      description: Creates an open match and triggers the Round Robin engine to find players.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                host_id:
                  type: integer
                  example: 15
                venue_id:
                  type: integer
                  example: 1
                start_time:
                  type: string
                  format: date-time
                  example: "2026-10-24 21:00:00"
                target_level:
                  type: number
                  format: float
                  example: 4.5
      responses:
        '200':
          description: Match created and engine triggered.
        '400':
          description: Missing parameters.

  /submit_score.php:
    post:
      summary: Submit Match Result
      description: Reports the final score of a match. Requires both teams to submit matching scores for verification.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                match_id:
                  type: integer
                  example: 10441
                reporter_id:
                  type: integer
                  example: 8
                team_a_score:
                  type: string
                  example: "6-4, 7-5"
                team_b_score:
                  type: string
                  example: "4-6, 5-7"
      responses:
        '200':
          description: Score submitted (Verified or Disputed state returned).

  /head_to_head.php:
    get:
      summary: View Head-to-Head Stats
      description: Returns analytic data comparing two players.
      parameters:
        - name: user_a
          in: query
          required: true
          schema:
            type: integer
        - name: user_b
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: H2H Stats Object

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []
