REST API v1: API açarları, autentifikasiya və nümayiş nöqtələri (endpoints)
API açarının yaradılması, Authorization başlığının göndərilməsi, sorğu limitləri və parametrlər, cavab strukturu və xəta kodları ilə bütün v1 endpoints.
Bu ekranı paneldə açREST API v1 paneldə etdiyiniz əməliyyatların çoxunu kod vasitəsilə həyata keçirməyə imkan verir: saytları sadalamaq, taramaları başlatmaq, problemləri çəkmək, AI düzəlişləri açmaq və Pixel qaydalarını, açar sözləri, məzmunu, tərs keçidləri (backlinks), outriç-i, rəqibləri və sosial media paylaşımlarını idarə etmək. Açarlar təşkilata məxsusdur; bir açar yalnız öz təşkilatının məlumatlarını görür. MCP serveri də eyni endpoints-i çağırır.
Ön şərtlər
- Yalnız təşkilatın sahibi (owner) və ya admini açarlar yarada və ləğv edə bilər. Digər rollar API açarları sekmesini görmür.
- API girişi Pro və Agency planlarına daxildir. Planınız buna imkan vermirsə, sekmede Planlara baxın keçidi olan bir bildiriş görünür; yenə də açar yarada bilərsiniz, lakin sorğular 403
plan_requiredxətası qaytaracaq.
API açarının yaradılması
- Tənzimləmələr → Profil → API açarları bölməsini açın.
- Açar adı sahəsində açarın harada istifadə olunacağını təsvir edin (ən azı 2 simvol, məs. "CI").
- Açar taramaları başlatmalı və ya düzəlişlər, qaydalar, açar sözlər və ya məzmun yaratmalıdırsa, yazma sahəsi (write scope) qutusunu işarələyin. Yalnız oxumaq üçün olan açar üçün işarələnməmiş saxlayın.
- Açar yarat düyməsinə klikləyin.
sa_live_ilə başlayan açarı Açarı kopyala düyməsi ilə dərhal kopyalayın. O bir daha göstərilmir; siyahıda yalnız onun Prefiksi saxlanılır.
Bir təşkilatın ən çoxu 20 aktiv açarı ola bilər. Açar sızarsa, siyahıdakı zibil qutusu ikonu (Ləğv et) ilə onu dərhal ləğv edin. Ləğv edilmiş açardan istifadə edən sorğular dərhal 401 xətası alır.
AI tətbiqlərinin OAuth ilə qurduğu bağlantılar bu siyahıda görünmür; onlar AI köməkçinizi bağlayın səhifəsindəki Qoşulmuş köməkçilər siyahısındadır.
Autentifikasiya və əsas URL
- Əsas URL:
https://seoasist.com/api/v1 - Başlıq (Header):
Authorization: Bearer sa_live_… ?api_key=sa_live_…sorğu parametri də qəbul edilir. URL-dəki açarlar loqlara düşə bildiyindən, bunlardan yalnız sınaq üçün istifadə edin.
Səlahiyyət sahələri (scopes): read açarı bütün GET endpoints-i çağıra bilər. write sahəsi POST, PATCH və DELETE sorğularının kilidini açır. Yalnız oxuma açarı ilə edilən yazma sorğusu 403 qaytarır.
Limitlər: hər təşkilat üçün dəqiqədə maksimum 240 sorğu və saatda maksimum 30 AI düzəlişi (POST /sites/{id}/fixes). Bu limit aşıldıqda 429 rate_limited xətası alırsınız.
curl -H "Authorization: Bearer sa_live_..." \
https://seoasist.com/api/v1/sites
Cavab strukturu (Response envelope)
Hər bir uğurlu JSON cavabı belə görünür:
{ "ok": true, "data": {}, "ms": 42 }
data endpoint-in nəticəsini saxlayır və ms milisaniyə ilə sorğu müddətidir. Yeganə istisna sadə mətn (text/plain) qaytaran llms.txt-dir. Xətalar { "ok": false, "error": "<code>", "message": "…" } qaytarır.
Endpoints
Bütün yollar əsas URL-ə nəzərən göstərilmişdir. {id} sayt ID-sidir və onu GET /sites vasitəsilə əldə edə bilərsiniz.
Hesab və saytlar
| Metod | Yol | Sahə | Neyləyir |
|---|---|---|---|
| GET | /me | read | Açarın təşkilatı və səlahiyyət sahələri: orgId, scopes |
| GET | /sites | read | Saytları sadalayır: id, name, domain, url, healthScore, lastCrawlAt, gscProperty, ga4PropertyId, repo, pixelKey … və Search Console mövqe dəyişməsi (movement) |
| GET | /sites/{id} | read | Sayt sahələri + lastCrawl (id, pages, finishedAt), issueTotals, problem qrupları (code, severity, title, count), kod repozitoriyaları (repos), düzəliş kanalları (fixChannels) və yüksələn / düşən sorğular |
| GET | /sites/{id}/data-sources | read | Hər bir məlumat növü üçün aktiv məlumat mənbəyi və onun vəziyyəti |
| POST | /sites/{id}/crawl | write | Taramanı başladır; { crawlId, status: "queued" } qaytarır. Aylıq səhifə kvotası bitdikdə 402 limit_reached |
Problemlər, düzəlişlər və qaydalar
| Metod | Yol | Sahə | Neyləyir |
|---|---|---|---|
| GET | /sites/{id}/issues | read | Qruplaşdırılmış problemlər (totals, groups). ?code= ilə həmin qrupu və nümunə urls əldə edirsiniz; ?limit= var-sayılan olaraq 200-dür, maks 1000 |
| POST | /sites/{id}/issues/{code}/rule-fix | write | Təsir edən hər bir URL-də bir problem kodunu qaydalarla düzəldir (Sayt API, WordPress plagini və ya Pixel tələb olunur) |
| POST | /sites/{id}/fixes | write | AI düzəlişi (PR / MR tapşırığı) açır. Bədən: issueCode və ya instructions (biri mütləqdir), istəyə bağlı repo və model. { jobId, status: "queued" } qaytarır |
| GET | /sites/{id}/fixes | read | Son 50 düzəliş tapşırığı: status, model, repo, prUrl, summary, error … |
| GET | /sites/{id}/pixel/rules | read | Qaydalar |
| POST | /sites/{id}/pixel/rules | write | Qayda əlavə edir. Bədən: kind, matchType (var-sayılan exact), matchPath (var-sayılan /), payload, istəyə bağlı note |
| DELETE | /sites/{id}/pixel/rules/{ruleId} | write | Qaydanı silir; { deleted: true } |
Açar sözlər və məzmun
| Metod | Yol | Sahə | Neyləyir |
|---|---|---|---|
| GET | /sites/{id}/keywords | read | avgPosition, buckets və açar sözlər (position, prevPosition, change, best, url, volume, kd, intent, aiOverview, aiCited …) üstəgəl Search Console movers |
| POST | /sites/{id}/keywords | write | Bədən: { keywords: string[] } (sorğu başına maks 200). { added } qaytarır; artıq izlənilən açar sözlər buraxılır |
| GET | /sites/{id}/keywords/opportunities | read | Fürsət balı (0–100) və fəaliyyət (new / strengthen) ilə açar söz hovuzu; ?limit= var-sayılan 50, maks 300 |
| POST | /sites/{id}/keywords/ideas | write | Bədən: { keywords: string[], note? } (2–60 açar söz). Açar sözləri klasterləşdirir və idea statusu ilə bloq ideyaları yaradır |
| GET | /sites/{id}/content | read | Son 100 məzmun elementi; ?status= ilə filtrləyin |
| POST | /sites/{id}/content | write | Bloq ideyası yaradır. Bədən: title (mütləqdir), targetKeywords?, angle?, generate? (true yazmağı növbəyə qoyur) |
| GET | /sites/{id}/content/{itemId} | read | Bütün sahələri ilə bir məzmun elementi (HTML daxil olmaqla) |
| PATCH | /sites/{id}/content/{itemId} | write | Canlı olmayan bloq yazısını redaktə edir: title, html, faq, metaTitle, metaDescription, excerpt, slug, targetKeywords. Təsdiqlənmiş və ya planlaşdırılmış yazı yenidən baxışa qayıdır. Səhifə yenidən yazmaları və canlı yazılar 422 / 409 not_editable qaytarır |
| POST | /sites/{id}/content/{itemId}/approve | write | Onu təsdiqləyir. scheduledFor (YYYY-MM-DD) ilə status scheduled olur; planlaşdırma avto-dərc yoxlamalarından keçməlidir |
| POST | /sites/{id}/content/{itemId}/publish | write | Dərc tapşırığını növbəyə qoyur. Bədən: channel (wordpress, github, siteapi, manual), live?. Canlı dərc avto-dərc yoxlamalarından keçməlidir; səhifə yenidən yazmaları canlı dərc edilə bilməz |
| GET / POST | /sites/{id}/content/{itemId}/brief | read / write | Saxlanılan tədqiqat brifi / yeni brif (keyword, urls?); aylıq brif kvotasından istifadə edir |
| POST | /sites/{id}/score | read | Məqalə HTML-ni 0–100 arası qiymətləndirir (html, itemId?, keyword?, title?, metaDescription?) |
| POST | /sites/{id}/articles | write | Öz AI-nızın yazdığı məqaləni baxışa göndərir (HTML təmizlənir, maks 300 KB, aylıq məzmun kvotasına daxil edilmir) |
| GET | /sites/{id}/brand | read | Brend profili: ton, auditoriya, qadağan olunmuş sözlər, müəllif |
Tərs keçidlər (Backlinks), outriç və rəqiblər
| Metod | Yol | Sahə | Neyləyir |
|---|---|---|---|
| GET | /sites/{id}/backlinks | read | Tərs keçid profili: xülasə, trend, üst domenlər və lövbərlər (anchors) |
| GET | /sites/{id}/backlinks/links | read | Fərdi tərs keçidlər; ?status= (active, new, lost, toxic, broken), ?limit= var-sayılan 200, maks 1000 |
| POST | /sites/{id}/backlinks/opportunities | write | Rəqiblərə keçid verən, lakin sayta verməyən domenlər; DataForSEO kreditlərini xərcləyir |
| GET / POST | /sites/{id}/outreach | read / write | Outriç daxilolmaları / yeni prospekt (domain, url?, contactName?, contactEmail?, notes?, rank?) |
| PATCH | /sites/{id}/outreach/{outreachId} | write | Status (idea, contacted, replied, won, lost), əlaqə məlumatları və ya qeydlər |
| GET / POST | /sites/{id}/competitors | read / write | Rəqiblər / yeni rəqib domeni (sayt başına maks 20) |
| GET | /sites/{id}/competitors/gap | read | Məzmun boşluğu; ?competitorId=, ?minVolume=, ?maxKd=, ?limit= |
| GET | /sites/{id}/competitors/{competitorId}/keywords | read | Həm saytın, həm də rəqibin sıralandığı açar sözlər |
Monitorinq və AI
| Metod | Yol | Sahə | Neyləyir |
|---|---|---|---|
| GET | /sites/{id}/geo | read | AI görünürlük xülasəsi; ?days= var-sayılan 90 |
| GET | /sites/{id}/monitors | read | uptime (30 gün), index sayları və changes30d |
| GET | /sites/{id}/ai-access | read | Son AI bot giriş yoxlaması: checkedAt, result, policy |
| GET | /sites/{id}/llms.txt | read | Genere edilmiş llms.txt sadə mətn kimi |
Təşkilat
| Metod | Yol | Sahə | Neyləyir |
|---|---|---|---|
| GET | /notifications | read | { unread, items }; ?unread=1 yalnız oxunmamışları qaytarır, ?limit= var-sayılan 50, maks 200 |
| POST | /notifications/read | write | Bədən: { ids?: string[] }; ids olmadan hamısı oxunmuş kimi işarələnir |
| GET | /todo | read | İnsanı nə gözləyir və avtomatlaşdırma nə etdi; ?siteId=, ?days= (var-sayılan 7) |
| GET | /agent/tasks | read | Planlardan gələn icra vaxtı çatmış əl tapşırıqları; ?siteId= |
| POST | /agent/tasks/{taskId}/complete | write | Qeyd ilə əl tapşırığını bağlayır (note, ən azı 10 simvol) |
| POST | /agent/activity | write | Fəaliyyət lentinə bir sətir yazır (message, siteId?) |
| GET | /reports | read | Son 50 hesabat və onların ictimai url-ləri; ?siteId= ilə filtrləyin |
| GET | /social/accounts, /social/posts, /social/insights | read | Sosial hesablar, paylaşımlar və hesab analitikası (paylaşılan sosial media mühərrikindən) |
| POST | /social/posts, /social/posts/{postId}/schedule, /social/campaign | write | Paylaşımlar yaratmaq, tarixləri təyin etmək və kampaniya seriyaları; paylaşımlar baxışa düşür |
Məzmun statusları: idea, planned, generating, draft, review, approved, scheduled, published, failed, archived. Qayda kind dəyərləri: title, meta_description, canonical, robots, h1, img_alt, og, json_ld, hreflang, redirect, lang, attr, link, meta. matchType: exact, prefix, regex, all.
CoSuite vasitəsilə hesablaşan təşkilatlarda sayt limiti xaricindəki saytlar yalnız oxunandır. Onlara yazan hər bir sorğu 403 site_read_only qaytarır; oxuma sorğuları işləməyə davam edir.
Nümunələr
AI düzəlişini başladın:
curl -X POST https://seoasist.com/api/v1/sites/SITE_ID/fixes \
-H "Authorization: Bearer sa_live_..." \
-H "Content-Type: application/json" \
-d '{"issueCode":"missing_meta_description"}'
İzləməyə açar sözlər əlavə edin:
curl -X POST https://seoasist.com/api/v1/sites/SITE_ID/keywords \
-H "Authorization: Bearer sa_live_..." \
-H "Content-Type: application/json" \
-d '{"keywords":["seo tool","site audit"]}'
Taramalar və düzəlişlər kimi tapşırıqlar növbəyə alınır. Nəticəni uyğun GET endpoint-də izləyin (/sites/{id}, /sites/{id}/fixes).
Xəta kodları
| HTTP | error | Nə vaxt |
|---|---|---|
| 400 | bad_request | Bədən sahəsi çatışmır və ya yanlışdır (məs. title, kind, keywords[]) |
| 401 | unauthorized | Açar çatışmır, keçərsizdir və ya ləğv edilib |
| 402 | limit_reached | Plan kvotası dolub (məs. aylıq tarana səhifələr, izlənilən açar sözlər, tədqiqat brifləri) |
| 403 | plan_required | Planın API girişi yoxdur (Pro və ya Agency lazımdır) |
| 403 | forbidden | Yalnız oxuma açarı ilə yazma sorğusu |
| 403 | site_read_only | Sayt CoSuite sayt limitindən kənardadır; yazma deaktiv edilib |
| 404 | not_found | Sayt və ya qeyd bu təşkilata məxsus deyil, mövcud deyil və ya endpoint naməlumdur |
| 409 | conflict | Məsələn, saytın kod repozitoriyası yoxdur, kod hostu qoşulmayıb, əlçatan AI modeli yoxdur, AI ilə işarələnmiş iddialar hələ təsdiqlənməyib və ya səhifə yenidən yazması canlı yayıma göndərilib |
| 409 | publish_gate | Yazı avto-dərc yoxlamalarından keçmədi; baxışa qayıtdı və sahibinə bildiriş göndərildi |
| 409 / 422 | not_editable | Redaktə edilə bilməyən məzmun (canlı yazı və ya səhifə yenidən yazması) |
| 413 | too_large | Bədən çox böyükdür (məs. məqalə HTML-i 300 KB-dan çoxdur) |
| 422 | no_ai | Əməliyyat üçün AI əlçatan deyil |
| 429 | rate_limited | Dəqiqədə 240 sorğu və ya saatda 30 düzəliş limiti aşıldı |
| 500 | internal | Gözlənilməz xəta. Təhlükəsizlik üçün detallar qaytarılmır |
Tez-tez verilən suallar
Açarımı itirdim. Onu yenidən görə bilərəmmi?
Xeyr. Açarlar yalnız heş (hash) kimi saxlanılır. Köhnəni ləğv edin və yeni açar yaradın.
Eyni açarı MCP müştərisində istifadə edə bilərəmmi?
Bəli. İki yol var:
- Uzaqdan MCP (quraşdırma tələb olunmur, tövsiyə edilir):
https://seoasist.com/api/mcp. Bu URL-i claude.ai, Claude Desktop, ChatGPT, Cursor və ya VS Code-da konnektor kimi əlavə edin; SEOAsist daxilolma pəncərəsi açılır, siz təşkilatı və icazələri seçirsiniz və açarı kopyalamırsınız. Addım-baddım təlimatlar və bir kliklə quraşdırma keçidləri paneldə Tənzimləmələr → İnteqrasiyalar → AI köməkçinizi bağlayın səhifəsindədir. Claude Code-daclaude mcp add --transport http seoasist https://seoasist.com/api/mcpəmrini icra edin və ilk istifadədə/mcpilə daxil olun. Daxilolma pəncərəsinin açıla bilmədiyi yerlərdə (serverlər, CI), API açarını--header "Authorization: Bearer sa_live_..."ilə göndərin. - Lokal (stdio): API açarları sekmesindəki MCP serveri görünüşü Claude Desktop, Claude Code və Cursor üçün hazır konfiqurasiya verir; açarı
SEOASIST_API_KEYdəyişəninə yerləşdirirsiniz.
Qoşulduqdan sonra hazır seo_round, content_from_gap, backlink_outreach, agent_tasks və weekly_report əmrləri AI tətbiqinin əmr menyusunda görünür. MCP alətləri eyni endpoints-i çağırır; yazma alətləri üçün yazma sahəsi olan açar lazımdır. Səhifə yenidən yazmaları (page_update) API vasitəsilə canlı dərc edilə bilməz; yalnız bloq yazıları dərc olunur. Bütün alətlər, sahələr və xəta kodları üçün MCP arayışına baxın; tətbiq başına quraşdırma üçün AI-nızı bağlayın bölməsinə baxın.
Onu birbaşa brauzerdən çağıra bilərəmmi?
API Access-Control-Allow-Origin: * başlığı qaytarır. Yenə də açarı heç vaxt ictimai səhifəyə yerləşdirməyin; açarı görən hər kəs təşkilatınızın məlumatlarına daxil ola bilər.
Əlaqəli məqalələr
- Audit problemlərini qəsdən edilmiş kimi qəbul etmək və onları avtomatik həll etməkQəsdən saxladığınız problemləri necə "Qəsdən" (Intentional) olaraq qeyd etmək, bunu geri qaytarmaq və qaydalar və ya GitHub pull request ilə problemləri avtomatik həll etmək.
- Planlar, aylıq səhifə kvotası və daxil olan SEOAsist AI zəngləriFree, Starter, Pro və Agency planlarının limitləri, aylıq tarama kvotası, daxil olan SEOAsist AI zəngləri və platforma məlumat sorğularının necə hesablanması, ödəniş qaydası və istifadəyə nəzarət.
- Sayt API sənədi (seoasist-site-api/1)SEOAsist Sayt API spesifikasiyası: autentifikasiya və HMAC imzalanması, dörd sonluq (endpoint), qayda növləri və hazır Next.js/PHP nümunələri.
- MCP server: end-point, autentifikasiya, alətlər və hazır əmrlərSEOAsist uzaq MCP serverinin URL ünvanı, OAuth 2.1 və ya API açarı ilə autentifikasiya, əhatə dairələri (scopes), bütün alətlər, beş hazır əmr, qaydalar, yerli stdio paketi və xəta kodları.
- Məzmun studiyası: yazılar, səhifə təkmilləşdirmələri, E-E-A-T və dərc etməAçar sözləri yazı ideyalarına çevirin, yazılarınızı hazırlayıb təqvimə paylayın, redaktorda E-E-A-T xalını və doğrulama nişanlarını nəzərdən keçirin, mövcud səhifələri mənbəyə əsaslanaraq genişləndirin və WordPress, Site API, GitHub və ya Shopify-da dərc edin.