واجهة برمجة تطبيقات قاعدة المعرفة #

قاعدة معرفتك هي ما يقرأ منه الذكاء الاصطناعي. وهي تتكون من جزأين، وتغطي هذه الصفحة كلاً منهما:

• مصادر المعرفة (/kb-sources) — صفحات الويب والمستندات التي تقوم برفعها إلى المنصة. يتم قراءة كل منها، وتقسيمها إلى أقسام، وتحويلها إلى أسئلة شائعة يمكن للذكاء الاصطناعي الخاص بك الإجابة عليها.
• مجموعات المعرفة (/kb-groups) — حزم مسماة من الأسئلة الشائعة التي يمكنك تطبيقها على وكيل أو حملة في استدعاء واحد، بحيث يمكن إعادة استخدام مجموعة المعرفة التي قمت بتنظيمها بالفعل على الوكيل التالي الذي تنشئه.

تستقر الأسئلة الشائعة التي ينتجها المصدر في نفس المكتبة التي توجد بها الأسئلة التي تكتبها يدويًا، لذا بمجرد انتهاء الاستيراد، يمكنك قراءتها وتعديلها وربطها باستخدام واجهة برمجة تطبيقات الأسئلة الشائعة.

جميع نقاط النهاية أدناه نسبية إلى عنوان URL الأساسي https://api.youraiconnector.com/v1. يجب أن تكون كل طلبية مصادقاً عليها — راجع الوصول إلى واجهة برمجة التطبيقات والمصادقة. الوصول إلى واجهة برمجة التطبيقات هو ميزة مدفوعة؛ وبدونها، يتم رفض الطلبات مع 403.

الاستيراد يستهلك رصيداً. قراءة صفحة أو مستند وكتابة أسئلة شائعة منه يستهلك رصيداً، يتناسب تقريباً مع حجم المحتوى الموجود. استخدم تقدير تكلفة الاستيراد قبل البدء في عملية زحف كبيرة.

كيف يعمل الاستيراد #

الاستيراد هو مهمة في الخلفية، وليس شيئاً ينتهي أثناء انتظارك. تجيب كل نقطة نهاية للاستيراد فوراً بـ source_id، وتقوم أنت بالاستعلام عن ذلك المصدر حتى ينتهي:

1. بدء الاستيراد — POST /kb-sources/url (صفحة واحدة)، أو POST /kb-sources/file (مستند مرفوع)، أو POST /kb-sources/bulk-import (ما يصل إلى 100 صفحة). ستحصل على معرف المصدر و status: "queued".
2. الاستعلام — GET /kb-sources/{sourceId} حتى لا تعود status تساوي queued أو processing.
3. قراءة الأسئلة الشائعة — عندما تكون الحالة ready، تكون الإدخالات التي أنتجها المصدر موجودة في مكتبة الأسئلة الشائعة الخاصة بك: GET /faqs.

يقدم كل مصدر إحدى هذه الحالات:

الإلحاق أثناء الاستيراد. مرر autoLinkToAgentId في أي نقطة نهاية للاستيراد وسينضم المصدر — بالإضافة إلى كل سؤال شائع ينتجه — إلى معرفة ذلك الوكيل في نفس الاستدعاء، دون الحاجة إلى خطوة ربط لاحقة. يقوم autoLinkToCampaignId بنفس الشيء لحملة كلاسيكية. الربط هو محاولة بأفضل جهد: المعرف الذي لا وجود له، أو الذي ينتمي لحساب آخر، يتم تخطيه بصمت ويستمر الاستيراد في العمل، لذا تأكد من الربط عن طريق قراءة بيانات الوكيل مرة أخرى.

استيراد صفحة ويب #

POST /kb-sources/url

يضيف صفحة ويب واحدة إلى قاعدة معرفتك.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/url?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/url", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/pricing",
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { source_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://example.com/pricing",
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
source_id = res.json().get("source_id")

الاستجابة — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued",
  "batch_id": "batch_9f2a"
}

