{
  "openapi": "3.1.0",
  "info": {
    "title": "Subnet Checker API",
    "version": "1.0.0",
    "description": "Публичные каталоги IPv4 /24, история и точные пересечения с опубликованными БС. Примеры иллюстративные; текущие значения получайте запросом."
  },
  "servers": [
    {
      "url": "https://subnetchecker.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/keys": {
      "post": {
        "operationId": "keys",
        "summary": "Создать ключ",
        "description": "Без регистрации. Ключ показывается один раз; сохраните его в переменной окружения. Если запрос выполнен из авторизованной панели, ключ также появится в разделе API.",
        "parameters": [],
        "responses": {
          "201": {
            "description": "Успешный ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "key": {
                          "type": "string"
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "expires_at": {
                          "type": "string"
                        },
                        "limits": {
                          "type": "object",
                          "properties": {
                            "requests_per_minute": {
                              "type": "integer"
                            },
                            "requests_per_day": {
                              "type": "integer"
                            },
                            "checks_per_day": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "0e72fa768b13c941",
                    "name": "Мониторинг",
                    "key": "sc_live_EXAMPLE_REPLACE_WITH_YOUR_KEY",
                    "created_at": "2026-11-17T12:00:00Z",
                    "expires_at": "2026-12-17T12:00:00Z",
                    "limits": {
                      "requests_per_minute": 60,
                      "requests_per_day": 10000,
                      "checks_per_day": 20
                    }
                  },
                  "request_id": "a98c4b6d2e710f33"
                }
              }
            }
          },
          "400": {
            "description": "Некорректный запрос",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Неверный ключ",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Не найдено",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Неверный метод",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Неверный Content-Type",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Превышен лимит",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Ожидание в секундах"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Внутренняя ошибка",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80,
                    "default": "Моя интеграция"
                  },
                  "expires_in_days": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 365,
                    "default": 30
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/subnets": {
      "get": {
        "operationId": "subnets",
        "summary": "Каталог подсетей",
        "description": "Возвращает предложения из последних успешных снимков. Одна сеть у двух поставщиков — две записи. При ошибке источника сохраняется его предыдущий снимок; свежесть проверяйте через /v1/sources.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            },
            "description": "Размер страницы."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000000,
              "default": 0
            },
            "description": "Смещение."
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Точное имя поставщика, с учётом регистра."
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Двухбуквенный код страны из каталога, например US."
          },
          {
            "name": "prefix",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "95.21.145.0/24",
              "description": "Публичный IPv4 /24. Адрес сети, без host bits."
            },
            "description": "Точная подсеть /24."
          },
          {
            "name": "match",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "any",
                "full"
              ],
              "default": "all"
            },
            "description": "Все; хотя бы один IP в БС; все 256 IP."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "ip",
                "new",
                "price"
              ],
              "default": "ip"
            },
            "description": "По IPv4; новые первыми; валюта + цена без конвертации."
          },
          {
            "name": "max_age_days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 3650,
              "default": 30
            },
            "description": "Максимальный возраст публикации БС; 0 включает архивы и записи без даты."
          },
          {
            "name": "whitelist",
            "in": "query",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Точное имя из /v1/whitelists. Повторите параметр для нескольких источников."
          }
        ],
        "responses": {
          "200": {
            "description": "Успешный ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "prefix": {
                            "type": "string"
                          },
                          "source": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "country": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "currency": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "monthly_price_cents": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "setup_price_cents": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "deposit_cents": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "sample": {
                            "type": "boolean"
                          },
                          "first_seen_at": {
                            "type": "string"
                          },
                          "last_seen_at": {
                            "type": "string"
                          },
                          "whitelist": {
                            "type": "object",
                            "properties": {
                              "matched_ips": {
                                "type": "integer"
                              },
                              "total_ips": {
                                "type": "integer"
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "generated_at": {
                          "type": "string"
                        },
                        "max_age_days": {
                          "type": "integer"
                        },
                        "active_whitelists": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "prefix": "95.21.145.0/24",
                      "source": "ONIE",
                      "url": "https://onie.net/ru/ip-subnets",
                      "country": "US",
                      "currency": "USD",
                      "monthly_price_cents": 12029,
                      "setup_price_cents": 1149,
                      "deposit_cents": null,
                      "sample": false,
                      "first_seen_at": "2026-11-17T10:00:00Z",
                      "last_seen_at": "2026-11-17T10:05:00Z",
                      "whitelist": {
                        "matched_ips": 0,
                        "total_ips": 256
                      }
                    }
                  ],
                  "request_id": "a98c4b6d2e710f33",
                  "pagination": {
                    "limit": 1,
                    "offset": 0,
                    "total": 1183,
                    "next_offset": 1
                  },
                  "meta": {
                    "generated_at": "2026-11-17T12:00:00Z",
                    "max_age_days": 30,
                    "active_whitelists": [
                      "igareck endpoints /32 · конфигурации"
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "Некорректный запрос",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Неверный ключ",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Не найдено",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Неверный метод",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Неверный Content-Type",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Превышен лимит",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Ожидание в секундах"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Внутренняя ошибка",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/sources": {
      "get": {
        "operationId": "sources",
        "summary": "Поставщики",
        "description": "Каталоги с раскрытыми префиксами и счётчики без полных адресов. kind=counter не позволяет определить, какие именно сети доступны.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Успешный ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "checked_at": {
                            "type": "string"
                          },
                          "healthy": {
                            "type": "boolean"
                          },
                          "offers": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "name": "Neterra",
                      "kind": "prefixes",
                      "url": "https://client.neterra.cloud/index.php?/cart/ipv4-for-rent",
                      "checked_at": "2026-11-17T12:00:00Z",
                      "healthy": true,
                      "offers": 9
                    },
                    {
                      "name": "ACE · ARIN",
                      "kind": "counter",
                      "url": "https://aceips.com/whmcs/index.php?rp=/store/arin-ipv4",
                      "checked_at": "2026-11-17T12:00:00Z",
                      "count": 3
                    }
                  ],
                  "request_id": "a98c4b6d2e710f33"
                }
              }
            }
          },
          "400": {
            "description": "Некорректный запрос",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Неверный ключ",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Не найдено",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Неверный метод",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Неверный Content-Type",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Превышен лимит",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Ожидание в секундах"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Внутренняя ошибка",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/whitelists": {
      "get": {
        "operationId": "whitelists",
        "summary": "Источники БС",
        "description": "Метаданные всех подключённых списков. published_at — публикация источника, fetched_at — наша загрузка. Поле older_than_30_days также true, если дата публикации неизвестна.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Успешный ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "published_at": {
                            "type": "string"
                          },
                          "fetched_at": {
                            "type": "string"
                          },
                          "revision": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "ranges": {
                            "type": "integer"
                          },
                          "older_than_30_days": {
                            "type": "boolean"
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "name": "hxehex",
                      "published_at": "2026-05-09T00:00:00Z",
                      "fetched_at": "2026-11-17T12:00:00Z",
                      "revision": "example-revision",
                      "url": "https://github.com/hxehex/russia-mobile-internet-whitelist",
                      "ranges": 30222,
                      "older_than_30_days": true
                    }
                  ],
                  "request_id": "a98c4b6d2e710f33"
                }
              }
            }
          },
          "400": {
            "description": "Некорректный запрос",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Неверный ключ",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Не найдено",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Неверный метод",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Неверный Content-Type",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Превышен лимит",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Ожидание в секундах"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Внутренняя ошибка",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/matches": {
      "get": {
        "operationId": "matches",
        "summary": "Пересечение с БС",
        "description": "Точное количество IP выбранной /24, попавших в объединение подходящих списков. Один адрес считается один раз. /32 никогда не расширяется до /24.",
        "parameters": [
          {
            "name": "prefix",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "95.21.145.0/24",
              "description": "Публичный IPv4 /24. Адрес сети, без host bits."
            },
            "description": "Проверяемая сеть."
          },
          {
            "name": "max_age_days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 3650,
              "default": 30
            },
            "description": "Максимальный возраст публикации БС; 0 включает архивы и записи без даты."
          },
          {
            "name": "whitelist",
            "in": "query",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Точное имя из /v1/whitelists. Повторите параметр для нескольких источников."
          }
        ],
        "responses": {
          "200": {
            "description": "Успешный ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "prefix": {
                          "type": "string"
                        },
                        "covered": {
                          "type": "integer"
                        },
                        "ready": {
                          "type": "boolean"
                        },
                        "sources": {
                          "type": "array",
                          "items": {}
                        },
                        "max_age_days": {
                          "type": "integer"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "data": {
                    "prefix": "95.21.145.0/24",
                    "covered": 0,
                    "ready": true,
                    "sources": [],
                    "max_age_days": 30
                  },
                  "request_id": "a98c4b6d2e710f33"
                }
              }
            }
          },
          "400": {
            "description": "Некорректный запрос",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Неверный ключ",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Не найдено",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Неверный метод",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Неверный Content-Type",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Превышен лимит",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Ожидание в секундах"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Внутренняя ошибка",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/checks": {
      "post": {
        "operationId": "checks",
        "summary": "Запустить проверку",
        "description": "Асинхронно собирает регистрацию, BGP, передачи адресов и геолокацию. 202 означает постановку в очередь, а не завершение. Свежий кэш до 5 минут возвращает 200/state=cached. Дубликаты выполняющейся проверки не создают новое задание.",
        "parameters": [],
        "responses": {
          "202": {
            "description": "Успешный ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "prefix": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string"
                        },
                        "poll_url": {
                          "type": "string"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "data": {
                    "prefix": "95.21.145.0/24",
                    "state": "running",
                    "poll_url": "/v1/history?prefix=95.21.145.0%2F24"
                  },
                  "request_id": "a98c4b6d2e710f33"
                }
              }
            }
          },
          "200": {
            "description": "Свежий кэш",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "prefix": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Некорректный запрос",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Неверный ключ",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Не найдено",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Неверный метод",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Неверный Content-Type",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Превышен лимит",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Ожидание в секундах"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Внутренняя ошибка",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prefix": {
                    "type": "string",
                    "example": "95.21.145.0/24",
                    "description": "Публичный IPv4 /24. Адрес сети, без host bits."
                  }
                },
                "required": [
                  "prefix"
                ]
              }
            }
          }
        }
      }
    },
    "/v1/history": {
      "get": {
        "operationId": "history",
        "summary": "История и результат проверки",
        "description": "Читает сохранённое досье. Сам GET не запускает сетевую проверку. data=null и state=not_checked — результат пока не собран. Старый результат может присутствовать одновременно со state=running.",
        "parameters": [
          {
            "name": "prefix",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "95.21.145.0/24",
              "description": "Публичный IPv4 /24. Адрес сети, без host bits."
            },
            "description": "Проверяемая сеть."
          },
          {
            "name": "max_age_days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 3650,
              "default": 30
            },
            "description": "Максимальный возраст публикации БС; 0 включает архивы и записи без даты."
          },
          {
            "name": "whitelist",
            "in": "query",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Точное имя из /v1/whitelists. Повторите параметр для нескольких источников."
          }
        ],
        "responses": {
          "200": {
            "description": "Успешный ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "prefix": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string"
                        },
                        "updated_at": {
                          "type": "string"
                        },
                        "data": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "prefix": {
                              "type": "string"
                            },
                            "checked": {
                              "type": "integer"
                            },
                            "errors": {
                              "type": "array",
                              "items": {}
                            },
                            "registration": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "type": {
                                    "type": "string"
                                  },
                                  "key": {
                                    "type": "string"
                                  },
                                  "attributes": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "key": {
                                          "type": "string"
                                        },
                                        "value": {
                                          "type": "string"
                                        }
                                      }
                                    }
                                  }
                                }
                              }
                            },
                            "registry_resource": {
                              "type": "string"
                            },
                            "registry_type": {
                              "type": "string"
                            },
                            "versions": {
                              "type": "array",
                              "items": {}
                            },
                            "overview": {
                              "type": "object",
                              "properties": {
                                "asns": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "asn": {
                                        "type": "integer"
                                      },
                                      "holder": {
                                        "type": "string"
                                      }
                                    }
                                  }
                                },
                                "resource": {
                                  "type": "string"
                                }
                              }
                            },
                            "routes": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "asn": {
                                    "type": "string"
                                  },
                                  "holder": {
                                    "type": "string"
                                  },
                                  "prefix": {
                                    "type": "string"
                                  },
                                  "exact": {
                                    "type": "boolean"
                                  },
                                  "periods": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "start": {
                                          "type": "string"
                                        },
                                        "end": {
                                          "type": "string"
                                        }
                                      }
                                    }
                                  }
                                }
                              }
                            },
                            "transfers": {
                              "type": "array",
                              "items": {}
                            },
                            "geo": {
                              "type": "array",
                              "items": {}
                            },
                            "bs": {
                              "type": "object",
                              "properties": {
                                "covered": {
                                  "type": "integer"
                                },
                                "ready": {
                                  "type": "boolean"
                                },
                                "sources": {
                                  "type": "array",
                                  "items": {}
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "data": {
                    "prefix": "95.21.145.0/24",
                    "state": "cached",
                    "updated_at": "2026-11-17T12:00:00Z",
                    "data": {
                      "prefix": "95.21.145.0/24",
                      "checked": 1794916800,
                      "errors": [],
                      "registration": [
                        {
                          "type": "inetnum",
                          "key": "95.21.0.0 - 95.21.255.255",
                          "attributes": [
                            {
                              "key": "netname",
                              "value": "JAZZTEL-TRIPLEPLAY"
                            }
                          ]
                        }
                      ],
                      "registry_resource": "inetnum:95.21.0.0 - 95.21.255.255",
                      "registry_type": "inetnum",
                      "versions": [],
                      "overview": {
                        "asns": [
                          {
                            "asn": 12479,
                            "holder": "UNI2-AS Orange Espagne SA"
                          }
                        ],
                        "resource": "95.21.128.0/19"
                      },
                      "routes": [
                        {
                          "asn": "12715",
                          "holder": "JAZZTEL",
                          "prefix": "95.21.0.0/16",
                          "exact": false,
                          "periods": [
                            {
                              "start": "2010-01-19T00:00:00",
                              "end": "2018-06-29T00:00:00"
                            }
                          ]
                        }
                      ],
                      "transfers": [],
                      "geo": [],
                      "bs": {
                        "covered": 0,
                        "ready": true,
                        "sources": []
                      }
                    }
                  },
                  "request_id": "a98c4b6d2e710f33"
                }
              }
            }
          },
          "400": {
            "description": "Некорректный запрос",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Неверный ключ",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Не найдено",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Неверный метод",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Неверный Content-Type",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Превышен лимит",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Ожидание в секундах"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Внутренняя ошибка",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/key": {
      "get": {
        "operationId": "key",
        "summary": "Текущий ключ",
        "description": "Возвращает метаданные использованного ключа. Секрет повторно не возвращается.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Успешный ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "expires_at": {
                          "type": "string"
                        },
                        "last_used_at": {
                          "type": [
                            "string",
                            "number",
                            "object",
                            "array",
                            "null"
                          ]
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "0e72fa768b13c941",
                    "name": "Мониторинг",
                    "created_at": "2026-11-17T12:00:00Z",
                    "expires_at": "2026-12-17T12:00:00Z",
                    "last_used_at": null
                  },
                  "request_id": "a98c4b6d2e710f33"
                }
              }
            }
          },
          "400": {
            "description": "Некорректный запрос",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Неверный ключ",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Не найдено",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Неверный метод",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Неверный Content-Type",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Превышен лимит",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Ожидание в секундах"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Внутренняя ошибка",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "revoke",
        "summary": "Отозвать ключ",
        "description": "Немедленно отзывает ключ из Authorization. Следующий запрос с ним вернёт 401. Для ротации сначала создайте новый ключ, проверьте интеграцию, затем отзовите старый.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Успешный ответ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "revoked": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "data": {
                    "revoked": true
                  },
                  "request_id": "a98c4b6d2e710f33"
                }
              }
            }
          },
          "400": {
            "description": "Некорректный запрос",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Неверный ключ",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Не найдено",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Неверный метод",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Неверный Content-Type",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Превышен лимит",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              },
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Ожидание в секундах"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Внутренняя ошибка",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "Идентификатор запроса"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "sc_live_<secret>"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "request_id"
        ]
      }
    }
  }
}