Scope-lar və endpoint-lər: AI agentlər, bilik bazası, kömək mərkəzi

Son yeniləmə: 11 noyabr 2026 · 13 dəq oxunur

AI agentləri oxumaq, öyrətmək, dərc etmək, onlardan cavab almaq, bilik bazası və kömək mərkəzi üçün scope-lar. AI agentin dəyişikliyi iki addımdır: ai_agents:write qaralamanı hazırlayır, ai_agents:publish onu canlı edir.

Addımlar

1
Bu məqaləni necə oxumaq
- Yollar https://api.clomni.ai/v1-dən sonra yazılır: GET /v1/agents tam ünvanda https://api.clomni.ai/v1/agents deməkdir. Yolda workspace ID yoxdur, çünki token bir workspace-ə bağlıdır.
- Hər sorğuda Authorization: Bearer clomni_pat_xxx başlığı olur. Tokeni necə almaq: Developer API-də tokenlər və autentifikasiya.
- Risk: aşağı (şəxsi məlumat yoxdur), orta (müştəri məlumatını oxuyur və ya daxili məlumatı dəyişir), yüksək (müştəriyə göndərir, silir, toplu çıxarır, canlı ayarı dəyişir).
- Hər scope review-dan keçir, public app-da da. Ətraflı: Review: scope-ların yoxlanması və rədd səbəbləri.
- «Əlavə verir»: write və manage eyni resursun read-ini də verir. send, delete, publish, assign, run heç nə vermir.
- Endpoint bir neçə scope ilə açılırsa, onlardan biri kifayətdir. Scope çatmasa, API 403 insufficient_scope və cavabda required_scopes qaytarır.
- Hər POST Idempotency-Key başlığı qəbul edir: təkrar sorğu ikinci dəfə icra olunmur.
2
AI agentləri görmək (ai_agents:read)
AI agentləri oxuyur: ayarlar, təlimatlar, qaralama, versiyalar, FAQ-lar (paneldə «Sual-cavab»), ssenarilər (paneldə «Hallar»), test sualları və nəticələri, agentin alətləri və qoşulduğu inbox-lar.
- Risk: aşağı.
- Yoxlama: review-dan keçir, aşağı riskli scope-lara tez baxılır.
- Əlavə verir: başqa scope vermir.
Endpoint-lər:
- GET /v1/ai_agent_faqs: FAQ yazısı siyahısı
- GET /v1/ai_agent_faqs/{faq_id}: FAQ yazısını oxumaq
- GET /v1/ai_agent_tools: AI agent alətlərinin siyahısı
- GET /v1/ai_agent_tools/{ai_agent_tool_id}: AI agent alətini oxumaq
- GET /v1/ai_agents: AI agent siyahısı
- GET /v1/ai_agents/tools: AI agentin işlədə biləcəyi alətlər
- GET /v1/ai_agents/{ai_agent_id}: AI agenti oxumaq
- GET /v1/ai_agents/{ai_agent_id}/draft: AI agentin qaralamasını oxumaq
- GET /v1/ai_agents/{ai_agent_id}/inboxes: AI agentin cavab verdiyi inbox-lar
- GET /v1/ai_agents/{ai_agent_id}/scenarios: Ssenari siyahısı
- GET /v1/ai_agents/{ai_agent_id}/scenarios/{scenario_id}: Ssenarini oxumaq
- GET /v1/ai_agents/{ai_agent_id}/test_questions: Test sualı siyahısı
- GET /v1/ai_agents/{ai_agent_id}/test_runs/{test_run_id}: Test işini oxumaq
- GET /v1/ai_agents/{ai_agent_id}/versions: AI agentin versiyaları
Nümunə:
```
curl "https://api.clomni.ai/v1/ai_agents" \
  -H "Authorization: Bearer clomni_pat_xxx"
```
```
curl "https://api.clomni.ai/v1/ai_agent_faqs" \
  -H "Authorization: Bearer clomni_pat_xxx"
```
3
AI agent qaralaması (ai_agents:write)
AI agent yaradır, qaralamanın ayarlarını dəyişir, qaralamada ssenari saxlayır və silir. Canlı agentə toxunmur: qaralamanı canlıya ai_agents:publish keçirir.
- Risk: orta.
- Yoxlama: review-dan keçir. Bu icazə ilə hansı məlumatı, nə vaxt və nə üçün işlədəcəyinizi konkret yazın.
- Əlavə verir: ai_agents:read də verir.
Endpoint-lər:
- POST /v1/ai_agents: AI agent yaratmaq
- PATCH /v1/ai_agents/{ai_agent_id}/draft: AI agentin qaralamasını dəyişmək
- POST /v1/ai_agents/{ai_agent_id}/draft/scenarios: Qaralamada ssenari saxlamaq
- DELETE /v1/ai_agents/{ai_agent_id}/draft/scenarios/{scenario_id}: Qaralamadan ssenari silmək
Nümunə:
```
curl -X POST "https://api.clomni.ai/v1/ai_agents" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Satış köməkçisi", "description": "Sifariş və çatdırılma suallarına cavab verir", "config": {"product_name": "Demo Store"}}'
```
4
AI agenti öyrətmək (ai_agents:train)
AI agenti öyrədir: FAQ, ssenari və test sualı əlavə edir, dəyişir, silir, test sualı idxal edir, testi işə salır, nəticəni qiymətləndirir, agentin biliyini yenidən qurur. Test və yenidən qurma AI kreditindən çıxılır.
- Risk: orta.
- Yoxlama: review-dan keçir. Bu icazə ilə hansı məlumatı, nə vaxt və nə üçün işlədəcəyinizi konkret yazın.
- Əlavə verir: başqa scope vermir.
Endpoint-lər:
- POST /v1/ai_agent_faqs: FAQ yazısı yaratmaq
- PATCH /v1/ai_agent_faqs/{faq_id}: FAQ yazısını yeniləmək
- DELETE /v1/ai_agent_faqs/{faq_id}: FAQ yazısını silmək
- POST /v1/ai_agents/{ai_agent_id}/scenarios: Ssenari yaratmaq
- PATCH /v1/ai_agents/{ai_agent_id}/scenarios/{scenario_id}: Ssenarini yeniləmək
- DELETE /v1/ai_agents/{ai_agent_id}/scenarios/{scenario_id}: Ssenarini silmək
- POST /v1/ai_agents/{ai_agent_id}/test_questions: Test sualı yaratmaq
- POST /v1/ai_agents/{ai_agent_id}/test_questions/import: Test suallarını idxal etmək
- PATCH /v1/ai_agents/{ai_agent_id}/test_questions/{test_question_id}: Test sualını yeniləmək
- DELETE /v1/ai_agents/{ai_agent_id}/test_questions/{test_question_id}: Test sualını silmək
- PATCH /v1/ai_agents/{ai_agent_id}/test_results/{test_result_id}: Test nəticəsini qiymətləndirmək
- POST /v1/ai_agents/{ai_agent_id}/test_runs: Test işini başlatmaq
- POST /v1/ai_agents/{ai_agent_id}/train: AI agenti yenidən öyrətmək
Nümunə:
```
curl -X POST "https://api.clomni.ai/v1/ai_agent_faqs" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"question": "Çatdırılma neçə günə olur?", "answer": "Bakı daxilində 1 iş günü, regionlara 2-3 iş günü.", "assistant_id": 4}'
```
5
AI agenti dərc etmək (ai_agents:publish)
Canlı agenti dəyişir: qaralamanı dərc edir, köhnə versiyanı bərpa edir, PATCH /v1/ai_agents/{ai_agent_id} ilə ayarları dərhal dəyişir, agenti inbox-a qoşur və ayırır, inbox-dakı iş rejimini dəyişir, agenti silir. Müştəriyə gedən cavablar dəyişdiyi üçün yüksək riskdir.
- Risk: yüksək.
- Yoxlama: review-dan keçir və daha diqqətlə yoxlanır. Ətraflı izah və funksiyanı göstərən qısa video lazımdır, hədəf müddət 2 iş günüdür.
- Əlavə verir: başqa scope vermir.
Endpoint-lər:
- PATCH /v1/ai_agents/{ai_agent_id}: Canlı AI agenti dəyişmək
- DELETE /v1/ai_agents/{ai_agent_id}: AI agenti silmək
- POST /v1/ai_agents/{ai_agent_id}/draft/publish: AI agentin qaralamasını dərc etmək
- POST /v1/ai_agents/{ai_agent_id}/inboxes: AI agenti inbox-a qoşmaq
- PATCH /v1/ai_agents/{ai_agent_id}/inboxes/{inbox_id}: AI agentin inbox-dakı iş rejimini dəyişmək
- DELETE /v1/ai_agents/{ai_agent_id}/inboxes/{inbox_id}: AI agenti inbox-dan ayırmaq
- POST /v1/ai_agents/{ai_agent_id}/versions/{version}/restore: AI agent versiyasını bərpa etmək
Nümunə:
```
curl -X POST "https://api.clomni.ai/v1/ai_agents/4/draft/publish" \
  -H "Authorization: Bearer clomni_pat_xxx"
```
```
curl -X POST "https://api.clomni.ai/v1/ai_agents/4/inboxes" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"inbox": {"inbox_id": 5}}'
```
6
AI agentdən cavab almaq (ai_agents:ask)
AI agentdən öz platformanızda cavab alır, agentin test panelindəki kimi. Heç bir söhbətə heç nə yazılmır. Hər cavab AI kreditindən çıxılır, kredit bitəndə 402 ai_credit_spent gəlir. handoff: true olanda sualı insana ötürün.
- Risk: orta.
- Yoxlama: review-dan keçir. Bu icazə ilə hansı məlumatı, nə vaxt və nə üçün işlədəcəyinizi konkret yazın.
- Əlavə verir: başqa scope vermir.
Endpoint-lər:
- POST /v1/ai_agents/{ai_agent_id}/ask: AI agentdən cavab almaq
Nümunə:
```
curl -X POST "https://api.clomni.ai/v1/ai_agents/4/ask" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"question": "Bəs regionlara?", "history": [{"role": "user", "content": "Çatdırılma neçə günə olur?"}, {"role": "assistant", "content": "Bakı daxilində 1 iş günü."}]}'
```
7
Bilik bazasını görmək (knowledge:read)
Bilik bazasının sənəd və linklərini və onların oxunma vəziyyətini (status, sync_status) oxuyur.
- Risk: aşağı.
- Yoxlama: review-dan keçir, aşağı riskli scope-lara tez baxılır.
- Əlavə verir: başqa scope vermir.
Endpoint-lər:
- GET /v1/knowledge: Bilik bazası sənədləri
- GET /v1/knowledge/{document_id}: Sənədi oxumaq
Nümunə:
```
curl "https://api.clomni.ai/v1/knowledge?assistant_id=4" \
  -H "Authorization: Bearer clomni_pat_xxx"
```
8
Bilik bazasını dəyişmək (knowledge:write)
Linklə veb səhifə və ya fayl əlavə edir və sənədi silir. Sənəd fonda oxunur, hazır olanda status bunu göstərir. Ayrıca yeniləmə endpoint-i yoxdur: səhifə dəyişəndə köhnə sənədi silib yenisini əlavə edin.
- Risk: orta.
- Yoxlama: review-dan keçir. Bu icazə ilə hansı məlumatı, nə vaxt və nə üçün işlədəcəyinizi konkret yazın.
- Əlavə verir: knowledge:read də verir.
Endpoint-lər:
- POST /v1/knowledge: Sənəd və ya link əlavə etmək
- DELETE /v1/knowledge/{document_id}: Bilik bazası sənədini silmək
Nümunə:
```
curl -X POST "https://api.clomni.ai/v1/knowledge" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"document": {"name": "Çatdırılma qaydaları", "external_link": "https://demo-store.example/delivery", "assistant_id": 4}}'
```
9
AI jurnalını oxumaq (ai_logs:read)
AI jurnalını oxuyur: agentin cavab verə bilmədiyi suallar, cavabların yoxlamaları və agentin nəticələri.
- Risk: orta.
- Yoxlama: review-dan keçir. Bu icazə ilə hansı məlumatı, nə vaxt və nə üçün işlədəcəyinizi konkret yazın.
- Əlavə verir: başqa scope vermir.
Endpoint-lər:
- GET /v1/ai_agents/{ai_agent_id}/gaps: AI agentin cavab verə bilmədiyi suallar
- GET /v1/ai_agents/{ai_agent_id}/results: AI agentin nəticələri
- GET /v1/ai_agents/{ai_agent_id}/reviews: AI cavablarının yoxlamaları
- GET /v1/ai_agents/{ai_agent_id}/reviews/{review_id}: AI cavabının yoxlaması
Nümunə:
```
curl "https://api.clomni.ai/v1/ai_agents/4/gaps" \
  -H "Authorization: Bearer clomni_pat_xxx"
```
10
Kömək mərkəzini görmək (help_center:read)
Kömək mərkəzi portallarını, kateqoriyalarını və məqalələrini oxuyur, məqalələrdə axtarır.
- Risk: aşağı.
- Yoxlama: review-dan keçir, aşağı riskli scope-lara tez baxılır.
- Əlavə verir: başqa scope vermir.
Endpoint-lər:
- GET /v1/portals: Kömək mərkəzi portalı siyahısı
- GET /v1/portals/{portal_id}: Portalı oxumaq
- GET /v1/portals/{portal_id}/articles: Məqalə siyahısı
- GET /v1/portals/{portal_id}/articles/{article_id}: Məqaləni oxumaq
- GET /v1/portals/{portal_id}/categories: Kateqoriya siyahısı
- GET /v1/portals/{portal_id}/categories/{category_id}: Kateqoriyanı oxumaq
- GET /v1/search/articles: Kömək mərkəzi məqalələrində axtarış
Nümunə:
```
curl "https://api.clomni.ai/v1/portals" \
  -H "Authorization: Bearer clomni_pat_xxx"
```
11
Kömək mərkəzini dəyişmək (help_center:write)
Məqalə yazır, dəyişir, dərc edir və silir, kateqoriya yaradır, sıranı və portal ayarlarını dəyişir.
- Risk: orta.
- Yoxlama: review-dan keçir. Bu icazə ilə hansı məlumatı, nə vaxt və nə üçün işlədəcəyinizi konkret yazın.
- Əlavə verir: help_center:read də verir.
Endpoint-lər:
- PATCH /v1/portals/{portal_id}: Portalı yeniləmək
- POST /v1/portals/{portal_id}/articles: Məqalə yaratmaq
- POST /v1/portals/{portal_id}/articles/reorder: Məqalələrin sırasını dəyişmək
- PATCH /v1/portals/{portal_id}/articles/{article_id}: Məqaləni yeniləmək
- DELETE /v1/portals/{portal_id}/articles/{article_id}: Məqaləni silmək
- POST /v1/portals/{portal_id}/categories: Kateqoriya yaratmaq
- POST /v1/portals/{portal_id}/categories/reorder: Kateqoriyaların sırasını dəyişmək
- PATCH /v1/portals/{portal_id}/categories/{category_id}: Kateqoriyanı yeniləmək
- DELETE /v1/portals/{portal_id}/categories/{category_id}: Kateqoriyanı silmək
Nümunə:
```
curl -X POST "https://api.clomni.ai/v1/portals/demo-store/articles" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "Sifarişimi necə izləyim?", "content": "Sifariş nömrənizi «Sifarişlərim» bölməsində tapın.", "category_id": 11, "status": "published", "locale": "az"}'
```
12