قم باستطلاع source_id باستخدام التحقق من مصدر حتى تصبح الحالة ready أو failed.

إذا كانت الصفحة نفسها موجودة بالفعل في قاعدة معرفتك، فلن يتم وضع أي شيء جديد في قائمة الانتظار وستحصل على 200 بدلاً من ذلك — وإذا طلبت رابطاً تلقائياً، فسيتم ربط المصدر الموجود لك على أي حال:

{
  "success": true,
  "status": "exists",
  "skipped_duplicate": 1
}

يؤدي فقدان url، أو إذا كان العنوان ليس عنوان http/https صالحاً، إلى إرجاع 400.

استيراد مستند مرفوع #

POST /kb-sources/file

يضيف مستنداً موجوداً بالفعل في مساحة تخزين ملفات حسابك كمصدر معرفة. الأنواع المدعومة: PDF و DOCX و TXT و MD و CSV و XLSX.

لا يحمل هذا الطرف (endpoint) الملف. لا يوجد رفع متعدد الأجزاء (multipart)، ولا جسم base64، ولا تنزيل من رابط URL: أنت ترسل موقع تخزين ملف موجود بالفعل، ويجب أن يكون موجوداً ضمن مجلد الرفع الخاص بك (يجب أن يبدأ storage_path بـ users/{your user id}/uploads/) وإلا سيتم رفض الطلب بـ 403. تضع لوحة التحكم الملفات هناك عند سحبها وإفلاتها. إذا لم تكن لديك طريقة لوضع ملف هناك، فقم باستيراد صفحة ويب باستخدام استيراد صفحة ويب بدلاً من ذلك.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/file?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storage_path": "users/abc123uid/uploads/handbook.pdf",
    "filename": "handbook.pdf",
    "mime_type": "application/pdf",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

الاستجابة — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}

التحقق من مصدر #

GET /kb-sources/{sourceId}

الاستطلاع الذي يلي كل عملية استيراد وتحديث. كرره حتى تصبح الحالة ready أو failed.

cURL

curl "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const source = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
source = res.json()

الاستجابة

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "ready",
  "faq_count": 24,
  "section_count": 31,
  "error_message": null
}

حذف مصدر #

DELETE /kb-sources/{sourceId}

يزيل مصدر معرفة واحداً. افتراضياً، يتم الاحتفاظ بالأسئلة الشائعة التي أنتجها — أضف delete_faqs=true لإزالتها أيضاً.

معلمات الاستعلام

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?delete_faqs=true&apiKey=YOUR_API_KEY"

الاستجابة

{
  "success": true,
  "faqs_deleted": 24
}

faqs_deleted هي 0 ما لم تطلب delete_faqs=true.

استيراد صفحات متعددة دفعة واحدة #

POST /kb-sources/bulk-import

يضيف ما يصل إلى 100 صفحة ويب في طلب واحد. يمكن أن يحتوي حسابك على ما يصل إلى 5,000 صفحة في انتظار الاستيراد في وقت واحد (حد الاستيراد الخاص بحسابك)، مع احتساب الصفحات الموجودة بالفعل في قائمة الانتظار أو التي يتم قراءتها. يتم رفض أي طلب يتجاوز هذا الحد مع 400 و error_code: kb_import_page_limit، ولا يتم وضع أي شيء من ذلك الطلب في قائمة الانتظار. تتطلب عمليات الاستيراد التي تزيد عن 5,000 صفحة موافقة، لذا اتصل بالدعم لرفع الحد. هذا هو الإجراء المعتاد بعد اكتشاف الصفحات على موقع ويب أو العثور على صفحات جديدة على موقع ويب. يتم تخطي الصفحات الموجودة بالفعل في قاعدة معرفتك بدلاً من تكرارها (وتظل مرتبطة بالوكيل عندما طلبت ذلك).

