{"openapi":"3.1.0","info":{"title":"youring API","version":"1.0.0","summary":"Открытый JSON API кольца личных сайтов","description":"youring — кольцо личных сайтов. Публичное API без ключей: кольцо, соседи, случайный сайт, поиск, статистика и здоровье участников.","contact":{"name":"youring","url":"https://youring.roxera.net"},"license":{"name":"API open, code closed"}},"servers":[{"url":"https://youring.roxera.net"}],"tags":[{"name":"ring","description":"Кольцо и соседи"},{"name":"discovery","description":"Случайный сайт и поиск"},{"name":"stats","description":"Цифры и здоровье"},{"name":"widget","description":"Виджет, бейдж и редиректы"}],"paths":{"/api/v1/ring":{"get":{"tags":["ring"],"summary":"Всё кольцо","description":"Активные сайты в порядке кольца.","responses":{"200":{"description":"Список сайтов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ring"}}}}}}},"/api/v1/ring/{slug}":{"get":{"tags":["ring"],"summary":"Сайт и его соседи","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Сайт + prev/next","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Neighbourhood"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/ring/{slug}/{action}":{"get":{"tags":["ring"],"summary":"Сосед: next, prev или random","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"action","in":"path","required":true,"schema":{"type":"string","enum":["next","prev","random"]}}],"responses":{"200":{"description":"Соседний сайт"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/ring/opml":{"get":{"tags":["ring"],"summary":"OPML-бандл всех фидов","description":"OPML 2.0 со ссылками на RSS/Atom-фиды участников — одна подписка на всё кольцо.","responses":{"200":{"description":"OPML","content":{"text/x-opml":{}}}}}},"/api/v1/random":{"get":{"tags":["discovery"],"summary":"Случайный сайт","parameters":[{"name":"exclude","in":"query","schema":{"type":"string"},"description":"slug, который не нужно возвращать"},{"name":"kind","in":"query","schema":{"type":"string"},"description":"ограничить подкольцом по категории (kind)"}],"responses":{"200":{"description":"Случайный сайт"}}}},"/api/v1/search":{"get":{"tags":["discovery"],"summary":"Поиск по кольцу","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50}}],"responses":{"200":{"description":"Найденные сайты"}}}},"/api/v1/stats":{"get":{"tags":["stats"],"summary":"Цифры кольца","responses":{"200":{"description":"Участники, заявки, клики"}}}},"/api/v1/health":{"get":{"tags":["stats"],"summary":"Здоровье участников","description":"онлайн 40 + виджет 30 + ссылки 15 + профиль 15 → S...F.","responses":{"200":{"description":"Оценки по сайтам"}}}},"/{slug}":{"get":{"tags":["widget"],"summary":"Переход на сайт","description":"302 на сайт участника; считает переход.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"302":{"description":"Редирект на сайт"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/{slug}/{action}":{"get":{"tags":["widget"],"summary":"Переход к соседу","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"action","in":"path","required":true,"schema":{"type":"string","enum":["next","prev","random"]}}],"responses":{"302":{"description":"Редирект на соседний сайт"}}}},"/badge/{slug}.svg":{"get":{"tags":["widget"],"summary":"SVG-бейдж участника","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SVG","content":{"image/svg+xml":{}}}}}},"/widget.js":{"get":{"tags":["widget"],"summary":"JS-виджет","description":"Подключите: <script src=\"https://youring.roxera.net/widget.js\" async></script> и вставьте <youring-ring site=\"slug\"></youring-ring>","responses":{"200":{"description":"JavaScript","content":{"application/javascript":{}}}}}}},"components":{"responses":{"NotFound":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Site":{"type":"object","properties":{"slug":{"type":"string","example":"xxiivv"},"name":{"type":"string","example":"XXIIVV"},"url":{"type":"string","example":"https://xxiivv.com"},"host":{"type":"string","example":"xxiivv.com"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"kind":{"type":"string","example":"blog"},"nsfw":{"type":"boolean"},"position":{"type":"integer"},"icon":{"type":["string","null"]},"screenshot":{"type":["string","null"]},"color":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2},"clicks":{"type":"integer"},"health":{"type":"object","properties":{"status":{"type":"string"},"tier":{"type":"string"},"score":{"type":"integer"},"widget":{"type":"boolean"},"links":{"type":"boolean"}}},"added":{"type":["string","null"],"format":"date-time"}}},"Ring":{"type":"object","properties":{"ring":{"type":"string","const":"youring"},"count":{"type":"integer"},"generated":{"type":"string","format":"date-time"},"sites":{"type":"array","items":{"$ref":"#/components/schemas/Site"}}}},"Neighbourhood":{"type":"object","properties":{"site":{"$ref":"#/components/schemas/Site"},"index":{"type":"integer"},"total":{"type":"integer"},"prev":{"$ref":"#/components/schemas/Site"},"next":{"$ref":"#/components/schemas/Site"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}