Kömək mərkəzi haqqında

Müştərilər üçün yardım saytı (portal, kateqoriyalar, məqalələr) 5 noyabr 2026-dan Clomni paketlərində yoxdur və paneldə görünmür. help_center:* scope-ları və endpoint-ləri kataloqda qalır, amma yeni inteqrasiyanı bunun üzərində qurmayın. Müştəri suallarına avtomatik cavab üçün AI agentin bilik bazasını (knowledge:write) və FAQ-larını (ai_agents:train) işlədin.
13
Əlaqəli məqalələr

Sənəd

Developer platforması: bələdçi v1.0 · 41 səhifə Aç Endir

Scope-lar və endpoint-lər: AI agentlər, bilik bazası, kömək mərkəzi

Addımlar

Bu məqaləni necə oxumaq

AI agentləri görmək (ai_agents:read)

AI agent qaralaması (ai_agents:write)

AI agenti öyrətmək (ai_agents:train)

AI agenti dərc etmək (ai_agents:publish)

AI agentdən cavab almaq (ai_agents:ask)

Bilik bazasını görmək (knowledge:read)

Bilik bazasını dəyişmək (knowledge:write)

AI jurnalını oxumaq (ai_logs:read)

Kömək mərkəzini görmək (help_center:read)

Kömək mərkəzini dəyişmək (help_center:write)

Kömək mərkəzi haqqında

Əlaqəli məqalələr

Sənəd