يتم رفض عملية الاستيراد التي لا يستطيع حسابك دفع تكاليفها قبل وضع أي شيء في قائمة الانتظار، مع 402 و error_code: kb_import_insufficient_credits (تحتوي الاستجابة أيضاً على required_credits و available_credits و waiting_pages). تُحتسب كل صفحة كجزء واحد على الأقل لهذا الفحص، كما تُحتسب الصفحات التي تنتظر الاستيراد بالفعل، لأنها لا تُحاسب إلا عند معالجتها. الحسابات التي تم إعداد التعبئة التلقائية لها لا يتم رفضها بناءً على رصيدها. الحسابات التي تستخدم مفتاح الذكاء الاصطناعي الخاص بها لا يتم رفضها أيضاً، ما لم تكن تعمل على فئة Max، والتي يتم محاسبتها بالرصيد. بالنسبة للحساب الفرعي، available_credits هو null.

استيراد أكثر من 100 صفحة يعني إجراء عدة طلبات. أرسل حجم التحديد بالكامل كـ plannedTotal في الطلب الأول. يغطي حد الصفحات وفحص الرصيد بعد ذلك التحديد بالكامل في ذلك الطلب، لذا يتم رفض عملية الاستيراد التي لا يمكن إكمالها قبل وضع أي صفحة في قائمة الانتظار، بدلاً من التوقف في منتصف الطريق. عند قبول الطلب الأول، تتضمن استجابته import_session: أرسله مرة أخرى كـ importSession في كل طلب لاحق لنفس التحديد. تتخطى تلك الطلبات بعد ذلك فحص الرصيد المسبق لما يصل إلى العدد المعتمد من الصفحات، لمدة ساعة واحدة. لا يزال حد الصفحات سارياً، ولا تزال كل صفحة تُحاسب عند معالجتها.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/pricing", "https://example.com/faq"],
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/bulk-import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: ["https://example.com/pricing", "https://example.com/faq"],
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { queued_source_ids } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/bulk-import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "urls": ["https://example.com/pricing", "https://example.com/faq"],
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
queued_source_ids = res.json()["queued_source_ids"]

الاستجابة — 202 Accepted

{
  "success": true,
  "batch_id": "batch_9f2a",
  "queued": 2,
  "skipped_duplicate": 0,
  "queued_source_ids": ["kb_src_abc123", "kb_src_def456"]
}

استعلم عن كل معرف في queued_source_ids باستخدام التحقق من مصدر. إرسال مصفوفة urls فارغة، أو إدخال ليس نصياً، أو أكثر من 100 إدخال يعيد 400.

حذف مصادر متعددة دفعة واحدة #

POST /kb-sources/bulk-delete

يزيل ما يصل إلى 2000 مصدر معرفة في طلب واحد. تتم عملية الإزالة في الخلفية وستتلقى بريداً إلكترونياً عند انتهائها.

يؤدي الحذف المجمع دائمًا إلى إزالة الأسئلة الشائعة أيضًا. على عكس حذف مصدر، الذي يحتفظ بها ما لم تطلب خلاف ذلك، يقوم نقطة النهاية هذه بحذف كل مصدر مع الأسئلة الشائعة التي أنتجها. لا يوجد خيار للاحتفاظ بها.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-delete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceIds": ["kb_src_abc123", "kb_src_def456"],
    "domainLabel": "example.com"
  }'

الاستجابة — 202 Accepted

{
  "success": true,
  "batch_id": "del_batch_31a",
  "queued": 2
}

اكتشاف الصفحات على موقع ويب #

POST /kb-sources/discover-pages

يستكشف موقع ويب بدءًا من عنوان واحد ويسرد الصفحات التي تم العثور عليها في نفس النطاق، مع تقديم رأي حول ما إذا كان الأمر يستحق الاستيراد. لا يتم استيراد أي شيء ولا يتم تحديد أي شيء نيابة عنك — هذه هي خطوة “ما الموجود في هذا الموقع” التي تقوم بتشغيلها قبل اتخاذ قرار بشأن ما يجب إرساله إلى استيراد صفحات متعددة دفعة واحدة.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/discover-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "maxPages": 100 }'

