# AutoMonitor — LLM / Agent Guide

AutoMonitor is a multi-platform social-listening & AI analysis platform
(Xiaohongshu / RedNote, Threads). It crawls posts by keyword, labels them
(sentiment / topic / content-type) with LLMs, clusters topics, raises crisis
alerts, and generates daily / weekly reports.

This file tells an LLM / agent exactly how to drive it over HTTP.

Interactive API reference (authoritative, always current):
  http://auto-monitor.ambr.io/docs        (Swagger UI)
  http://auto-monitor.ambr.io/redoc
  http://auto-monitor.ambr.io/openapi.json

AUTHENTICATION
  Every request to /api/external/v1/* needs BOTH:
    X-API-Key: <your-api-key>          (platform-issued shared key; ask the AutoMonitor team)
  plus ONE identity header:
    Authorization: Bearer mia_pat_...   (your MIA platform PAT — get one at
                                         https://mia-platform.i-click.com/account)
    -- or --
    X-User-Email: you@<whitelisted-company-domain>
  Your first call auto-provisions your user + billing account.
  Resources you create are owned by you and isolated per tenant.

RESPONSE ENVELOPE
  Most endpoints return: { "success": bool, "message": str, "data": {...} }

ASYNC TASK MODEL
  Trigger endpoints (crawl / analyze / topics / report) are asynchronous:
  they return a task_id with status "queued". Poll until done:
    GET http://auto-monitor.ambr.io/api/external/v1/tasks/{task_id}
  Statuses: queued -> running -> succeeded | failed. Poll every 3-5s.

ENDPOINTS (base: http://auto-monitor.ambr.io/api/external/v1)
  Self-describing field docs (call these first if unsure):
    GET  /skills/format          field spec + examples for Skills
    GET  /monitors/format        field spec for monitor tasks
    GET  /threads/probe/format   field spec for the Threads seed probe

  Skills (analysis logic: prompt / alert thresholds / report template):
    POST   /skills               create
    GET    /skills               list mine
    GET    /skills/{skill_id}    detail
    PATCH  /skills/{skill_id}    update
    DELETE /skills/{skill_id}    delete

  Monitors (a keyword group on a platform, managed mode):
    POST   /monitors             register a monitor task
    GET    /monitors             list mine
    GET    /monitors/ids         list my monitor group ids (lightweight)
    GET    /monitors/{id}        detail
    PATCH  /monitors/{id}        update
    DELETE /monitors/{id}        delete

  Building-block triggers (async, return task_id):
    POST   /monitors/{id}/crawl     collect posts now
    POST   /monitors/{id}/analyze   run alerts + topic analysis
    POST   /monitors/{id}/topics    topic clustering
    POST   /monitors/{id}/report    generate a report

  Pull results:
    GET    /monitors/{id}/posts     collected posts
    GET    /monitors/{id}/alerts    alert events
    GET    /monitors/{id}/reports   reports
    GET    /monitors/{id}/topics    topic clusters
    GET    /tasks/{task_id}         task status / result

  Threads discovery:
    POST   /threads/probe        dry-run seed keywords before configuring a task

BILLING
  Calls that invoke LLM analysis are metered against your MIA credit and
  charged on the MIA platform side. If credit is insufficient the call errors.
  Check or top up your balance on the MIA platform (this API has no balance endpoint).

HTTP STATUS CODES
  200 ok · 400 bad request · 401 missing/invalid auth · 403 not whitelisted ·
  404 not found / not yours · 429 rate limited · 503 upstream (e.g. MIA) unavailable

See http://auto-monitor.ambr.io/docs for the complete, always-current OpenAPI specification.