{"openapi":"3.0.3","info":{"title":"PromoPilot API","version":"1.0.0","description":"REST API экосистемы PromoPilot: запуск ссылочного продвижения (каскады), Rank Tracker, SEO Audit и Security Shield. Аутентификация — ключ API из клиентского кабинета (раздел «API»), заголовок Authorization: Bearer ppk_… Все списания — с личного баланса аккаунта. Полная документация: https://promopilot.link/api/docs"},"servers":[{"url":"https://promopilot.link/api/v1"}],"security":[{"bearerKey":[]}],"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer","bearerFormat":"ppk_… API key"}},"schemas":{"Error":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"insufficient_funds"},"message":{"type":"string"},"details":{"type":"object"}}}}},"Project":{"type":"object","properties":{"id":{"type":"integer"},"uuid":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"domain_host":{"type":"string"},"homepage_url":{"type":"string"},"region":{"type":"string"},"topic":{"type":"string"},"created_via":{"type":"string","enum":["web","api"]},"created_at":{"type":"string","format":"date-time"}}},"Run":{"type":"object","properties":{"id":{"type":"integer"},"project_id":{"type":"integer"},"link_id":{"type":"integer"},"target_url":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"progress":{"type":"object"},"charged":{"type":"number"},"discount_percent":{"type":"number"},"initiated_via":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}},"paths":{"/ping":{"get":{"summary":"Проверка доступности","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/me":{"get":{"summary":"Аккаунт: профиль, баланс, Pro-статус, скоупы ключа","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Неверный ключ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/balance":{"get":{"summary":"Текущий баланс","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/key":{"get":{"summary":"Информация о предъявленном ключе","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/branding":{"get":{"summary":"White-label бренд отчётов (Pro)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"put":{"summary":"Сохранить white-label бренд (Pro)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"company_name":{"type":"string"},"logo_url":{"type":"string"},"accent_color":{"type":"string"},"footer_text":{"type":"string"},"website":{"type":"string"}},"required":["company_name"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"pro_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects":{"get":{"summary":"Список проектов (по умолчанию только API-проекты; ?all=1 — все)","parameters":[{"name":"all","in":"query","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Создать проект (created_via=api) + опционально ссылки","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","url"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"language":{"type":"string"},"region":{"type":"string"},"topic":{"type":"string"},"wishes":{"type":"string"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"anchor":{"type":"string"},"language":{"type":"string"},"wish":{"type":"string"}}}}}}}}},"responses":{"201":{"description":"Создан","content":{"application/json":{"schema":{"type":"object"}}}},"422":{"description":"validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{id}":{"get":{"summary":"Проект со ссылками и запусками","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Обновить проект","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"delete":{"summary":"Удалить API-проект (личные проекты недоступны)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{id}/links":{"post":{"summary":"Добавить продвигаемую ссылку (домен = домен проекта)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"anchor":{"type":"string"},"language":{"type":"string"},"wish":{"type":"string"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"422":{"description":"domain_mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/promotion/tariffs":{"get":{"summary":"Активные тарифы + юнит-цены гибкого каскада + ваша скидка","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/promotion/quote":{"post":{"summary":"Предрасчёт цены запуска (без списания)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/promotion/runs":{"post":{"summary":"Запустить продвижение ссылки (списывает баланс)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["project_id"],"properties":{"project_id":{"type":"integer"},"url":{"type":"string"},"link_id":{"type":"integer"},"tariff_id":{"type":"integer"},"level1_count":{"type":"integer"},"level2_per_level1":{"type":"integer"},"level3_per_level2":{"type":"integer"},"crowd_per_article":{"type":"integer"},"schedule_start_at":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"Запущено: run_id, charged, balance_after","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"insufficient_funds: required/balance/shortfall/topup_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"level1_disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"Список запусков (фильтры: project_id, status=active|…, initiated_via=api|web)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/promotion/runs/{id}":{"get":{"summary":"Статус запуска + прогресс по уровням","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/promotion/runs/{id}/nodes":{"get":{"summary":"Все размещения каскада (?verified=1 — только проверенные)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"verified","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/promotion/runs/{id}/report":{"get":{"summary":"Отчёт (verified-only). ?format=pdf — брендированный PDF; brand_* параметры (Pro) — white-label","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","pdf"]}},{"name":"brand_company","in":"query","schema":{"type":"string"}},{"name":"brand_logo_url","in":"query","schema":{"type":"string"}},{"name":"brand_accent_color","in":"query","schema":{"type":"string"}},{"name":"brand_footer_text","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"pro_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"report_archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rank/projects":{"get":{"summary":"Rank Tracker: проекты","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Rank Tracker: создать проект {domain, name?, region?, device?}","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/rank/projects/{id}":{"get":{"summary":"Rank Tracker: проект + ключевые слова с позициями","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/rank/projects/{id}/keywords":{"post":{"summary":"Rank Tracker: добавить ключевые слова","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/rank/projects/{id}/check":{"post":{"summary":"Rank Tracker: поставить проверку позиций в очередь (списание по факту проверок)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/audit/projects":{"get":{"summary":"SEO Audit: проекты","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"SEO Audit: создать проект {url, name?}","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/audit/projects/{id}/estimate":{"get":{"summary":"SEO Audit: оценка размера сайта и цены полного аудита","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/audit/projects/{id}/crawls":{"post":{"summary":"SEO Audit: запустить аудит {mode: express|full}. express — бесплатно, full — с баланса","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"insufficient_funds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"already_running / need_estimate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"express_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"SEO Audit: история аудитов проекта","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/audit/crawls/{id}":{"get":{"summary":"SEO Audit: статус/итоги аудита","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/shield/projects":{"get":{"summary":"Shield: проекты","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Shield: создать/найти проект {url, name?}","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/shield/projects/{id}/verify":{"post":{"summary":"Shield: проверить подтверждение домена (DNS TXT / .well-known / meta)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/shield/projects/{id}/scans":{"post":{"summary":"Shield: запустить скан {mode: free|deep|comprehensive} (платные — с баланса)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"insufficient_funds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"needs_verify","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shield/scans/{id}":{"get":{"summary":"Shield: статус, оценка, светофор-вердикт, находки","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}