الاستجابة

{
  "success": true,
  "source_type": "sitemap",
  "pages": [
    {
      "url": "https://example.com/pricing",
      "title": "Pricing",
      "depth": 1,
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ]
}

الاستكشاف هو جهد بأفضل ما يمكن. إذا تعذرت قراءة الموقع، تظل الاستجابة 200، مع success: false، وقائمة pages فارغة، ورسالة error. تحقق من success قبل قراءة pages.

فقدان url يؤدي إلى إرجاع 400.

تقدير تكلفة الاستيراد #

POST /kb-sources/estimate-cost

يحسب عدد الرصيد الذي سيستهلكه استيراد مقترح، قبل الالتزام به. يتم جلب الصفحات وقراءة المستندات لقياس حجمها، ولكن لا يتم استيراد أي شيء ولا يستهلك التقدير نفسه أي رصيد.

حقول الطلب

أرسل urls أو files أو كليهما.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/estimate-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://example.com/pricing"] }'

الاستجابة

{
  "success": true,
  "estimates": [
    { "ref": "https://example.com/pricing", "chunks": 7, "credits": 7 }
  ],
  "total_chunks": 7,
  "total_credits": 7,
  "affordable": true,
  "required_credits": 7,
  "available_credits": 120,
  "checked_chunks": 7,
  "waiting_pages": 0,
  "max_affordable_chunks": 120
}

يعكس كل صف عنوان URL أو مسار التخزين في ref حتى تتمكن من مطابقته مع مدخلاتك. الصفحة أو الملف الذي تعذر قراءته يحصل أيضاً على صف، ويُحتسب كجزء واحد، مع وجود error عليه.

يخبرك affordable ما إذا كان حسابك يستطيع دفع تكاليف هذا التقدير، مع احتساب الصفحات التي تنتظر الاستيراد بالفعل (waiting_pages). max_affordable_chunks هو أكبر عدد من الأجزاء الإضافية التي يمكن دفع تكاليفها، لذا يمكنك مقارنة إجمالي تراكمي عند تقدير تحديد كبير في عدة طلبات. يكون null عندما لا يقيدك رصيدك (تم إعداد التعبئة التلقائية، أو مفتاح الذكاء الاصطناعي الخاص بك أقل من فئة Max)، ويكون دائماً null للحساب الفرعي، الذي يحصل على affordable فقط (أرسل prior_chunks بحيث يغطي التحديد بالكامل) و null available_credits.

إيقاف عملية استيراد #

POST /kb-sources/cancel-import

يُوقف الصفحات التي لا تزال تنتظر في قائمة انتظار الاستيراد — وهو زر “إيقاف الاستيراد” لعملية زحف تبين أنها أكبر مما كنت تتوقع. إلغاء صفحة منتظرة لا يكلف شيئاً، لأنها لم تُقرأ بعد.

الصفحات التي يجري معالجتها بالفعل لا يتم إيقافها: فعملها قيد التنفيذ ويتم احتساب تكلفتها في كلتا الحالتين، لذا فهي تكتمل. يوضح الرد عدد تلك الصفحات.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/cancel-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "host": "docs.example.com" }'

الاستجابة

{
  "success": true,
  "cancelled": 412,
  "in_flight": 3
}

استئناف عملية استيراد متوقفة مؤقتاً #

POST /kb-sources/resume-import

يعيد تشغيل عملية استيراد تم إيقافها مؤقتاً لأن مفتاح الذكاء الاصطناعي الخاص بك توقف عن العمل.

استدعاء هذا يعتبر موافقة منك على إنهاء عملية الاستيراد باستخدام أي مفتاح نشط حالياً — وهو ما قد يعني استهلاك أرصدة المنصة إذا كان مفتاحك الخاص لا يزال معطلاً.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/resume-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

الاستجابة

{
  "success": true,
  "resumed": 58
}

