{"openapi":"3.1.0","info":{"title":"RuForge API","version":"1.0.0","description":"REST API для диагностики управленческой зрелости и базы знаний RuForge.\n\nПолучить API-ключ: https://ruforge.ru/integrations","contact":{"email":"api@ruforge.ru","url":"https://ruforge.ru/integrations"},"license":{"name":"Проприетарная лицензия"}},"servers":[{"url":"https://lk.ruforge.ru","description":"Production"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"Bearer API ключ. Легаси-ключи: https://ruforge.ru/integrations. User-scoped ключи (для corporate): личный кабинет → API-ключи."}},"schemas":{"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"ownerUserId":{"type":"string"},"emailDomain":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Membership":{"type":"object","properties":{"id":{"type":"string"},"companyId":{"type":"string"},"userId":{"type":"string"},"role":{"type":"string","enum":["owner","hr_admin","manager","member"]},"managerUserId":{"type":"string","nullable":true},"joinedAt":{"type":"string","format":"date-time"},"leftAt":{"type":"string","format":"date-time","nullable":true},"sharedLastResultId":{"type":"string","nullable":true}}},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"companyId":{"type":"string"},"invitedEmail":{"type":"string","format":"email"},"invitedByUserId":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","expired","revoked"]},"createdAt":{"type":"string","format":"date-time"}}},"DashboardMember":{"type":"object","properties":{"userId":{"type":"string"},"membershipId":{"type":"string"},"name":{"type":"string","description":"PII-strip маска"},"email":{"type":"string","description":"PII-strip маска"},"membershipRole":{"type":"string"},"managerUserId":{"type":"string","nullable":true},"joinedAt":{"type":"string","format":"date-time"},"lastDiagnosticAt":{"type":"string","format":"date-time","nullable":true},"overallLevel":{"type":"number","nullable":true},"hasSharedResult":{"type":"boolean"}}},"BulkInviteResult":{"type":"object","properties":{"total":{"type":"integer"},"createdCount":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"status":{"type":"string","enum":["created","already_member","already_invited","duplicate_in_file","invalid_email"]},"invitationId":{"type":"string"}}}}}}}},"paths":{"/api/v1/model/domains":{"get":{"summary":"Список 10 управленческих доменов","tags":["Модель"],"responses":{"200":{"description":"Список доменов"}}}},"/api/v1/model/maturity-levels":{"get":{"summary":"4 уровня зрелости BARS","tags":["Модель"],"responses":{"200":{"description":"Уровни зрелости"}}}},"/api/v1/diagnostics/sessions":{"post":{"summary":"Создать сессию диагностики","tags":["Диагностика"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["role","company_size","direct_reports"],"properties":{"role":{"type":"string","enum":["entrepreneur","c_level","product","dept_head","division_head"]},"company_size":{"type":"string","enum":["<50","50-500","500-5000",">5000"]},"direct_reports":{"type":"string","enum":["1-3","4-10","11-30",">30"]},"respondent_name":{"type":"string","description":"Необязательно"}}}}}},"responses":{"201":{"description":"Сессия создана","content":{"application/json":{"schema":{"type":"object","properties":{"session_id":{"type":"string"},"survey_url":{"type":"string"}}}}}},"400":{"description":"Ошибка валидации"},"401":{"description":"Неверный API ключ"}}}},"/api/v1/diagnostics/sessions/{id}":{"get":{"summary":"Статус сессии","tags":["Диагностика"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Статус сессии"},"404":{"description":"Не найдена"}}}},"/api/v1/diagnostics/sessions/{id}/report":{"get":{"summary":"Полный отчёт по завершённой диагностике","tags":["Диагностика"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Отчёт: уровни по доменам, слабые зоны, точки роста"},"404":{"description":"Отчёт не готов или сессия не найдена"}}}},"/api/v1/kb/items":{"get":{"summary":"Список материалов базы знаний","tags":["База знаний"],"parameters":[{"name":"domain","in":"query","schema":{"type":"string"},"description":"Слаг домена: strategy, execution, people..."},{"name":"type","in":"query","schema":{"type":"string"},"description":"article, book, video, course, practice, case, glossary"},{"name":"maturity","in":"query","schema":{"type":"string"},"description":"level-1..level-4"},{"name":"role","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Полнотекстовый поиск"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Список материалов с пагинацией"}}}},"/api/v1/kb/items/{slug}":{"get":{"summary":"Детали материала по slug","tags":["База знаний"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Материал"},"404":{"description":"Не найден"}}}},"/api/v1/kb/recommendations":{"get":{"summary":"Персональные рекомендации","tags":["База знаний"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"session_id","in":"query","schema":{"type":"string"},"description":"ID завершённой сессии"},{"name":"domain","in":"query","schema":{"type":"string"}},{"name":"level","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Рекомендации"}}}},"/api/v1/kb/suggestions":{"post":{"summary":"Предложить материал на модерацию","tags":["База знаний"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","type"],"properties":{"url":{"type":"string","format":"uri"},"type":{"type":"string","enum":["article","book","video","course","practice","case","glossary"]},"title":{"type":"string"},"description":{"type":"string","maxLength":300},"author_email":{"type":"string","format":"email"}}}}}},"responses":{"201":{"description":"Принято на модерацию"}}}},"/api/v1/corporate/companies":{"post":{"summary":"Создать компанию (вы — owner)","tags":["Corporate"],"security":[{"ApiKeyAuth":[]}],"description":"Требует scope corporate.write.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"emailDomain":{"type":"string","description":"Напр. example.com"},"slug":{"type":"string","description":"URL-slug; если не указан — генерируется из name"}}}}}},"responses":{"201":{"description":"Компания создана","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"400":{"description":"Ошибка валидации"},"401":{"description":"Неверный API ключ"},"403":{"description":"Нет scope corporate.write"}}},"get":{"summary":"Мои компании (активные memberships)","tags":["Corporate"],"security":[{"ApiKeyAuth":[]}],"description":"Требует scope corporate.read.","responses":{"200":{"description":"Список memberships","content":{"application/json":{"schema":{"type":"object","properties":{"companies":{"type":"array","items":{"type":"object","properties":{"companyId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"role":{"type":"string"},"joinedAt":{"type":"string","format":"date-time"}}}},"total":{"type":"integer"}}}}}},"401":{"description":"Неверный API ключ"},"403":{"description":"Нет scope corporate.read"}}}},"/api/v1/corporate/companies/{companyId}":{"get":{"summary":"Данные компании","tags":["Corporate"],"security":[{"ApiKeyAuth":[]}],"description":"Требует членства в компании + scope corporate.read.","parameters":[{"name":"companyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"403":{"description":"Не член компании"},"404":{"description":"Компания не найдена"}}}},"/api/v1/corporate/companies/{companyId}/invitations":{"post":{"summary":"Пригласить человека","tags":["Corporate"],"security":[{"ApiKeyAuth":[]}],"description":"Требует owner/hr_admin + scope corporate.write.","parameters":[{"name":"companyId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["invitedEmail"],"properties":{"invitedEmail":{"type":"string","format":"email"}}}}}},"responses":{"201":{"description":"Приглашение создано","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"403":{"description":"Не owner/hr_admin"}}}},"/api/v1/corporate/companies/{companyId}/invitations/bulk":{"post":{"summary":"Пачка приглашений (до 200)","tags":["Corporate"],"security":[{"ApiKeyAuth":[]}],"description":"Валидация формата email + дедуп внутри файла + проверка already_member/already_invited. Требует owner/hr_admin + scope corporate.write.","parameters":[{"name":"companyId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rows"],"properties":{"rows":{"type":"array","maxItems":200,"items":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}}}}},"responses":{"200":{"description":"Результаты по каждой строке","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkInviteResult"}}}},"403":{"description":"Не owner/hr_admin"}}}},"/api/v1/corporate/companies/{companyId}/dashboard":{"get":{"summary":"HR-дашборд компании","tags":["Corporate"],"security":[{"ApiKeyAuth":[]}],"description":"Список членов с PII-strip, avg gap по доменам, sharing count. Требует owner/hr_admin + scope corporate.read.","parameters":[{"name":"companyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dashboard","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/DashboardMember"}},"domainGaps":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"integer"},"avgGap":{"type":"number"},"sampleSize":{"type":"integer"}}}},"sharing":{"type":"object","properties":{"shared":{"type":"integer"},"total":{"type":"integer"}}}}}}}},"403":{"description":"Не owner/hr_admin"}}}},"/api/v1/corporate/companies/{companyId}/members/{userId}":{"get":{"summary":"Карточка члена компании","tags":["Corporate"],"security":[{"ApiKeyAuth":[]}],"description":"assertCanViewMember: hr_admin/owner — всех, manager — только своих подчинённых. Требует scope corporate.read.","parameters":[{"name":"companyId","in":"path","required":true,"schema":{"type":"string"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Карточка с отчётами после joined_at"},"403":{"description":"Нет права видеть"}}}},"/api/v1/corporate/users/me/memberships":{"get":{"summary":"Мои членства (алиас к GET /companies)","tags":["Corporate"],"security":[{"ApiKeyAuth":[]}],"description":"Требует scope corporate.read.","responses":{"200":{"description":"Список memberships"}}}},"/api/v1/corporate/memberships/{membershipId}/share":{"post":{"summary":"Поделиться базовой диагностикой","tags":["Corporate"],"security":[{"ApiKeyAuth":[]}],"description":"Можно делиться только базовым отчётом (domain_focus=null/0). Membership должен быть вашим и активным. Требует scope corporate.write.","parameters":[{"name":"membershipId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["resultId"],"properties":{"resultId":{"type":"string"}}}}}},"responses":{"200":{"description":"Shared"},"400":{"description":"Не базовая диагностика или мембершип неактивен"},"403":{"description":"Не ваш membership"}}},"delete":{"summary":"Отозвать sharing","tags":["Corporate"],"security":[{"ApiKeyAuth":[]}],"description":"Требует scope corporate.write.","parameters":[{"name":"membershipId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Unshared"},"403":{"description":"Не ваш membership"}}}},"/api/v1/integrations/request-key":{"post":{"summary":"Получить API-ключ автоматически","tags":["Интеграции"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email","platform","use_case"],"properties":{"name":{"type":"string","description":"Ваше имя"},"email":{"type":"string","format":"email"},"platform":{"type":"string","description":"Платформа / компания"},"use_case":{"type":"string","description":"Как планируете использовать API"}}}}}},"responses":{"200":{"description":"Ключ отправлен на email"},"400":{"description":"Ошибка валидации"},"409":{"description":"Ключ для этого email уже существует"}}}}}}