{"openapi":"3.1.0","info":{"title":"Spytay API","description":"Доступ лише для читання до звітів, які ви вже замовили: висновок, місце серед брендів, таблиці за асистентами, відповіді дослівно та план дій. Видимість, перше місце й інтервали — частки від 0 до 1. Ключ створюється в кабінеті, розділ «API».","version":"1.0.0"},"servers":[{"url":"https://spytay.com"}],"paths":{"/api/v1/me":{"get":{"summary":"Поточний ключ і кабінет","description":"Хто ви для API: номер кабінету, адреса, префікс ключа, ліміти та кількість звітів.","operationId":"get_me_api_v1_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"Немає ключа, він недійсний або відкликаний.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Звіту немає серед звітів кабінету.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Перевищено ліміт запитів; див. заголовок Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/reports":{"get":{"summary":"Список звітів","description":"Звіти кабінету, найновіші перші: статус, категорія, бренд, асистенти, k і публічне посилання.","operationId":"list_reports_api_v1_reports_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Скільки звітів повернути (до 100).","default":50,"title":"Limit"},"description":"Скільки звітів повернути (до 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":1000000,"minimum":0,"description":"Скільки звітів пропустити.","default":0,"title":"Offset"},"description":"Скільки звітів пропустити."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportList"}}}},"401":{"description":"Немає ключа, він недійсний або відкликаний.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Звіту немає серед звітів кабінету.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Перевищено ліміт запитів; див. заголовок Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некоректний параметр запиту (код validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/reports/{report_id}":{"get":{"summary":"Звіт з усіма числами","description":"Усе, що показує звіт у кабінеті: висновок, місце, лідера, найважливіше, таблиці за асистентами, план дій.","operationId":"get_report_api_v1_reports__report_id__get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"integer","maximum":2147483647,"minimum":1,"description":"Номер звіту з кабінету.","title":"Report Id"},"description":"Номер звіту з кабінету."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"401":{"description":"Немає ключа, він недійсний або відкликаний.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Звіту немає серед звітів кабінету.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Перевищено ліміт запитів; див. заголовок Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некоректний параметр запиту (код validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/reports/{report_id}/answers":{"get":{"summary":"Відповіді асистентів дослівно","description":"Відповіді асистентів: питання, текст, згадані бренди та місце вашого бренду.","operationId":"get_answers_api_v1_reports__report_id__answers_get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"integer","maximum":2147483647,"minimum":1,"description":"Номер звіту з кабінету.","title":"Report Id"},"description":"Номер звіту з кабінету."},{"name":"assistant","in":"query","required":false,"schema":{"type":"string","description":"Ідентифікатор моделі зі списку assistants звіту.","default":"","title":"Assistant"},"description":"Ідентифікатор моделі зі списку assistants звіту."},{"name":"condition","in":"query","required":false,"schema":{"type":"string","description":"category, needs або probe.","default":"","title":"Condition"},"description":"category, needs або probe."},{"name":"mentions","in":"query","required":false,"schema":{"type":"string","description":"yes — лише відповіді з вашим брендом, no — без нього.","default":"","title":"Mentions"},"description":"yes — лише відповіді з вашим брендом, no — без нього."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":1000000,"minimum":1,"description":"Номер сторінки.","default":1,"title":"Page"},"description":"Номер сторінки."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Розмір сторінки (до 200).","default":50,"title":"Page Size"},"description":"Розмір сторінки (до 200)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnswerPage"}}}},"401":{"description":"Немає ключа, він недійсний або відкликаний.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Звіту немає серед звітів кабінету.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Перевищено ліміт запитів; див. заголовок Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некоректний параметр запиту (код validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/reports/{report_id}/answers.csv":{"get":{"summary":"Відповіді у CSV","description":"Той самий файл, що й у кабінеті: усі відповіді звіту.","operationId":"get_answers_csv_api_v1_reports__report_id__answers_csv_get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"integer","maximum":2147483647,"minimum":1,"description":"Номер звіту з кабінету.","title":"Report Id"},"description":"Номер звіту з кабінету."}],"responses":{"200":{"description":"CSV з відповідями (UTF-8 з BOM).","content":{"application/json":{"schema":{}},"text/csv":{}}},"401":{"description":"Немає ключа, він недійсний або відкликаний.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Звіту немає серед звітів кабінету.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Перевищено ліміт запитів; див. заголовок Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некоректний параметр запиту (код validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/reports/{report_id}/metrics.csv":{"get":{"summary":"Показники у CSV","description":"Той самий файл, що й у кабінеті: показники кожного бренду за асистентами й типами запитів.","operationId":"get_metrics_csv_api_v1_reports__report_id__metrics_csv_get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"integer","maximum":2147483647,"minimum":1,"description":"Номер звіту з кабінету.","title":"Report Id"},"description":"Номер звіту з кабінету."}],"responses":{"200":{"description":"CSV з показниками (UTF-8 з BOM).","content":{"application/json":{"schema":{}},"text/csv":{}}},"401":{"description":"Немає ключа, він недійсний або відкликаний.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Звіту немає серед звітів кабінету.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Перевищено ліміт запитів; див. заголовок Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некоректний параметр запиту (код validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/reports/{report_id}/plan":{"get":{"summary":"План дій","description":"Лише план дій звіту: кроки, дата наступного вимірювання та пакет.","operationId":"get_plan_api_v1_reports__report_id__plan_get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"integer","maximum":2147483647,"minimum":1,"description":"Номер звіту з кабінету.","title":"Report Id"},"description":"Номер звіту з кабінету."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plan"}}}},"401":{"description":"Немає ключа, він недійсний або відкликаний.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Звіту немає серед звітів кабінету.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Перевищено ліміт запитів; див. заголовок Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некоректний параметр запиту (код validation_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"Action":{"properties":{"code":{"type":"string","title":"Code"},"title":{"type":"string","title":"Title"},"why":{"type":"string","title":"Why"},"what":{"type":"string","title":"What"},"effect":{"type":"string","title":"Effect"},"package":{"type":"string","title":"Package"}},"type":"object","required":["code","title","why","what","effect","package"],"title":"Action"},"Answer":{"properties":{"id":{"type":"integer","title":"Id"},"assistant":{"type":"string","title":"Assistant","description":"Ідентифікатор моделі."},"condition":{"type":"string","title":"Condition","description":"category, needs або probe."},"scenario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scenario"},"prompt":{"type":"string","title":"Prompt"},"answer":{"type":"string","title":"Answer"},"brands_mentioned":{"items":{"type":"string"},"type":"array","title":"Brands Mentioned"},"focal_mentioned":{"type":"boolean","title":"Focal Mentioned"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank","description":"Місце бренду клієнта у відповіді; null — не згадано."}},"type":"object","required":["id","assistant","condition","scenario","prompt","answer","brands_mentioned","focal_mentioned","rank"],"title":"Answer"},"AnswerPage":{"properties":{"answers":{"items":{"$ref":"#/components/schemas/Answer"},"type":"array","title":"Answers"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["answers","page","page_size","total"],"title":"AnswerPage"},"Assistant":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Ідентифікатор моделі; null — усі асистенти разом."},"name":{"type":"string","title":"Name","description":"Назва асистента українською («Усі» для спільного підсумку)."}},"type":"object","required":["id","name"],"title":"Assistant"},"CategoryStat":{"properties":{"visibility":{"type":"number","title":"Visibility","description":"Частка відповідей, де бренд серед перших k (0–1)."},"lo":{"type":"number","title":"Lo","description":"Нижня межа 95 % інтервалу."},"hi":{"type":"number","title":"Hi","description":"Верхня межа 95 % інтервалу."},"first_place":{"type":"number","title":"First Place","description":"Частка відповідей, де бренд названо першим (0–1)."},"mean_rank":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Mean Rank","description":"Середнє місце; null — бренд не названо жодного разу."},"n":{"type":"integer","title":"N","description":"Кількість відповідей."}},"type":"object","required":["visibility","lo","hi","first_place","mean_rank","n"],"title":"CategoryStat"},"Cell":{"properties":{"assistant":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assistant","description":"Ідентифікатор моделі; null — усі асистенти разом."},"n":{"type":"integer","title":"N"},"visibility":{"type":"number","title":"Visibility"},"lo":{"type":"number","title":"Lo"},"hi":{"type":"number","title":"Hi"},"mrr":{"type":"number","title":"Mrr"},"mrr_lo":{"type":"number","title":"Mrr Lo"},"mrr_hi":{"type":"number","title":"Mrr Hi"},"first_place":{"type":"number","title":"First Place"},"mean_rank":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Mean Rank"}},"type":"object","required":["assistant","n","visibility","lo","hi","mrr","mrr_lo","mrr_hi","first_place","mean_rank"],"title":"Cell"},"Condition":{"properties":{"label":{"type":"string","title":"Label"},"assistants":{"items":{"$ref":"#/components/schemas/Assistant"},"type":"array","title":"Assistants"},"rows":{"items":{"$ref":"#/components/schemas/Row"},"type":"array","title":"Rows"},"takeaway":{"type":"string","title":"Takeaway"}},"type":"object","required":["label","assistants","rows","takeaway"],"title":"Condition"},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code","description":"unauthorized, not_found, rate_limited, validation_error, internal_error."},"message":{"type":"string","title":"Message","description":"Пояснення українською."}},"type":"object","required":["code","message"],"title":"ErrorBody"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"ErrorResponse"},"Highlight":{"properties":{"title":{"type":"string","title":"Title"},"meaning":{"type":"string","title":"Meaning"},"numbers":{"additionalProperties":true,"type":"object","title":"Numbers"}},"type":"object","required":["title","meaning","numbers"],"title":"Highlight"},"Leader":{"properties":{"name":{"type":"string","title":"Name"},"visibility":{"type":"number","title":"Visibility"},"is_focal":{"type":"boolean","title":"Is Focal"}},"type":"object","required":["name","visibility","is_focal"],"title":"Leader"},"LeaderboardItem":{"properties":{"name":{"type":"string","title":"Name"},"visibility":{"type":"number","title":"Visibility"},"is_focal":{"type":"boolean","title":"Is Focal"},"discovered":{"type":"boolean","title":"Discovered","description":"true — бренд знайдено у відповідях, його не було в заданому наборі."}},"type":"object","required":["name","visibility","is_focal","discovered"],"title":"LeaderboardItem"},"Limits":{"properties":{"per_minute":{"type":"integer","title":"Per Minute","description":"Запитів за хвилину на ключ."},"per_hour":{"type":"integer","title":"Per Hour","description":"Запитів за годину на ключ."}},"type":"object","required":["per_minute","per_hour"],"title":"Limits"},"Me":{"properties":{"customer_id":{"type":"integer","title":"Customer Id"},"email":{"type":"string","title":"Email"},"key_prefix":{"type":"string","title":"Key Prefix","description":"Перші 12 символів ключа, яким виконано запит."},"limits":{"$ref":"#/components/schemas/Limits"},"reports_count":{"type":"integer","title":"Reports Count","description":"Скільки звітів у кабінеті."}},"type":"object","required":["customer_id","email","key_prefix","limits","reports_count"],"title":"Me"},"Plan":{"properties":{"actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Actions"},"next_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Date"},"package":{"type":"string","title":"Package"}},"type":"object","required":["actions","next_date","package"],"title":"Plan"},"Report":{"properties":{"id":{"type":"integer","title":"Id"},"status":{"type":"string","title":"Status"},"ready":{"type":"boolean","title":"Ready","description":"false — вимірювання ще триває, аналітичні поля порожні."},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand"},"k":{"type":"integer","title":"K"},"category":{"anyOf":[{"$ref":"#/components/schemas/CategoryStat"},{"type":"null"}]},"verdict":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verdict"},"severity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Severity","description":"success, info, warning або danger."},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank","description":"Місце бренду за видимістю."},"rank_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank Total","description":"Скільки брендів у порівнянні."},"leader":{"anyOf":[{"$ref":"#/components/schemas/Leader"},{"type":"null"}]},"highlights":{"items":{"$ref":"#/components/schemas/Highlight"},"type":"array","title":"Highlights","default":[]},"leaderboard":{"items":{"$ref":"#/components/schemas/LeaderboardItem"},"type":"array","title":"Leaderboard","default":[]},"conditions":{"additionalProperties":{"$ref":"#/components/schemas/Condition"},"type":"object","title":"Conditions","description":"За типом запитів: category, needs, probe.","default":{}},"explain":{"items":{"type":"string"},"type":"array","title":"Explain","default":[]},"actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Actions","default":[]},"next_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Date"},"measured_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Measured At"},"report_url":{"type":"string","title":"Report Url"}},"type":"object","required":["id","status","ready","k","report_url"],"title":"Report"},"ReportItem":{"properties":{"id":{"type":"integer","title":"Id","description":"Номер звіту."},"status":{"type":"string","title":"Status","description":"queued, running, done, failed або cancelled."},"created_at":{"type":"string","title":"Created At"},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Finished At"},"category":{"type":"string","title":"Category","description":"Категорія, яку вимірювали."},"focal_brand":{"type":"string","title":"Focal Brand","description":"Бренд клієнта."},"package":{"type":"string","title":"Package","description":"Пакет: report, monitoring, actions."},"assistants":{"items":{"$ref":"#/components/schemas/Assistant"},"type":"array","title":"Assistants"},"k":{"type":"integer","title":"K","description":"Скільки перших місць у відповіді враховано (BRP@k)."},"answers_total":{"type":"integer","title":"Answers Total","description":"Скільки відповідей асистентів зібрано."},"report_url":{"type":"string","title":"Report Url","description":"Публічне посилання на звіт."}},"type":"object","required":["id","status","created_at","finished_at","category","focal_brand","package","assistants","k","answers_total","report_url"],"title":"ReportItem"},"ReportList":{"properties":{"reports":{"items":{"$ref":"#/components/schemas/ReportItem"},"type":"array","title":"Reports"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["reports","total","limit","offset"],"title":"ReportList"},"Row":{"properties":{"brand":{"type":"string","title":"Brand"},"is_focal":{"type":"boolean","title":"Is Focal"},"cells":{"items":{"$ref":"#/components/schemas/Cell"},"type":"array","title":"Cells"}},"type":"object","required":["brand","is_focal","cells"],"title":"Row"}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Ключ API з кабінету (розділ «API»): заголовок Authorization: Bearer spk_…"}}},"security":[{"bearerAuth":[]}]}