العثور على صفحات جديدة على موقع إلكتروني #

POST /kb-sources/refresh-domain

يستكشف موقعاً إلكترونياً قمت بالاستيراد منه بالفعل ويبلغ فقط عن الصفحات التي ليست في قاعدة معارفك بعد، مع تقديم نفس التوصية لكل منها كما في اكتشاف الصفحات. لا يتم استيراد أي شيء ولا يتم تغيير أي شيء.

عمليتا المتابعة هما استدعاءان منفصلان عمداً، لذا فإن التراجع عن هذه العملية لا يكلف شيئاً:

• استورد الصفحات الجديدة التي تريدها باستخدام استيراد صفحات متعددة دفعة واحدة؛
• أعد قراءة الصفحات التي تمتلكها بالفعل باستخدام تحديث كل صفحة على موقع إلكتروني.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'

الاستجابة

{
  "success": true,
  "source_type": "sitemap",
  "discovered": 249,
  "new_pages": [
    {
      "url": "https://example.com/new-guide",
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ],
  "new_urls_queued": 0,
  "existing_refresh_queued": 249
}

مثل الاكتشاف، يفشل هذا بهدوء: الموقع الذي لا يمكن قراءته لا يزال يعيد 200، مع success: false، وnew_pages فارغ، وerror. يؤدي وجود baseUrl مفقود أو فارغ إلى إرجاع 400.

تحديث كل صفحة على موقع إلكتروني #

POST /kb-sources/trigger-domain-refresh

يعيد قراءة كل صفحة استوردتها بالفعل من موقع إلكتروني، بحيث تتبع الأسئلة الشائعة الخاصة به محتوى الموقع الحالي: يتم تحديث الأقسام التي تغيرت، وإضافة أقسام جديدة، وحذف الأقسام التي تمت إزالتها.

يضع هذا العمل في قائمة الانتظار ويعود فوراً. اتبعه بـ تتبع تحديث الموقع الإلكتروني، وأوقفه بـ إيقاف تحديث الموقع الإلكتروني.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/trigger-domain-refresh?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'

الاستجابة

{
  "success": true,
  "queued": 249
}

تتبع تحديث الموقع الإلكتروني #

GET /kb-sources/domain-refresh-status

مدى تقدم تحديث الموقع الإلكتروني، حتى تتمكن من عرض التقدم مثل “221 من 249”.

معلمات الاستعلام

cURL

curl "https://api.youraiconnector.com/v1/kb-sources/domain-refresh-status?baseUrl=https://example.com&apiKey=YOUR_API_KEY"

الاستجابة

{
  "success": true,
  "job": {
    "domainBatchId": "job_7c1e",
    "host": "example.com",
    "total": 249,
    "pending": 28,
    "succeeded": 219,
    "failed": 2,
    "skippedDuplicate": 0,
    "status": "refreshing",
    "startedAtIso": "2026-06-15T09:00:00.000Z"
  }
}

تكون job هي null عندما لا يكون هناك تحديث قيد التشغيل لهذا الموقع. الصفحات التي تم الانتهاء منها حتى الآن هي total ناقص pending. المهمة status هي واحدة من refreshing (لا تزال تعمل عبر الصفحات)، أو deduplicating (مرحلة التنظيف في النهاية)، أو الحالة النهائية completed، أو failed، أو cancelled. احتفظ بـ domainBatchId — فهي ما تمرره إلى نقطة نهاية الإلغاء.

يؤدي وجود baseUrl مفقود أو فارغ إلى إرجاع 400.

إيقاف تحديث موقع إلكتروني #

POST /kb-sources/refresh-domain/cancel

يوقف تحديث موقع إلكتروني لا يزال يعمل على معالجة صفحاته. الصفحات التي انتهت بالفعل تحتفظ بمحتواها المحدث؛ أما الصفحات التي لم تبدأ بعد فيتم إسقاطها، والصفحات التي كانت قيد إعادة القراءة تعود إلى حالتها السابقة.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain/cancel?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jobId": "job_7c1e" }'

الاستجابة

{
  "success": true,
  "status": "cancelled",
  "cancelled_units": 28,
  "sources_reset": 3,
  "sources_cancelled": 25
}

إلغاء العملية مرتين غير ضار — حيث يبلغ الاستدعاء الثاني عن نفس الحالة النهائية. بمجرد انتقال التحديث إلى مرحلة التنظيف، لا يمكن إيقافه بعد الآن، ويأتي الرد بـ success: false و reason: "already_finalizing". الـ jobId المفقود يرجع 400، والوظيفة التي ليست في حسابك ترجع 404.

تحديث مصدر واحد #

POST /kb-sources/{sourceId}/refresh

يعيد قراءة صفحة ويب قمت باستيرادها مسبقاً ويجعل الأسئلة الشائعة (FAQs) الخاصة بها متوافقة مع المحتوى الحالي للصفحة: يتم تحديث الأقسام المتغيرة، وإضافة أقسام جديدة، وإسقاط الأقسام المحذوفة.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123/refresh?apiKey=YOUR_API_KEY"

الاستجابة — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}

