🩺 UA Doctor · Agent API v1

REST API để 3 sub-agent (LinhLT1 · NamNT · HoangHH) đọc todos & reply feedback về Leo's UA Doctor. Chuẩn Authorization: Bearer sk_agent_.... Base URL: https://ua.supermindsgame.com/api/v1/agent

Authentication

Mỗi agent có 1+ API key format:

sk_agent_<agent_lower>_<8-prefix>_<40-secret>
VD:  sk_agent_linhlt1_a3f8b1c2_XXXXXXXX...XXXX

Gọi Leo mint key (chỉ hiện 1 LẦN, save vào password manager). Header:

Authorization: Bearer sk_agent_linhlt1_a3f8b1c2_XXXXXXXX...XXXX

Endpoints

GET /me

Trả identity từ key (dùng để verify key hoạt động).

curl -s -H 'Authorization: Bearer sk_agent_linhlt1_...' \
     https://ua.supermindsgame.com/api/v1/agent/me

{
  "agent": "LINHLT1",
  "key_prefix": "a3f8b1c2",
  "key_name": "Linh personal",
  "scopes": ["todos:read","todos:write","reply:write"]
}

GET /todos

List todos scope theo agent của key.

curl -s -H 'Authorization: Bearer sk_agent_...' \
     'https://ua.supermindsgame.com/api/v1/agent/todos?date=2026-08-19&include_debt=true'

{
  "agent": "LINHLT1",
  "focus_date": "2026-08-19",
  "total_today": 23,
  "total_debt": 15,
  "todos": [{"id":"uuid","title":"[APP] ...","suggested_ut":"UT1","status":"pending",...}],
  "debt_todos": [...]
}

GET /todos/:id

Chi tiết 1 todo (chỉ todos của agent mình).

PATCH /todos/:id

Update status / final_ut / reason — chỉ todos của agent mình.

curl -s -X PATCH -H 'Authorization: Bearer sk_agent_...' \
     -H 'Content-Type: application/json' \
     -d '{"status":"done","reason":"Đã scale Dance Time từ 120M→150M"}' \
     https://ua.supermindsgame.com/api/v1/agent/todos/<uuid>

{ "ok": true, "todo": {...updated...} }

POST /todos/:id/feedback

Pushback về todo cụ thể — VD "việc này không hợp lý, số sai". Leo review qua UI tab Phản hồi để Accept (update rule) / Reject / Reassign.

curl -s -X POST -H 'Authorization: Bearer sk_agent_hoanghh_...' \
     -H 'Content-Type: application/json' \
     -d '{"feedback_type":"wrong_data","body":"Payrate 15.6% thực tế là 22% — số bị lỗi tracking. Cần verify lại trước khi giao task này."}' \
     https://ua.supermindsgame.com/api/v1/agent/todos/<uuid>/feedback

{ "ok": true, "feedback": {...}, "todo": {"id":"uuid","title":"...","report_date":"2026-08-19"} }

🎯 Agent UA — token xoay 5 phút

Danh tính UA dùng cho người/bot phân tích số UA. Token tự đổi mỗi 5 phút, lấy ở endpoint dưới (cần đăng nhập Google Apero trên trình duyệt):

GET https://ua.supermindsgame.com/api/v1/agent/ua-token
→ {"token":"sk_agent_ua_...","expires_in_sec":213,"rotates_every_sec":300}

GET /creatives 🆕

Query creative snapshot data (cùng dataset UI /dashboard/creatives). Read-only, mọi agent gọi được.

Mỗi row có sẵn metrics đã tính theo công thức chuẩn của hệ — dùng thẳng, đừng tự tính lại:

ctr     = unique_inline_link_clicks / impressions × 100   (KHÔNG dùng clicks all)
cpm     = spend / impressions × 1000
cpc     = spend / clicks
cpp     = spend / purchases                    ← giá mỗi đơn
cpi     = spend / registrations                ← CHỈ APP; web = null (không có reg event)
cvr     = registrations / clicks × 100
payrate = APP: purchases/registrations × 100 · WEB: purchases/clicks × 100
roas    = purchase_value × fee / spend         ← fee: app ×0.70 · web ×0.85

meta.definitions và meta.thresholds trả kèm trong mọi response: ctr đạt app 1.5% / web 2.0% · ctr yếu app 1.0% / web 1.5% · CPM trần app 800K / web 1.5tr · CPI US ≤150K, Global <120K · payrate gate app 15% / web 4% · ROAS target app 0.35 / web 0.19 · dung sai KPI ±10%.

# Query app payrate thấp spend cao trong 3d cho HoangHH context
curl -s -H 'Authorization: Bearer sk_agent_hoanghh_...' \
     'https://ua.supermindsgame.com/api/v1/agent/creatives?window=3d&plat=web&min_spend=20000000&limit=50'

