{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent Ready Scan API",
    "version": "1.2.0",
    "description": "Сканирование сайта на готовность к ИИ-агентам по открытой шкале 0–4. Без авторизации, CORS открыт. Оператор: ООО «САРМАТЕХ», ИНН 4725011864. Сканирование не независимо и не является сертификацией. Цены и заказ работ — на https://aid2c.ru/. Лицензия описания и шкалы: CC BY 4.0.",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "email": "info@ai-d2c.ru",
      "url": "https://agentreadyscan.ru/"
    }
  },
  "servers": [
    {
      "url": "https://agentreadyscan.ru"
    }
  ],
  "paths": {
    "/api/v1/check": {
      "get": {
        "operationId": "checkSite",
        "summary": "Проверить сайт: уровень машиночитаемости 0–4 и список проверок",
        "description": "Запрашивает сайт по HTTP без выполнения JavaScript (~20 запросов, 5–45 с). Результат кэшируется 15 минут. Лимит — 12 новых проверок в час с одного IP; ответ из кэша лимит не расходует. Требования уровня зависят от группы сайта (levels.json, types); в ответе поля type, verdict и scale.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 300
            },
            "description": "Адрес сайта: домен или URL. Проверяется главная; если указан путь, он считается страницей товара.",
            "example": "albela.ru"
          },
          {
            "name": "product",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500
            },
            "description": "Страница товара на том же сайте — для проверки Product, Offer и таблицы характеристик."
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "auto",
                "goods",
                "services",
                "knowledge"
              ],
              "default": "auto"
            },
            "description": "Группа сайта: товары, услуги или знания. По умолчанию определяется автоматически; указанная группа «знания» отклоняется, если на сайте найдены цены, корзина или запись."
          }
        ],
        "responses": {
          "200": {
            "description": "Отчёт",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Report"
                }
              }
            }
          },
          "400": {
            "description": "Неверный адрес",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Превышен лимит; см. Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Проверяемый сайт не ответил",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Все места для сканирования заняты (не больше трёх одновременно). В теле busy: true, повторите через время из Retry-After."
          }
        }
      }
    },
    "/api/v1/type-report": {
      "post": {
        "operationId": "reportType",
        "summary": "Сообщить, что группа сайта определена неверно",
        "description": "Обращение уходит на ручную проверку. Почта необязательна; при её указании нужно согласие на обработку персональных данных.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "url",
                  "claimed"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "maxLength": 300
                  },
                  "claimed": {
                    "type": "string",
                    "enum": [
                      "goods",
                      "services",
                      "knowledge"
                    ]
                  },
                  "detected": {
                    "type": "string"
                  },
                  "declared": {
                    "type": "string"
                  },
                  "comment": {
                    "type": "string",
                    "maxLength": 1000
                  },
                  "email": {
                    "type": "string",
                    "maxLength": 160
                  },
                  "consent": {
                    "type": "string",
                    "enum": [
                      "1"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Обращение принято"
          },
          "303": {
            "description": "Для формы на странице отчёта: переход к отчёту, пересчитанному с указанной группой"
          },
          "400": {
            "description": "Неверные данные"
          },
          "429": {
            "description": "Лимит обращений"
          }
        }
      }
    },
    "/api/v1/site": {
      "get": {
        "operationId": "getSite",
        "summary": "Последний результат сканирования по домену",
        "description": "Отдаёт сохранённый результат и историю уровней. Сканирование не запускает.",
        "parameters": [
          {
            "name": "d",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Домен, например zavod.ru"
          }
        ],
        "responses": {
          "200": {
            "description": "Результат найден"
          },
          "400": {
            "description": "Параметр d не домен"
          },
          "404": {
            "description": "Домен ещё не сканировался"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "string"
          },
          "retry_after": {
            "type": "integer"
          }
        }
      },
      "Check": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "s.waf"
          },
          "group": {
            "type": "string",
            "enum": [
              "server",
              "files",
              "html",
              "jsonld",
              "api",
              "trust"
            ]
          },
          "title": {
            "type": "string"
          },
          "prio": {
            "type": "string",
            "enum": [
              "crit",
              "high",
              "med"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pass",
              "warn",
              "fail",
              "na"
            ]
          },
          "detail": {
            "type": "string"
          },
          "fix": {
            "type": "string"
          }
        }
      },
      "Report": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "url": {
            "type": "string"
          },
          "final_url": {
            "type": "string"
          },
          "product_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "checked_at": {
            "type": "string",
            "format": "date-time"
          },
          "level": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4,
            "description": "Шкала — https://agentreadyscan.ru/levels.json"
          },
          "next_level": {
            "type": [
              "integer",
              "null"
            ]
          },
          "blockers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "id проверок, которые мешают следующему уровню"
          },
          "summary": {
            "type": "object",
            "properties": {
              "crit": {
                "type": "integer"
              },
              "high": {
                "type": "integer"
              },
              "med": {
                "type": "integer"
              },
              "pass": {
                "type": "integer"
              },
              "total": {
                "type": "integer"
              }
            }
          },
          "checks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Check"
            }
          },
          "method_note": {
            "type": "string"
          },
          "cached": {
            "type": "boolean"
          },
          "report_url": {
            "type": "string"
          },
          "type": {
            "type": "object",
            "description": "Группа сайта и основание её определения",
            "properties": {
              "id": {
                "type": "string",
                "enum": [
                  "goods",
                  "services",
                  "knowledge",
                  "undetermined"
                ]
              },
              "name_ru": {
                "type": "string"
              },
              "declared": {
                "type": "string"
              },
              "detected": {
                "type": "string"
              },
              "basis": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "changed": {
                "type": "boolean"
              },
              "note": {
                "type": "string"
              },
              "pages_sampled": {
                "type": "integer"
              }
            }
          },
          "verdict": {
            "type": "object",
            "description": "Ответ на вопрос группы: что агент может сделать с сайтом",
            "properties": {
              "label": {
                "type": "string"
              },
              "answer": {
                "type": "string"
              },
              "text": {
                "type": "string"
              }
            }
          },
          "scale": {
            "type": "object",
            "properties": {
              "version": {
                "type": "string"
              },
              "ceiling": {
                "type": "integer",
                "description": "Максимальный уровень группы"
              },
              "calibration": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        }
      }
    }
  }
}