استعلم عن المصدر حتى تخرج حالته من queued و processing. معرف المصدر الذي ليس في حسابك يرجع 404.

اختيار الصفحات الأكثر صلة #

POST /kb-sources/select-relevant-pages

يطلب من الذكاء الاصطناعي اختيار الصفحات الخمس، من قائمة المرشحين، التي تصف النشاط التجاري بشكل أفضل — تُستخدم عند إنشاء دليل حملة من موقع إلكتروني. هذا يستهلك أرصدة.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/select-relevant-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "homeUrl": "https://example.com",
    "urls": ["https://example.com/about", "https://example.com/pricing"]
  }'

الاستجابة

{
  "success": true,
  "pages": [
    { "url": "https://example.com/pricing", "title": "Pricing", "type": "pricing" }
  ]
}

هذا مساعد، وليس مورداً: عند الفشل، فإنه لا يزال يجيب بـ 200، مع success: false، وقائمة pages فارغة ورسالة error.

مجموعات المعرفة #

تُعد مجموعة المعرفة حزمة مسماة من الأسئلة الشائعة — مثل “الشحن والإرجاع”، “التأهيل” — التي يمكنك تطبيقها على وكيل أو حملة في استدعاء واحد. تحتفظ المجموعة بمراجع، وليس نسخاً: تظل الأسئلة الشائعة نفسها في مكتبتك الموحدة، لذا فإن تعديل أحدها باستخدام واجهة برمجة تطبيقات الأسئلة الشائعة يؤدي إلى تحديثه في كل مكان يُستخدم فيه.

لا يؤدي تطبيق مجموعة ما إلا إلى إضافة ما هو مفقود، لذا فإن تطبيق نفس المجموعة مرتين لا يسبب أي ضرر، وستعود added_count كـ 0 في المرة الثانية.

إنشاء مجموعة معرفة #

POST /kb-groups

ينشئ مجموعة. تبدأ المجموعة فارغة — أضف إليها أسئلة شائعة باستخدام إضافة سؤال شائع إلى مجموعة.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping and returns" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-groups", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Shipping and returns" }),
});
const { group_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Shipping and returns"},
)
group_id = res.json()["group_id"]

الاستجابة — 201 Created

{
  "success": true,
  "group_id": "kbg_abc123"
}

إعادة تسمية مجموعة معرفة #

PUT /kb-groups/{groupId}

يغير اسم المجموعة. تظل الأسئلة الشائعة الموجودة فيها دون تغيير.

حقول الطلب

cURL

curl -X PUT "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping, returns and refunds" }'

الاستجابة

{
  "success": true,
  "group_id": "kbg_abc123",
  "name": "Shipping, returns and refunds"
}

حذف مجموعة معرفة #

DELETE /kb-groups/{groupId}