{
  "meta": {"window":"3d","total_rows":42,"filters":{...},"caller":{"agent":"HOANGHH"},"roas_multipliers":{"app":0.7,"web":0.85}},
  "summary": {
    "app": {"creatives":0, "spend":0, "cpi":165042, ...},
    "web": {"creatives":42, "spend":85300000, "roas":0.11, "payrate":3.2, "ctr":1.24, ...},
    "total_rows": 42
  },
  "rows": [
    {
      "id":123, "time_window":"3d", "is_web":true, "tz_bucket":"-7",
      "use_case":"Dancing Toy", "creative_id":"456789...", "thumbnail_url":"...",
      "deeplink":"https://trend.reelme.art/f/dance_2_v4",
      "ad_count":18, "campaigns":["IIP555_WebFunnel_Reelme_dance_..."],
      "spend":12500000, "impressions":1010000, "clicks":19040, "unique_clicks":18700,
      "purchases":572, "purchase_value":1470000, "registrations":15200
    },
    ...
  ]
}

Metric formulas: CTR = unique_clicks/impressions (fallback clicks). ROAS = purchase_value/spend × 0.70 (app) hoặc × 0.85 (web). Payrate = purchases/registrations (app) hoặc purchases/clicks (web).

POST /kb 🆕

Bổ sung Knowledge Base entry — rule/kiến thức mà agent bạn học được sẽ đưa vào KB của agent. Sau đó Leo sync (promote) về master KB → analyzer LLM dùng khi build report.

KHÔNG dùng /reply để gửi KB — reply endpoint dành cho comment/feedback về todo cụ thể. KB endpoint dành riêng cho rule tổng quát, structured.

🆕 knowledge_class — 8 lớp tri thức. kb_type là routing thô (data vs assignment); knowledge_class mới là bản chất tri thức, dùng để lọc ?class= và nhóm trên UI.

curl -s -X POST -H 'Authorization: Bearer sk_agent_hoanghh_...' \
     -H 'Content-Type: application/json' \
     -d '{
       "kb_type": "data_rule",
       "title": "Web spend >20M + payrate <4% → highlight red trong report",
       "rule_text": "Khi 1 web use case có spend > 20M VND VÀ payrate < 4% trong ngày focus, report phải: (1) highlight row đỏ, (2) thêm badge ⚠️, (3) suggest sửa OB flow.",
       "priority": 1
     }' \
     https://ua.supermindsgame.com/api/v1/agent/kb

{ "entry": { "id":"uuid", "agent":"HOANGHH", "promoted_to_leo": false, ... } }

Sub-agent: entry lưu với agent=<sub>, promoted_to_leo=false — chờ Leo sync để analyzer dùng.
LEO key: entry auto-promoted (promoted_to_leo=true) ngay lập tức.

Xem tất cả rules đã contribute:

curl -s 'https://ua.supermindsgame.com/api/v1/agent/kb?agent=HOANGHH&active=true'
# hoặc UI: https://ua.supermindsgame.com/dashboard/kb

PATCH /kb/:id

Update rule (chỉ owner hoặc LEO). Body: {title, rule_text, priority, example, active}.

POST /reply

Reply/feedback back to Leo's UA Doctor về 1 todo cụ thể — insert vào ua_doctor_comments (Leo duyệt qua @alisa như comment thường).
⚠️ KHÔNG dùng /reply cho KB entries — dùng POST /kb ở trên. /reply chỉ cho feedback về 1 todo hoặc comment tự do.

curl -s -X POST -H 'Authorization: Bearer sk_agent_...' \
     -H 'Content-Type: application/json' \
     -d '{"body":"Đã scale xong Dance Time. Cần Leo xem thêm rule scaling giới hạn.","todo_id":"uuid"}' \
     https://ua.supermindsgame.com/api/v1/agent/reply

{ "ok": true, "comment": { "id":"uuid", "status":"pending", ... } }

Todo schema

{
  "id": "uuid",
  "report_date": "2026-08-19",
  "version": "1.20260820d",
  "agent": "LINHLT1",
  "task_type": "from_analyzer",
  "uc_ref": "Dance Time::dance_7",
  "plat": "app",
  "title": "[APP] Làm biến thể mới Dance Time·dance_7 (120.5M ROAS 0.37 CTR 1.55% pr 15.6%)",
  "context": {"spend": 120500000, "roas": 0.37, "ctr": 1.55, "payrate": 15.6, "ob_flow": "dance_7"},
  "suggested_ut": "UT1",
  "suggested_reason": "Rule ...",
  "final_ut": null,             // team override — set qua PATCH
  "reason": null,               // team explanation — set qua PATCH
  "status": "pending",          // pending | in_progress | done
  "created_at": "2026-08-20T04:37:00Z",
  "updated_at": "2026-08-20T04:37:00Z"
}

Errors

Rate limit

Hiện KHÔNG rate limit. Fair use → gọi ≤ 60 req/min. Nếu team cần cao hơn → báo Leo.

Rotate key

Nếu key leak/lost → báo Leo revoke + mint key mới. Prefix (8-char sau agent_) là public — Leo tra được key nào để revoke.

UA Doctor · Reelme iip555 · → Dashboard