{
    "openapi": "3.0.3",
    "info": {
        "title": "TEZT Savollar API",
        "version": "1.0.0",
        "description": "YHQ (yo'l harakati qoidalari) imtihon savollari, biletlari va rasmlariga ochiq, faqat o'qish uchun API. Har so'rov `X-API-Key` sarlavhasi bilan."
    },
    "servers": [
        {
            "url": "https://prava.tezt.uz/api/v1"
        }
    ],
    "components": {
        "securitySchemes": {
            "ApiKey": {
                "type": "apiKey",
                "in": "header",
                "name": "X-API-Key"
            }
        },
        "schemas": {
            "Envelope": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "boolean"
                    },
                    "data": {
                        "type": "object"
                    },
                    "request_id": {
                        "type": "string"
                    }
                }
            },
            "Error": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "boolean",
                        "example": false
                    },
                    "error": {
                        "type": "object",
                        "properties": {
                            "code": {
                                "type": "string"
                            },
                            "message": {
                                "type": "string"
                            },
                            "retry_after": {
                                "type": "integer"
                            }
                        }
                    },
                    "request_id": {
                        "type": "string"
                    }
                }
            }
        }
    },
    "security": [
        {
            "ApiKey": []
        }
    ],
    "paths": {
        "/public/meta": {
            "get": {
                "operationId": "meta",
                "tags": [
                    "Umumiy"
                ],
                "summary": "Meta ma'lumot",
                "description": "Jami savollar/biletlar/mavzular soni, kontent versiyasi va oxirgi yangilanish vaqti. Mahalliy keshingiz yangimi, shuni bilish uchun `content_version` ni saqlang: o'zgarmagan bo'lsa, boshqa so'rov kerak emas. Kalitning o'z ruxsatlari va limitlari ham qaytadi.",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "ok": true,
                                    "data": {
                                        "api_version": 1,
                                        "content_version": "a91c0e44b2d7",
                                        "totals": {
                                            "questions": 1235,
                                            "tickets": 62,
                                            "topics": 15
                                        },
                                        "last_updated_ts": 1790000000,
                                        "last_updated_at": "2026-10-25T10:13:20+05:00",
                                        "server_time": 1790001234,
                                        "languages": [
                                            "uz_latn",
                                            "uz_cyrl"
                                        ],
                                        "difficulties": [
                                            "easy",
                                            "medium",
                                            "hard"
                                        ],
                                        "key": {
                                            "name": "Mening ilovam",
                                            "scopes": [
                                                "questions:read",
                                                "tickets:read"
                                            ],
                                            "rate_per_min": 60,
                                            "rate_per_day": 10000
                                        }
                                    },
                                    "request_id": "req_9f2c41d07a3b55e0"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Xato",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "ApiKey": []
                    }
                ]
            }
        },
        "/public/topics": {
            "get": {
                "operationId": "topics",
                "tags": [
                    "Mavzular va biletlar"
                ],
                "summary": "Mavzular (kategoriyalar)",
                "description": "Mavzular va ulardagi savollar soni. `key` ni boshqa endpointlarda `topic=` sifatida ishlating.",
                "parameters": [
                    {
                        "name": "lang",
                        "in": "query",
                        "required": false,
                        "description": "Javob yozuvi: `uz_latn` (lotin) yoki `uz_cyrl` (kirill). Kirillcha matn kiritilmagan joylar lotindan avtomatik o'giriladi.",
                        "schema": {
                            "type": "string",
                            "default": "uz_latn",
                            "enum": [
                                "uz_latn",
                                "uz_cyrl"
                            ]
                        }
                    },
                    {
                        "name": "fields",
                        "in": "query",
                        "required": false,
                        "description": "Faqat kerakli maydonlar, vergul bilan: `fields=id,text,options`. Javob hajmini kamaytiradi.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "ok": true,
                                    "data": {
                                        "items": [
                                            {
                                                "key": "chorraha",
                                                "name": "Chorrahalardan o'tish va navbat",
                                                "questions": 138
                                            },
                                            {
                                                "key": "svetofor",
                                                "name": "Svetofor va tartibga soluvchi",
                                                "questions": 74
                                            }
                                        ],
                                        "count": 15
                                    },
                                    "request_id": "req_9f2c41d07a3b55e0"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Xato",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "ApiKey": []
                    }
                ]
            }
        },
        "/public/tickets": {
            "get": {
                "operationId": "tickets",
                "tags": [
                    "Mavzular va biletlar"
                ],
                "summary": "Biletlar ro'yxati",
                "description": "`id` — barqaror ichki ID (bilet o'chirilsa ham boshqa bilet bu raqamni olmaydi), `number` — foydalanuvchiga ko'rsatiladigan ketma-ket raqam (1..N). Ko'rsatish uchun `number`, so'rovlarda `id` ishlating.",
                "parameters": [
                    {
                        "name": "fields",
                        "in": "query",
                        "required": false,
                        "description": "Faqat kerakli maydonlar, vergul bilan: `fields=id,text,options`. Javob hajmini kamaytiradi.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "ok": true,
                                    "data": {
                                        "items": [
                                            {
                                                "id": 1,
                                                "number": 1,
                                                "questions": 20,
                                                "updated_ts": 1790000000
                                            },
                                            {
                                                "id": 2,
                                                "number": 2,
                                                "questions": 20,
                                                "updated_ts": 1789000000
                                            }
                                        ],
                                        "count": 62
                                    },
                                    "request_id": "req_9f2c41d07a3b55e0"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Xato",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "ApiKey": []
                    }
                ]
            }
        },
        "/public/tickets/{id}": {
            "get": {
                "operationId": "ticket",
                "tags": [
                    "Mavzular va biletlar"
                ],
                "summary": "Bitta bilet va uning savollari",
                "description": "Bilet savollari `position` tartibida.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Bilet ID si (`/public/tickets` dagi `id`).",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "required": false,
                        "description": "Javob yozuvi: `uz_latn` (lotin) yoki `uz_cyrl` (kirill). Kirillcha matn kiritilmagan joylar lotindan avtomatik o'giriladi.",
                        "schema": {
                            "type": "string",
                            "default": "uz_latn",
                            "enum": [
                                "uz_latn",
                                "uz_cyrl"
                            ]
                        }
                    },
                    {
                        "name": "shuffle",
                        "in": "query",
                        "required": false,
                        "description": "`1` — javob variantlari tartibi aralashtiriladi. Har variantning `key` qiymati o'zgarmaydi (u variantning ID si; harfni o'zingiz ko'rsating).",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    },
                    {
                        "name": "seed",
                        "in": "query",
                        "required": false,
                        "description": "`shuffle=1` bilan: bir xil seed — har safar bir xil tartib (testni qayta ochganda).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "include_answers",
                        "in": "query",
                        "required": false,
                        "description": "`1` — `correct` (to'g'ri variant kalitlari) va `explanation` qo'shiladi. Kalitda `answers:read` ruxsati kerak, aks holda 403.",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    },
                    {
                        "name": "fields",
                        "in": "query",
                        "required": false,
                        "description": "Faqat kerakli maydonlar, vergul bilan: `fields=id,text,options`. Javob hajmini kamaytiradi.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "ok": true,
                                    "data": {
                                        "ticket": {
                                            "id": 1,
                                            "number": 1,
                                            "questions": 20
                                        },
                                        "items": [
                                            {
                                                "id": 1672,
                                                "ticket_id": 1,
                                                "ticket_number": 1,
                                                "position": 6,
                                                "topic": "chorraha",
                                                "topic_name": "Chorrahalardan o'tish va navbat",
                                                "difficulty": "medium",
                                                "type": "single",
                                                "text": "Qaysi transport vositasining haydovchisi chorrahadan birinchi bo'lib o'tadi?",
                                                "options": [
                                                    {
                                                        "key": "A",
                                                        "text": "Avtomobil va avtobus haydovchisi"
                                                    },
                                                    {
                                                        "key": "B",
                                                        "text": "Tramvay haydovchisi"
                                                    },
                                                    {
                                                        "key": "C",
                                                        "text": "Har ikkalasi"
                                                    }
                                                ],
                                                "image": {
                                                    "url": "https://DOMEN/api/v1/public/images/1672?v=01b03c9a1f&sig=4be0f3a1c2d9e711",
                                                    "thumb_url": "https://DOMEN/api/v1/public/images/1672?v=01b03c9a1f&sig=4be0f3a1c2d9e711&w=480&fmt=webp",
                                                    "source": "own"
                                                },
                                                "version": 2,
                                                "updated_ts": 1790000000
                                            }
                                        ],
                                        "count": 20,
                                        "content_version": "a91c0e44b2d7"
                                    },
                                    "request_id": "req_9f2c41d07a3b55e0"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Xato",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "ApiKey": []
                    }
                ]
            }
        },
        "/public/questions": {
            "get": {
                "operationId": "questions",
                "tags": [
                    "Savollar"
                ],
                "summary": "Savollar ro'yxati (filtr, sahifalash, delta-sinxron)",
                "description": "`id` bo'yicha tartiblangan, `cursor` bilan sahifalanadi. **Delta-sinxron:** birinchi marta to'liq yuklab oling va javobdagi `server_time` ni saqlang; keyingi safar `updated_since=<saqlangan server_time>` yuboring — faqat o'zgargan/yangi savollar `items` da, o'chirilgan yoki nofaol bo'lganlar `removed` da keladi (`removed` oxirgi sahifada to'liq bo'ladi).",
                "parameters": [
                    {
                        "name": "lang",
                        "in": "query",
                        "required": false,
                        "description": "Javob yozuvi: `uz_latn` (lotin) yoki `uz_cyrl` (kirill). Kirillcha matn kiritilmagan joylar lotindan avtomatik o'giriladi.",
                        "schema": {
                            "type": "string",
                            "default": "uz_latn",
                            "enum": [
                                "uz_latn",
                                "uz_cyrl"
                            ]
                        }
                    },
                    {
                        "name": "topic",
                        "in": "query",
                        "required": false,
                        "description": "Mavzu kaliti (`/public/topics` dan), masalan `chorraha`.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "difficulty",
                        "in": "query",
                        "required": false,
                        "description": "Qiyinlik: `easy`, `medium`, `hard`.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "easy",
                                "medium",
                                "hard"
                            ]
                        }
                    },
                    {
                        "name": "ticket",
                        "in": "query",
                        "required": false,
                        "description": "Bilet ID si (`/public/tickets` dagi `id`).",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Sahifadagi elementlar soni (1–100).",
                        "schema": {
                            "type": "integer",
                            "default": 50
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": false,
                        "description": "Oldingi javobdagi `next_cursor`. Bo'sh = birinchi sahifa.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "updated_since",
                        "in": "query",
                        "required": false,
                        "description": "UNIX vaqt (soniya). Shundan keyin o'zgargan savollar.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "ids",
                        "in": "query",
                        "required": false,
                        "description": "Vergul bilan ID lar (≤100): `ids=1,2,3`.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "shuffle",
                        "in": "query",
                        "required": false,
                        "description": "`1` — javob variantlari tartibi aralashtiriladi. Har variantning `key` qiymati o'zgarmaydi (u variantning ID si; harfni o'zingiz ko'rsating).",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    },
                    {
                        "name": "seed",
                        "in": "query",
                        "required": false,
                        "description": "`shuffle=1` bilan: bir xil seed — har safar bir xil tartib (testni qayta ochganda).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "include_answers",
                        "in": "query",
                        "required": false,
                        "description": "`1` — `correct` (to'g'ri variant kalitlari) va `explanation` qo'shiladi. Kalitda `answers:read` ruxsati kerak, aks holda 403.",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    },
                    {
                        "name": "fields",
                        "in": "query",
                        "required": false,
                        "description": "Faqat kerakli maydonlar, vergul bilan: `fields=id,text,options`. Javob hajmini kamaytiradi.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "ok": true,
                                    "data": {
                                        "items": [
                                            {
                                                "id": 1672,
                                                "ticket_id": 1,
                                                "ticket_number": 1,
                                                "position": 6,
                                                "topic": "chorraha",
                                                "topic_name": "Chorrahalardan o'tish va navbat",
                                                "difficulty": "medium",
                                                "type": "single",
                                                "text": "Qaysi transport vositasining haydovchisi chorrahadan birinchi bo'lib o'tadi?",
                                                "options": [
                                                    {
                                                        "key": "A",
                                                        "text": "Avtomobil va avtobus haydovchisi"
                                                    },
                                                    {
                                                        "key": "B",
                                                        "text": "Tramvay haydovchisi"
                                                    },
                                                    {
                                                        "key": "C",
                                                        "text": "Har ikkalasi"
                                                    }
                                                ],
                                                "image": {
                                                    "url": "https://DOMEN/api/v1/public/images/1672?v=01b03c9a1f&sig=4be0f3a1c2d9e711",
                                                    "thumb_url": "https://DOMEN/api/v1/public/images/1672?v=01b03c9a1f&sig=4be0f3a1c2d9e711&w=480&fmt=webp",
                                                    "source": "own"
                                                },
                                                "version": 2,
                                                "updated_ts": 1790000000
                                            }
                                        ],
                                        "count": 1,
                                        "next_cursor": "cNjQ5",
                                        "content_version": "a91c0e44b2d7",
                                        "server_time": 1790001234
                                    },
                                    "request_id": "req_9f2c41d07a3b55e0"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Xato",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "ApiKey": []
                    }
                ]
            }
        },
        "/public/questions/{id}": {
            "get": {
                "operationId": "question",
                "tags": [
                    "Savollar"
                ],
                "summary": "Bitta savol",
                "description": "To'g'ri javob bilan olish uchun kalitda `answers:read` va `include_answers=1` kerak.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Savol ID si.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "required": false,
                        "description": "Javob yozuvi: `uz_latn` (lotin) yoki `uz_cyrl` (kirill). Kirillcha matn kiritilmagan joylar lotindan avtomatik o'giriladi.",
                        "schema": {
                            "type": "string",
                            "default": "uz_latn",
                            "enum": [
                                "uz_latn",
                                "uz_cyrl"
                            ]
                        }
                    },
                    {
                        "name": "shuffle",
                        "in": "query",
                        "required": false,
                        "description": "`1` — javob variantlari tartibi aralashtiriladi. Har variantning `key` qiymati o'zgarmaydi (u variantning ID si; harfni o'zingiz ko'rsating).",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    },
                    {
                        "name": "seed",
                        "in": "query",
                        "required": false,
                        "description": "`shuffle=1` bilan: bir xil seed — har safar bir xil tartib (testni qayta ochganda).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "include_answers",
                        "in": "query",
                        "required": false,
                        "description": "`1` — `correct` (to'g'ri variant kalitlari) va `explanation` qo'shiladi. Kalitda `answers:read` ruxsati kerak, aks holda 403.",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    },
                    {
                        "name": "fields",
                        "in": "query",
                        "required": false,
                        "description": "Faqat kerakli maydonlar, vergul bilan: `fields=id,text,options`. Javob hajmini kamaytiradi.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "ok": true,
                                    "data": {
                                        "question": {
                                            "id": 1672,
                                            "ticket_id": 1,
                                            "ticket_number": 1,
                                            "position": 6,
                                            "topic": "chorraha",
                                            "topic_name": "Chorrahalardan o'tish va navbat",
                                            "difficulty": "medium",
                                            "type": "single",
                                            "text": "Qaysi transport vositasining haydovchisi chorrahadan birinchi bo'lib o'tadi?",
                                            "options": [
                                                {
                                                    "key": "A",
                                                    "text": "Avtomobil va avtobus haydovchisi"
                                                },
                                                {
                                                    "key": "B",
                                                    "text": "Tramvay haydovchisi"
                                                },
                                                {
                                                    "key": "C",
                                                    "text": "Har ikkalasi"
                                                }
                                            ],
                                            "image": {
                                                "url": "https://DOMEN/api/v1/public/images/1672?v=01b03c9a1f&sig=4be0f3a1c2d9e711",
                                                "thumb_url": "https://DOMEN/api/v1/public/images/1672?v=01b03c9a1f&sig=4be0f3a1c2d9e711&w=480&fmt=webp",
                                                "source": "own"
                                            },
                                            "version": 2,
                                            "updated_ts": 1790000000,
                                            "correct": [
                                                "B"
                                            ],
                                            "explanation": "Tramvay teng ahamiyatli chorrahada afzallikka ega."
                                        }
                                    },
                                    "request_id": "req_9f2c41d07a3b55e0"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Xato",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "ApiKey": []
                    }
                ]
            }
        },
        "/public/questions/random": {
            "get": {
                "operationId": "random",
                "tags": [
                    "Savollar"
                ],
                "summary": "Tasodifiy savollar",
                "description": "Filtrga mos savollardan tasodifiy tanlaydi (takrorlanmaydi). `exclude=1,2,3` — avval ko'rsatilganlarni chiqarib tashlaydi. Javob keshlanmaydi. `seed` bilan natija takrorlanadi.",
                "parameters": [
                    {
                        "name": "count",
                        "in": "query",
                        "required": false,
                        "description": "Savollar soni (1–50, standart 10).",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "topic",
                        "in": "query",
                        "required": false,
                        "description": "Mavzu kaliti (`/public/topics` dan), masalan `chorraha`.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "difficulty",
                        "in": "query",
                        "required": false,
                        "description": "Qiyinlik: `easy`, `medium`, `hard`.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "easy",
                                "medium",
                                "hard"
                            ]
                        }
                    },
                    {
                        "name": "ticket",
                        "in": "query",
                        "required": false,
                        "description": "Bilet ID si (`/public/tickets` dagi `id`).",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "exclude",
                        "in": "query",
                        "required": false,
                        "description": "Chiqarib tashlanadigan ID lar (≤200).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "required": false,
                        "description": "Javob yozuvi: `uz_latn` (lotin) yoki `uz_cyrl` (kirill). Kirillcha matn kiritilmagan joylar lotindan avtomatik o'giriladi.",
                        "schema": {
                            "type": "string",
                            "default": "uz_latn",
                            "enum": [
                                "uz_latn",
                                "uz_cyrl"
                            ]
                        }
                    },
                    {
                        "name": "shuffle",
                        "in": "query",
                        "required": false,
                        "description": "`1` — javob variantlari tartibi aralashtiriladi. Har variantning `key` qiymati o'zgarmaydi (u variantning ID si; harfni o'zingiz ko'rsating).",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    },
                    {
                        "name": "seed",
                        "in": "query",
                        "required": false,
                        "description": "`shuffle=1` bilan: bir xil seed — har safar bir xil tartib (testni qayta ochganda).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "include_answers",
                        "in": "query",
                        "required": false,
                        "description": "`1` — `correct` (to'g'ri variant kalitlari) va `explanation` qo'shiladi. Kalitda `answers:read` ruxsati kerak, aks holda 403.",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    },
                    {
                        "name": "fields",
                        "in": "query",
                        "required": false,
                        "description": "Faqat kerakli maydonlar, vergul bilan: `fields=id,text,options`. Javob hajmini kamaytiradi.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "ok": true,
                                    "data": {
                                        "items": [
                                            {
                                                "id": 1672,
                                                "ticket_id": 1,
                                                "ticket_number": 1,
                                                "position": 6,
                                                "topic": "chorraha",
                                                "topic_name": "Chorrahalardan o'tish va navbat",
                                                "difficulty": "medium",
                                                "type": "single",
                                                "text": "Qaysi transport vositasining haydovchisi chorrahadan birinchi bo'lib o'tadi?",
                                                "options": [
                                                    {
                                                        "key": "A",
                                                        "text": "Avtomobil va avtobus haydovchisi"
                                                    },
                                                    {
                                                        "key": "B",
                                                        "text": "Tramvay haydovchisi"
                                                    },
                                                    {
                                                        "key": "C",
                                                        "text": "Har ikkalasi"
                                                    }
                                                ],
                                                "image": {
                                                    "url": "https://DOMEN/api/v1/public/images/1672?v=01b03c9a1f&sig=4be0f3a1c2d9e711",
                                                    "thumb_url": "https://DOMEN/api/v1/public/images/1672?v=01b03c9a1f&sig=4be0f3a1c2d9e711&w=480&fmt=webp",
                                                    "source": "own"
                                                },
                                                "version": 2,
                                                "updated_ts": 1790000000
                                            }
                                        ],
                                        "count": 1,
                                        "pool": 74,
                                        "content_version": "a91c0e44b2d7"
                                    },
                                    "request_id": "req_9f2c41d07a3b55e0"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Xato",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "ApiKey": []
                    }
                ]
            }
        },
        "/public/search": {
            "get": {
                "operationId": "search",
                "tags": [
                    "Savollar"
                ],
                "summary": "Qidiruv",
                "description": "Savol va variantlar matni bo'yicha qidiradi (lotin ham, kirill ham; harf registri va `o'`/`oʻ` apostrof turlari farqsiz).",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "description": "Qidiruv matni (≥2 belgi).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "topic",
                        "in": "query",
                        "required": false,
                        "description": "Mavzu kaliti (`/public/topics` dan), masalan `chorraha`.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "difficulty",
                        "in": "query",
                        "required": false,
                        "description": "Qiyinlik: `easy`, `medium`, `hard`.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "easy",
                                "medium",
                                "hard"
                            ]
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Sahifadagi elementlar soni (1–100).",
                        "schema": {
                            "type": "integer",
                            "default": 50
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "required": false,
                        "description": "Javob yozuvi: `uz_latn` (lotin) yoki `uz_cyrl` (kirill). Kirillcha matn kiritilmagan joylar lotindan avtomatik o'giriladi.",
                        "schema": {
                            "type": "string",
                            "default": "uz_latn",
                            "enum": [
                                "uz_latn",
                                "uz_cyrl"
                            ]
                        }
                    },
                    {
                        "name": "include_answers",
                        "in": "query",
                        "required": false,
                        "description": "`1` — `correct` (to'g'ri variant kalitlari) va `explanation` qo'shiladi. Kalitda `answers:read` ruxsati kerak, aks holda 403.",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    },
                    {
                        "name": "fields",
                        "in": "query",
                        "required": false,
                        "description": "Faqat kerakli maydonlar, vergul bilan: `fields=id,text,options`. Javob hajmini kamaytiradi.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Muvaffaqiyatli",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                },
                                "example": {
                                    "ok": true,
                                    "data": {
                                        "query": "svetofor",
                                        "items": [
                                            {
                                                "id": 1672,
                                                "ticket_id": 1,
                                                "ticket_number": 1,
                                                "position": 6,
                                                "topic": "chorraha",
                                                "topic_name": "Chorrahalardan o'tish va navbat",
                                                "difficulty": "medium",
                                                "type": "single",
                                                "text": "Qaysi transport vositasining haydovchisi chorrahadan birinchi bo'lib o'tadi?",
                                                "options": [
                                                    {
                                                        "key": "A",
                                                        "text": "Avtomobil va avtobus haydovchisi"
                                                    },
                                                    {
                                                        "key": "B",
                                                        "text": "Tramvay haydovchisi"
                                                    },
                                                    {
                                                        "key": "C",
                                                        "text": "Har ikkalasi"
                                                    }
                                                ],
                                                "image": {
                                                    "url": "https://DOMEN/api/v1/public/images/1672?v=01b03c9a1f&sig=4be0f3a1c2d9e711",
                                                    "thumb_url": "https://DOMEN/api/v1/public/images/1672?v=01b03c9a1f&sig=4be0f3a1c2d9e711&w=480&fmt=webp",
                                                    "source": "own"
                                                },
                                                "version": 2,
                                                "updated_ts": 1790000000
                                            }
                                        ],
                                        "count": 1
                                    },
                                    "request_id": "req_9f2c41d07a3b55e0"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Xato",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "ApiKey": []
                    }
                ]
            }
        },
        "/public/images/{id}": {
            "get": {
                "operationId": "image",
                "tags": [
                    "Rasmlar"
                ],
                "summary": "Savol rasmi",
                "description": "Savol obyektidagi `image.url` imzolangan havola — uni to'g'ridan-to'g'ri `<img src>` ga qo'yish mumkin (kalit sarlavhasi kerak emas, `sig` o'zi ruxsat). Rasmlar `Cache-Control: public, max-age=31536000, immutable` bilan keladi; havoladagi `v` rasm o'zgarsa yangilanadi. Kichraytirish: `w` (160, 240, 320, 480, 640, 800, 960, 1280), format: `fmt` (webp, jpeg, png, orig). Rasmi yo'q savol — 404.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Savol ID si.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "v",
                        "in": "query",
                        "required": false,
                        "description": "Rasm versiyasi (havoladan).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "sig",
                        "in": "query",
                        "required": false,
                        "description": "Imzo (havoladan).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "w",
                        "in": "query",
                        "required": false,
                        "description": "Kenglik (px), ro'yxatdagi qiymatlardan.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "fmt",
                        "in": "query",
                        "required": false,
                        "description": "webp | jpeg | png | orig",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Rasm fayli",
                        "content": {
                            "image/*": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Xato",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "ApiKey": []
                    },
                    {}
                ]
            }
        }
    }
}