يحذف المجموعة. تتم إزالة الحزمة فقط — تظل الأسئلة الشائعة الموجودة فيها في مكتبتك، وأي شيء تم تطبيق المجموعة عليه مسبقاً يحتفظ بتلك الأسئلة الشائعة.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY"

الاستجابة

{
  "success": true
}

إضافة أسئلة شائعة إلى مجموعة #

POST /kb-groups/{groupId}/faqs

يضع سؤالاً شائعاً موجوداً ضمن مجموعة. هذا الإجراء يغير الحزمة فقط — ولا يربط السؤال الشائع بأي وكيل (Agent) بحد ذاته؛ استخدم المجموعة للقيام بذلك.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "faq_id": "aBcD1234eFgH5678" }'

الاستجابة

{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}

إزالة سؤال شائع من مجموعة #

DELETE /kb-groups/{groupId}/faqs/{faqId}

يخرج سؤالاً شائعاً من مجموعة. لا يتم حذف السؤال الشائع نفسه، ويحتفظ الوكلاء الذين تم تطبيق المجموعة عليهم مسبقاً بهذا السؤال.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY"

الاستجابة

{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}

تطبيق مجموعة على وكيل (Agent) #

POST /kb-groups/{groupId}/apply-to-agent

يضيف كل سؤال شائع في المجموعة إلى معرفة وكيل الذكاء الاصطناعي في استدعاء واحد — وهي الطريقة السريعة لمنح وكيل جديد قاعدة معرفية قمت بتنظيمها مسبقاً.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent_id: "ag7HkQ2ZpLxR3mNb" }),
  }
);
const { added_count } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"agent_id": "ag7HkQ2ZpLxR3mNb"},
)
added_count = res.json()["added_count"]

الاستجابة

{
  "success": true,
  "group_id": "kbg_abc123",
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "added_count": 12
}

added_count هو عدد الأسئلة الشائعة التي تمت إضافتها فعلياً — 0 عندما تكون المجموعة فارغة أو مطبقة بالفعل.

تطبيق مجموعة على حملة #

POST /kb-groups/{groupId}/apply-to-campaign

نسخة الحملة الكلاسيكية من الاستدعاء أعلاه. في الحسابات القائمة على الوكلاء، استخدم تطبيق مجموعة على وكيل بدلاً من ذلك.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign123" }'

الاستجابة

{
  "success": true,
  "group_id": "kbg_abc123",
  "campaign_id": "campaign123",
  "added_count": 12
}

أخطاء واجهة برمجة تطبيقات قاعدة المعرفة #

تُرجع نقاط النهاية هذه غلاف الخطأ القياسي:

{
  "success": false,
  "error": "Knowledge base source not found."
}

الإخفاقات الطفيفة ليست أخطاء. تستجيب عمليات الاكتشاف (discover-pages، refresh-domain) ومساعد اختيار الصفحة بـ 200 مع success: false ورسالة error عندما يتعذر قراءة موقع الويب، بدلاً من إفشال الطلب. تحقق دائماً من success قبل قراءة البيانات.

الرموز المشتركة التي يمكن أن تُرجعها كل نقطة نهاية — 401، و 403 (خطتك لا تتضمن الوصول إلى واجهة برمجة التطبيقات)، و 429 (حد المعدل)، و 500 — مدرجة مع إرشادات إعادة المحاولة في الأخطاء والترقيم.

ذات صلة #

• واجهة برمجة تطبيقات الأسئلة الشائعة — قراءة وتعديل وربط الأسئلة الشائعة التي تنتجها مصادرك.
• إدارة الأسئلة الشائعة — نفس قاعدة المعرفة في لوحة التحكم.
• وكلاء الذكاء الاصطناعي — الوكلاء الذين تقوم بإرفاق المصادر والمجموعات بهم.
• الوصول إلى واجهة برمجة التطبيقات — إنشاء مفتاح واجهة برمجة التطبيقات الخاص بك.
• المصادقة — جميع الطرق لتمرير مفتاحك.