{
  "openapi": "3.1.0",
  "info": {
    "title": "Polemia for assistants",
    "version": "1.0.0",
    "description": "Make free live phone quizzes on Polemia (https://polemia.ai) for your user, find ready-made ones, and read the question of the day. No key, no charge. Always give the user the links you get back. The same tools are offered over MCP at https://polemia.ai/mcp."
  },
  "servers": [
    {
      "url": "https://polemia.ai"
    }
  ],
  "paths": {
    "/api/polemia/agent/quiz": {
      "post": {
        "operationId": "createQuiz",
        "summary": "Make a new live quiz on a topic",
        "description": "Writes a new multiple-choice quiz (10 to 60 seconds) and returns join_url and code for the players and host_url for the person running the game (it makes the first browser that opens it the host, once). Always read `ok`: once writing starts the status is 200.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "topic": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 80,
                    "description": "What the quiz is about, e.g. \"volcanoes\"."
                  },
                  "questions": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 25,
                    "default": 10
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "facts",
                      "opinions"
                    ],
                    "default": "facts",
                    "description": "\"facts\" have right answers; \"opinions\" score the majority answer."
                  },
                  "language": {
                    "type": "string",
                    "description": "Write the quiz in this language. Leave out to use the topic's language."
                  },
                  "for_children_under": {
                    "type": "integer",
                    "minimum": 3,
                    "maximum": 17,
                    "description": "Keep every question suitable for children under this age."
                  }
                },
                "required": [
                  "topic"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The quiz, or an error object with ok=false if writing it failed or the topic was refused.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Quiz"
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many quizzes from this address; see retry_after_seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Quiz making is unavailable for now.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/polemia/agent/search": {
      "get": {
        "operationId": "findQuizzes",
        "summary": "Search the library of ready-made quizzes",
        "description": "Free and instant. Up to 10 public quizzes matching the query, each with a play_url where the user can start a live game.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60
            },
            "description": "A word or two about the topic."
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "BCP-47 language tag, e.g. \"en\", \"fr\", \"pt-BR\", \"ja\"."
            },
            "description": "Only quizzes in this language."
          }
        ],
        "responses": {
          "200": {
            "description": "Matching quizzes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Search"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/polemia/agent/daily": {
      "get": {
        "operationId": "dailyQuestion",
        "summary": "Today's question for the whole world",
        "description": "One opinion question a day, answered anonymously by people everywhere. The user votes at answer_url and then sees the results.",
        "parameters": [
          {
            "name": "language",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "BCP-47 language tag, e.g. \"en\", \"fr\", \"pt-BR\", \"ja\"."
            },
            "description": "Show the question in this language when a translation exists."
          }
        ],
        "responses": {
          "200": {
            "description": "Today's question.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Daily"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "string",
            "enum": [
              "invalid_input",
              "topic_refused",
              "rate_limited",
              "unavailable",
              "generation_failed"
            ]
          },
          "message": {
            "type": "string",
            "description": "What went wrong, in English, with what to do instead."
          },
          "retry_after_seconds": {
            "type": "integer"
          }
        },
        "required": [
          "ok",
          "error",
          "message"
        ]
      },
      "Quiz": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "code": {
            "type": "string",
            "description": "The join code players type at polemia.ai."
          },
          "join_url": {
            "type": "string",
            "format": "uri",
            "description": "For the players."
          },
          "host_url": {
            "type": "string",
            "format": "uri",
            "description": "For the person running the game; the first browser to open it becomes the host."
          },
          "qr_url": {
            "type": "string",
            "format": "uri",
            "description": "An SVG QR code of join_url."
          },
          "questions": {
            "type": "integer"
          },
          "kind": {
            "type": "string",
            "enum": [
              "facts",
              "opinions"
            ]
          },
          "language": {
            "type": "string"
          },
          "topic": {
            "type": "string"
          },
          "host_link_expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "An unopened game closes at this time."
          },
          "instructions": {
            "type": "string",
            "description": "A sentence or two to pass on to the user."
          }
        },
        "required": [
          "ok",
          "code",
          "join_url",
          "host_url",
          "qr_url",
          "questions",
          "kind",
          "language",
          "topic",
          "host_link_expires_at",
          "instructions"
        ]
      },
      "Search": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "total": {
            "type": "integer"
          },
          "quizzes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "questions": {
                  "type": "integer"
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "facts",
                    "opinions"
                  ]
                },
                "language": {
                  "type": "string"
                },
                "for_children_under": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "sample_question": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "play_url": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "required": [
                "title",
                "questions",
                "kind",
                "language",
                "play_url"
              ]
            }
          },
          "browse_url": {
            "type": "string",
            "format": "uri"
          },
          "instructions": {
            "type": "string"
          }
        },
        "required": [
          "ok",
          "total",
          "quizzes",
          "browse_url",
          "instructions"
        ]
      },
      "Daily": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "date": {
            "type": "string"
          },
          "question": {
            "type": [
              "string",
              "null"
            ]
          },
          "options": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "language": {
            "type": "string"
          },
          "answer_url": {
            "type": "string",
            "format": "uri"
          },
          "past_results_url": {
            "type": "string",
            "format": "uri"
          },
          "instructions": {
            "type": "string"
          }
        },
        "required": [
          "ok",
          "date",
          "question",
          "options",
          "language",
          "answer_url",
          "past_results_url",
          "instructions"
        ]
      }
    }
  }
}