SEOmonitor Agent API dokumentáció

Bearer tokenes API AI agenteknek, n8n workflow-knak, MCP szervereknek és saját automatizmusoknak.

Token létrehozás

Ügyfél token

Menü: Beállítások → API tokenek. A token csak a saját fiók projektjeit és kulcsszavait látja.

Auth

Authorization: Bearer $SEOMONITOR_AGENT_TOKEN
Content-Type: application/json

A plaintext token csak generáláskor látható. Elveszett tokennél újat kell generálni.

Jogosultságok

Scope	Mit enged
projects:read	Projektek listázása és lekérése
projects:write	Projekt létrehozás, módosítás, deaktiválás
keywords:read	Kulcsszavak listázása
keywords:write	Kulcsszó hozzáadás, módosítás, deaktiválás
analysis:run	Elemzések indítása és queue státusz lekérése
models:read	Aktív AI model beállítások lekérése

Endpointok

Method	URL	Leírás	Scope
GET	/api/agent/v1/health	Token ellenőrzés és capability lista	projects:read
GET	/api/agent/v1/docs	Gépi JSON dokumentáció	publikus
GET	/api/agent/v1/projects	Saját projektek listázása	projects:read
POST	/api/agent/v1/projects	Projekt létrehozása	projects:write
GET	/api/agent/v1/projects/:id	Projekt részletek	projects:read
PATCH	/api/agent/v1/projects/:id	Projekt módosítása	projects:write
DELETE	/api/agent/v1/projects/:id	Projekt deaktiválása	projects:write
GET	/api/agent/v1/projects/:id/keywords	Projekt kulcsszavai	keywords:read
POST	/api/agent/v1/projects/:id/keywords	Kulcsszavak hozzáadása	keywords:write
PATCH	/api/agent/v1/keywords/:id	Kulcsszó módosítása, AI mérés kapcsolása	keywords:write
DELETE	/api/agent/v1/keywords/:id	Kulcsszó deaktiválása	keywords:write
GET	/api/agent/v1/analyze	Queue státuszok	analysis:run
POST	/api/agent/v1/analyze	Elemzés indítása	analysis:run
GET	/api/agent/v1/results	Elemzési eredmények lekérése	projects:read
GET	/api/agent/v1/models	AI model beállítások	models:read

Adatforrások

Az eredmények a saját projektekből, kulcsszavakból, nyilvános weboldaladatokból, Google/SERP jellegű találati adatokból, technikai auditokból és AI visibility mérésekből állhatnak össze. Ügyfél token csak a token tulajdonosának projektadatait és mérési eredményeit adja vissza.

Kulcsszó kutatás

A bejelentkezett felület /keyword-research oldala a /api/keyword-research endpointot használja. Ez jelenleg session-alapú ügyfélfunkció, nem Bearer tokenes Agent API endpoint.

GET /api/keyword-research

Válasz:
{
  "usage": 12,
  "limit": 200,
  "available": true
}

POST /api/keyword-research
Content-Type: application/json

{
  "keyword": "esküvői fotós debrecen",
  "location": "Hungary",
  "language": "Hungarian"
}

A válasz havi keresési volument, CPC-t, versenyt, 12 havi trendet és kapcsolódó kulcsszó-ötleteket ad. Az eredmény 30 napig cache-elődik; cache-találat nem fogyaszt havi kutatási kvótát. A korábban lekutatott kulcsszavak userenként előzménylistában visszanyithatók. A projektkulcsszavak havi állapota külön session endpointból olvasható, és a meglévő projektadatok frissességét mutatja új külső lekérés nélkül. A felület a válasz adataiból kliensoldali prioritást, AI mérési javaslatot, tömeges projektbe mentést, GSC/projekt gap ellenőrzést és tartalomterv mentést kínál. A felület szándékosan nem jelenít meg belső adatbeszállító- vagy infrastruktúrarészleteket.

Projekt létrehozás

curl -X POST https://seomonitor.hu/api/agent/v1/projects \
  -H "Authorization: Bearer $SEOMONITOR_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.hu",
    "name": "Example",
    "keywords": ["seo debrecen", "ai visibility"],
    "clientName": "Ügyfél A",
    "category": "Webshop",
    "tags": ["kiemelt", "lokális SEO"],
    "favorite": true,
    "priority": "high",
    "workflowStatus": "onboarding",
    "assignedToName": "Account manager",
    "reportRecipients": ["riport@example.hu"],
    "reportSettings": {
      "enabled": true,
      "frequency": "inherit",
      "includePdf": "inherit",
      "contentOverrides": {}
    }
  }'

Több domain vagy ügynökségi működés esetén a projekt meta mezők minden listázásban és eredményben visszajönnek: clientName, category, tags, favorite, priority, workflowStatus, assignedToName, reportRecipients, reportSettings. Egy személyes fióknál a reportSettings kihagyható, ilyenkor a projekt a fiók alap riportbeállításait örökli.

Kulcsszavak hozzáadása

curl -X POST https://seomonitor.hu/api/agent/v1/projects/1/keywords \
  -H "Authorization: Bearer $SEOMONITOR_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["új kulcsszó","másik kulcsszó"],"aiTracked":true}'

Az aiTracked mező jelöli, hogy a kulcsszó beleszámítson-e az AI visibility keretbe. Módosítás: PATCH /api/agent/v1/keywords/:id body: { "aiTracked": true }.

Elemzés indítása

curl -X POST https://seomonitor.hu/api/agent/v1/analyze \
  -H "Authorization: Bearer $SEOMONITOR_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"rankCheck","projectId":1}'

n8n HTTP Request node

Method: GET
URL: https://seomonitor.hu/api/agent/v1/projects
Headers:
  Authorization: Bearer {{$env.SEOMONITOR_AGENT_TOKEN}}
  Content-Type: application/json

Eredmények lekérése

curl "https://seomonitor.hu/api/agent/v1/results?type=content-changes&projectId=1" \
  -H "Authorization: Bearer $SEOMONITOR_AGENT_TOKEN"

Típusok:
  all, rankings, serp, ai-visibility, ai-trends, sov, forecast, competitors, suggestions,
  content-changes, broken-links, cannibalization, vitals, schema, geo-score, eeat, content

MCP tool mapping

seomonitor_list_projects

seomonitor_create_project

seomonitor_update_project

seomonitor_add_keywords

seomonitor_update_keyword

seomonitor_run_analysis

seomonitor_get_results

seomonitor_get_models

Fontos biztonsági szabály

Ügyfél token csak saját fiókhoz kötött adatokat kezel. Ne tedd kliensoldali kódba, publikus repóba vagy megosztott dokumentumba.