Инструменты эндпоинтов

Инструменты эндпоинтов позволяют LLM просматривать API-эндпоинты на разных уровнях иерархии: все эндпоинты в спецификации, в коллекции, в теге или сводку одного эндпоинта. Используйте их для обнаружения доступных операций перед проверкой или вызовом.

---

endpoint_by_spec

Назначение

Список всех эндпоинтов во всей спецификации, охватывающий все коллекции и теги. Возвращает наиболее полное представление — каждый эндпоинт в спецификации с полным контекстом (тег, коллекция, спецификация).

Когда использовать

• Когда нужно увидеть каждый эндпоинт, доступный в спецификации
• Когда неизвестно, в какой коллекции или теге находится нужный эндпоинт
• После spec_by_id для получения полного списка эндпоинтов

Параметры

Параметр	Тип	Обязательный	Описание
specId	string	Да	32-символьный MD5-хеш спецификации

Ответ

{
  "endpoints": [
    {
      "id": "f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6",
      "tagId": "d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6",
      "tagName": "forecast",
      "collectionId": "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6",
      "collectionTitle": "Weather Forecast",
      "specId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "specDomain": "meteo",
      "method": "GET",
      "path": "/v1/forecast",
      "summary": "Get weather forecast for a location"
    }
  ]
}

Поле	Тип	Описание
id	string	Идентификатор эндпоинта
tagId	string	Идентификатор родительского тега
tagName	string	Человекочитаемое имя тега
collectionId	string	Идентификатор родительской коллекции
collectionTitle	string	Человекочитаемое название коллекции
specId	string	Идентификатор родительской спецификации
specDomain	string	Доменное имя спецификации
method	string	HTTP-метод (GET, POST, PUT, DELETE и т.д.)
path	string	Путь API (например, /v1/forecast)
summary	string	Человекочитаемое описание того, что делает эндпоинт

Нюансы

• Возвращает not_found, если спецификация не существует
• Каждый эндпоинт включает полную родословную (спецификация → коллекция → тег) для контекста
• Для быстрой сводки одного эндпоинта используйте endpoint_by_id

---

endpoint_by_collection

Назначение

Список всех эндпоинтов в конкретной коллекции, независимо от их тега. Возвращает эндпоинты, сгруппированные по коллекции, с метаданными спецификации и коллекции.

Когда использовать

• После collection_by_id для просмотра всех эндпоинтов в коллекции
• Когда нужно исследовать полную поверхность API коллекции

Параметры

Параметр	Тип	Обязательный	Описание
collectionId	string	Да	32-символьный MD5-хеш коллекции

Ответ

{
  "spec": {
    "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "domain": "meteo"
  },
  "collection": {
    "id": "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6",
    "title": "Weather Forecast",
    "countMethods": 12
  },
  "endpoints": [
    {
      "id": "f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6",
      "tagId": "d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6",
      "tagName": "forecast",
      "method": "GET",
      "path": "/v1/forecast",
      "summary": "Get weather forecast for a location"
    }
  ]
}

Нюансы

• Возвращает not_found, если коллекция не существует
• Включает метаданные спецификации и коллекции для контекста
• Эндпоинты из всех тегов внутри коллекции возвращаются вместе

---

endpoint_by_tag

Назначение

Список всех эндпоинтов, сгруппированных под конкретным тегом. Это наиболее сфокусированное представление — эндпоинты в одном теге внутри одной коллекции.

Когда использовать

• После tag_by_id для просмотра фактических эндпоинтов в теге
• Когда известен тег и нужно увидеть его операции

Параметры

Параметр	Тип	Обязательный	Описание
tagId	string	Да	32-символьный MD5-хеш тега

Ответ

{
  "spec": {
    "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "domain": "meteo"
  },
  "collection": {
    "id": "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6",
    "title": "Weather Forecast",
    "countMethods": 12
  },
  "tag": {
    "id": "d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6",
    "title": "forecast",
    "countMethods": 5
  },
  "endpoints": [
    {
      "id": "f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6",
      "method": "GET",
      "path": "/v1/forecast",
      "summary": "Get weather forecast for a location"
    }
  ]
}

Нюансы

• Возвращает not_found, если тег не существует
• Включает полный контекст: метаданные спецификации, коллекции и тега
• Эндпоинты ограничены одним тегом в одной коллекции

---

endpoint_by_id

Назначение

Получение быстрой сводки одного эндпоинта: метод, путь, описание и статус устаревания. Включает родительскую спецификацию, коллекцию и тег. Это лёгкий инструмент — для полного объекта OpenAPI-операции (параметры, тело запроса, схемы ответов) используйте inspect.

Когда использовать

• Когда есть ID эндпоинта и нужно быстро вспомнить, что он делает
• Перед решением, вызывать ли inspect для полных деталей
• Когда нужно подтвердить метод и путь перед вызовом

Параметры

Параметр	Тип	Обязательный	Описание
id	string	Да	32-символьный MD5-хеш эндпоинта

Ответ

{
  "spec": {
    "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "domain": "meteo"
  },
  "collection": {
    "id": "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6",
    "title": "Weather Forecast",
    "countMethods": 12
  },
  "tag": {
    "id": "d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6",
    "title": "forecast",
    "countMethods": 5
  },
  "endpoint": {
    "id": "f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6",
    "method": "GET",
    "path": "/v1/forecast",
    "summary": "Get weather forecast for a location"
  }
}

Поле	Тип	Описание
endpoint.id	string	Идентификатор эндпоинта
endpoint.method	string	HTTP-метод
endpoint.path	string	Путь API
endpoint.summary	string	Человекочитаемое описание

Нюансы

• Возвращает not_found, если эндпоинт не существует
• Это быстрая сводка — не возвращает параметры, тело запроса или схемы ответов
• Для полных технических деталей (требуются перед invoke) используйте inspect