{"openapi": "3.0.3", "info": {"title": "Team Shuffle API", "version": "1.0.0", "description": "Split players into balanced teams so everyone plays with everyone equally often."}, "paths": {"/api/shuffle": {"post": {"summary": "Shuffle players into teams", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["players", "teams"], "properties": {"players": {"type": "array", "items": {"type": "string"}, "description": "Players this round"}, "teams": {"type": "integer", "minimum": 1, "description": "Number of teams"}, "history": {"description": "How many times each pair has played on the same team. Dense (players + matrix) or sparse (pairs).", "oneOf": [{"type": "object", "required": ["players", "matrix"], "properties": {"players": {"type": "array", "items": {"type": "string"}}, "matrix": {"type": "array", "items": {"type": "array", "items": {"type": "number", "minimum": 0}}}}}, {"type": "object", "required": ["pairs"], "properties": {"pairs": {"type": "object", "additionalProperties": {"type": "object", "additionalProperties": {"type": "number", "minimum": 0}}}}}]}, "seed": {"type": "integer", "description": "Optional, for reproducible results"}}}, "example": {"players": ["Ann", "Bob", "Cy", "Dee"], "teams": 2, "history": {"players": ["Ann", "Bob", "Cy", "Dee"], "matrix": [[0, 3, 0, 1], [3, 0, 1, 0], [0, 1, 0, 2], [1, 0, 2, 0]]}}}}}, "responses": {"200": {"description": "The teams, plus the history matrix updated with this round", "content": {"application/json": {"schema": {"type": "object", "properties": {"teams": {"type": "array", "items": {"type": "array", "items": {"type": "string"}}}, "cost": {"type": "number", "description": "Sum of past together-counts over same-team pairs (lower is better)"}, "team_costs": {"type": "array", "items": {"type": "number"}}, "max_repeat": {"type": "number", "description": "Highest past together-count among any same-team pair"}, "history": {"type": "object", "required": ["players", "matrix"], "properties": {"players": {"type": "array", "items": {"type": "string"}}, "matrix": {"type": "array", "items": {"type": "array", "items": {"type": "number", "minimum": 0}}}}}, "warnings": {"type": "array", "items": {"type": "string"}}, "stats": {"type": "object"}}}}}}, "400": {"description": "Invalid input", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}, "/api/health": {"get": {"summary": "Health check", "responses": {"200": {"description": "OK"}}}}}}