توثيق Inkpilots API الإصدار V1

الغرض: مرجع API كامل للواجهة العامة V1 مع وصف شامل لنقاط النهاية، ومعاملات الاستعلام، وآلية المصادقة، وتنسيقات الاستجابة، ونظام الحصص بهدف توليد Node.js SDK.

جدول المحتويات

المصادقة
Base URL و CORS
نقاط نهاية API
معالجة الأخطاء
نظام الحصص
تنسيقات الاستجابة
ملخص نقاط النهاية

المصادقة

المصادقة بمفتاح API

تتطلب جميع نقاط نهاية API في V1 المصادقة عبر مفتاح API. يتم تمرير مفتاح API داخل ترويسة الطلب.

صيغة الترويسة:

x-api-key: Bearer <your-api-key>

مثال:

curl -H "x-api-key: Bearer your_api_key_here" https://inkpilots.com/api/v1/agents

تدفق التحقق

يرسل العميل طلبًا مع ترويسة x-api-key
يستدعي الخادم الدالة verifyApiKey(apiKeyHeader)
إذا كان المفتاح صالحًا، يعيد:
- isValid: قيمة منطقية
- workspaceId: سلسلة نصية (MongoDB ObjectId كسلسلة)
إذا كان غير صالح، يعيد { isValid: false }

استجابات الأخطاء

401 Unauthorized: مفتاح API غير صالح أو مفقود، أو صلاحيات غير كافية
402 Payment Required: تم تجاوز حصة الوصول إلى API الخاصة بخطة مساحة العمل

Base URL و CORS

Base URL

https://inkpilots.com/api/v1

ترويسات CORS

تشمل جميع الاستجابات ترويسات CORS التالية:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, x-api-key

ملاحظة: يسمح CORS بجميع المصادر لأن الـ API لا يستخدم ملفات تعريف الارتباط (مصادقة عديمة الحالة).

طلبات Preflight

جميع نقاط النهاية تدعم طلبات OPTIONS الخاصة بـ CORS preflight:

curl -X OPTIONS https://inkpilots.com/api/v1/agents

الاستجابة: 204 No Content مع ترويسات CORS.

نقاط نهاية API

1. جلب قائمة الوكلاء

Endpoint: GET /agents

الملخص: عرض قائمة الوكلاء

الوصف: يجلب قائمة وكلاء مع تقسيم صفحات، مع فلاتر متقدمة حسب الحالة، ونمط التنفيذ، ونموذج LLM، والبحث النصي الكامل في الاسم والـ prompt. يتطلب المصادقة عبر ترويسة x-api-key وحصة API صالحة.

المصادقة: مطلوبة (x-api-key)

الوسوم: Agents

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

المعامل	النوع	الافتراضي	الوصف	مثال
skip	number	0	عدد الوكلاء الذين سيتم تجاوزهم لأغراض التقسيم (offset)	0
limit	number	10	الحد الأقصى لعدد الوكلاء في الصفحة (بحد أقصى 100)	20
sortBy	string	createdAt	الحقل المستخدم للترتيب (مثل name, createdAt, model, isActive)	createdAt
sortOrder	enum	desc	اتجاه الترتيب (تصاعدي أو تنازلي)	desc
status	enum	optional	تصفية الوكلاء حسب الحالة (active أو inactive)	active
executionMode	enum	optional	تصفية الوكلاء حسب نمط التنفيذ (scheduled أو batched)	scheduled
model	string	optional	تصفية الوكلاء حسب اسم نموذج LLM	llama-2-70b-chat
search	string	optional	بحث نصي كامل في اسم الوكيل والـ prompt (غير حساس لحالة الأحرف)	blog writer

مخطط الاستجابة (200 OK):

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439010",
      "name": "Tech Blog Writer",
      "description": "Generates tech articles on a weekly schedule",
      "status": "active",
      "executionMode": "scheduled",
      "schedule": "0 0 * * MON",
      "model": "llama-2-70b-chat",
      "language": "en",
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T15:45:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 12,
    "totalPages": 1,
    "currentPage": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}

استجابات الأخطاء:

400 Bad Request: معاملات استعلام غير صالحة
401 Unauthorized: مفتاح API غير صالح
402 Payment Required: تم تجاوز حصة API
404 Not Found: لم يتم العثور على مساحة العمل
500 Internal Server Error: خطأ في الخادم

مثال طلب:

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents?limit=20&skip=0&status=active&sortBy=createdAt&sortOrder=desc&model=llama-2-70b-chat"

2. جلب وكيل حسب المعرّف

Endpoint: GET /agents/{agentId}

الملخص: جلب وكيل حسب المعرّف

الوصف: يجلب الإعداد الكامل والبيانات الوصفية لوكيل واحد. يتطلب المصادقة عبر ترويسة x-api-key وحصة API صالحة.

المصادقة: مطلوبة (x-api-key)

الوسوم: Agents

معاملات المسار:

المعامل	النوع	الوصف	مثال
agentId	string	MongoDB ObjectId الخاص بالوكيل المطلوب	507f1f77bcf86cd799439011

مخطط الاستجابة (200 OK):

{
  "agent": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f1f77bcf86cd799439010",
    "name": "Tech Blog Writer",
    "description": "Generates tech articles on a weekly schedule",
    "status": "active",
    "executionMode": "scheduled",
    "schedule": "0 0 * * MON",
    "model": "llama-2-70b-chat",
    "language": "en",
    "prompt": "Write an article about: {topic}",
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T15:45:00Z",
    "createdBy": "507f1f77bcf86cd799439050",
    "updatedBy": "507f1f77bcf86cd799439050"
  }
}

استجابات الأخطاء:

400 Bad Request: صيغة معرّف الوكيل غير صالحة
401 Unauthorized: مفتاح API غير صالح
402 Payment Required: تم تجاوز حصة API
404 Not Found: لم يتم العثور على الوكيل أو مساحة العمل
500 Internal Server Error: خطأ في الخادم

مثال طلب:

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents/507f1f77bcf86cd799439011"

3. جلب قائمة المقالات

Endpoint: GET /articles

الملخص: عرض قائمة المقالات

الوصف: يجلب قائمة مقالات مع تقسيم صفحات، وفلاتر متقدمة حسب الوكيل، والحالة، واللغة، والوسوم، والبحث النصي الكامل عبر العنوان والوصف والكلمات المفتاحية. يتطلب المصادقة عبر ترويسة x-api-key وحصة API صالحة.

المصادقة: مطلوبة (x-api-key)

الوسوم: Articles

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

المعامل	النوع	الافتراضي	الوصف	مثال
skip	number	0	عدد المقالات التي سيتم تجاوزها لأغراض التقسيم (offset)	0
limit	number	10	الحد الأقصى لعدد المقالات في الصفحة (بحد أقصى 100)	20
sortBy	string	createdAt	الحقل المستخدم للترتيب (مثل title, createdAt, status, updatedAt)	createdAt
sortOrder	enum	desc	اتجاه الترتيب (تصاعدي أو تنازلي)	desc
agentId	string	optional	تصفية المقالات حسب معرّف الوكيل المصدر (MongoDB ObjectId)	507f1f77bcf86cd799439011
status	enum	optional	تصفية المقالات حسب حالة النشر (draft, published, archived)	published
slug	string	optional	تصفية المقالات حسب الـ slug المحدد.	generic-article-slug-as-example
language	string	optional	تصفية المقالات حسب رمز اللغة (مثل en, tr, de)	en
model	string	optional	تصفية المقالات حسب نموذج LLM المستخدم في التوليد	llama-2-70b-chat
tags	string	optional	التصفية بالوسوم (مفصولة بفواصل، تطابق أي وسم)	featured,trending,tech
search	string	optional	بحث نصي كامل في العنوان والوصف والكلمات المفتاحية والوسوم (غير حساس لحالة الأحرف)	artificial intelligence

مخطط الاستجابة (200 OK):

{
  "data": [
    {
      "id": "607f1f77bcf86cd799439012",
      "workspaceId": "507f1f77bcf86cd799439010",
      "agentId": "507f1f77bcf86cd799439011",
      "title": "Getting Started with Next.js 14",
      "slug": "getting-started-with-nextjs-14",
      "description": "Learn how to build modern web applications with Next.js 14",
      "status": "published",
      "language": "en",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "tags": ["nextjs", "react", "web-development"],
      "createdBy": "507f1f77bcf86cd799439050",
      "updatedBy": "507f1f77bcf86cd799439050",
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T12:30:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 45,
    "totalPages": 3,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

استجابات الأخطاء:

400 Bad Request: معاملات استعلام غير صالحة
401 Unauthorized: مفتاح API غير صالح
402 Payment Required: تم تجاوز حصة API
404 Not Found: لم يتم العثور على مساحة العمل
500 Internal Server Error: خطأ في الخادم

مثال طلب:

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/articles?limit=25&skip=0&status=published&agentId=507f1f77bcf86cd799439011&language=en&tags=featured,trending&search=artificial+intelligence"

4. جلب مقالة حسب المعرّف

Endpoint: GET /articles/{articleId}

الملخص: جلب مقالة حسب المعرّف

الوصف: يجلب مقالة واحدة عبر معرّفها مع المحتوى الكامل والكتل البنيوية. يتطلب المصادقة عبر ترويسة x-api-key وحصة API صالحة.

المصادقة: مطلوبة (x-api-key)

الوسوم: Articles

معاملات المسار:

المعامل	النوع	الوصف	مثال
articleId	string	MongoDB ObjectId الخاص بالمقالة المطلوب جلبها	607f1f77bcf86cd799439012

مخطط الاستجابة (200 OK):

{
  "article": {
    "id": "607f1f77bcf86cd799439012",
    "workspaceId": "507f1f77bcf86cd799439010",
    "agentId": "507f1f77bcf86cd799439011",
    "title": "Getting Started with Next.js 14",
    "slug": "getting-started-with-nextjs-14",
    "description": "Learn how to build modern web applications with Next.js 14",
    "content": "Full article markdown/text content here...",
    "status": "published",
    "language": "en",
    "model": "llama-2-70b-chat",
    "tone": "professional",
    "tags": ["nextjs", "react", "web-development"],
    "blocks": [
      {
        "type": "header",
        "content": "Getting Started with Next.js 14",
        "level": 1
      },
      {
        "type": "text",
        "content": "Next.js 14 introduces new features..."
      },
      {
        "type": "image",
        "url": "https://example.com/image.jpg",
        "caption": "Next.js logo"
      }
    ],
    "meta": {
      "keywords": "nextjs, react, web development",
      "description": "Learn how to build modern web applications with Next.js 14",
      "tags": ["nextjs", "react", "web-development"]
    },
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2024-01-15T12:30:00Z",
    "createdBy": "507f1f77bcf86cd799439050",
    "updatedBy": "507f1f77bcf86cd799439050"
  }
}

أنواع الكتل:

text: فقرة نصية عادية

{"type": "text", "content": "Paragraph text"}

header: عنوان (المستويات 1-6)

{"type": "header", "content": "Heading", "level": 1}

image: صورة مع تسمية توضيحية اختيارية

{"type": "image", "url": "https://example.com/img.jpg", "caption": "Caption"}

list: قائمة مرتبة أو غير مرتبة

{"type": "list", "items": ["item1", "item2"], "ordered": false}

code: كتلة كود مع اللغة

{"type": "code", "content": "const x = 1;", "language": "javascript"}

video: تضمين فيديو

{"type": "video", "url": "https://example.com/video.mp4", "title": "Video title"}

استجابات الأخطاء:

400 Bad Request: صيغة معرّف المقالة غير صالحة
401 Unauthorized: مفتاح API غير صالح
402 Payment Required: تم تجاوز حصة API
404 Not Found: لم يتم العثور على المقالة أو مساحة العمل
500 Internal Server Error: خطأ في الخادم

مثال طلب:

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/articles/607f1f77bcf86cd799439012"

5. جلب مقالات وكيل

Endpoint: GET /agents/{agentId}/articles

الملخص: جلب مقالات وكيل محدد

الوصف: يجلب جميع المقالات التي أنشأها وكيل محدد مع التصفية وتقسيم الصفحات. تُعاد المقالات مرتبة من الأحدث إلى الأقدم. يتطلب المصادقة عبر ترويسة x-api-key وحصة API صالحة.

المصادقة: مطلوبة (x-api-key)

الوسوم: Agents

معاملات المسار:

المعامل	النوع	الوصف	مثال
agentId	string	MongoDB ObjectId الخاص بالوكيل	507f1f77bcf86cd799439011

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

المعامل	النوع	الافتراضي	الوصف	مثال
limit	number	50	الحد الأقصى لعدد المقالات المرجعة	30
skip	number	0	عدد السجلات التي سيتم تجاوزها للتقسيم	0
status	string	optional	التصفية حسب حالة المقالة (draft, published, archived)	published
sort	string	createdAt	الحقل المستخدم للترتيب	createdAt
order	enum	desc	اتجاه الترتيب (asc أو desc)	desc
slug	string	optional	تصفية المقالات حسب slug الصديق لعناوين URL	getting-started-with-nextjs

مخطط الاستجابة (200 OK):

{
  "articles": [
    {
      "id": "607f1f77bcf86cd799439012",
      "workspaceId": "507f1f77bcf86cd799439010",
      "agentId": "507f1f77bcf86cd799439011",
      "title": "Getting Started with Next.js",
      "slug": "getting-started-with-nextjs",
      "description": "A comprehensive guide to Next.js",
      "status": "published",
      "language": "en",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "tags": ["nextjs", "react", "web-development"],
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T12:30:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 30,
    "totalCount": 45,
    "totalPages": 2,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

استجابات الأخطاء:

400 Bad Request: صيغة معرّف الوكيل غير صالحة
401 Unauthorized: مفتاح API غير صالح
402 Payment Required: تم تجاوز حصة API
404 Not Found: لم يتم العثور على الوكيل أو مساحة العمل
500 Internal Server Error: خطأ في الخادم

مثال طلب:

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents/507f1f77bcf86cd799439011/articles?limit=30&skip=0&status=published&sort=createdAt&order=desc"

6. جلب بيانات مساحة العمل

Endpoint: GET /workspaces/{workspaceId}

الملخص: جلب بيانات مساحة العمل

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

المصادقة: مطلوبة (x-api-key) - يجب أن تطابق مساحة العمل المطلوب الوصول إليها

الوسوم: Workspaces

معاملات المسار:

المعامل	النوع	الوصف	مثال
workspaceId	string	MongoDB ObjectId الخاص بمساحة العمل المطلوب جلبها	507f1f77bcf86cd799439010

مخطط الاستجابة (200 OK):

{
  "workspace": {
    "id": "507f1f77bcf86cd799439010",
    "ownerId": "507f1f77bcf86cd799439001",
    "name": "My Content Studio",
    "description": "AI-powered content generation workspace",
    "plan": "pro",
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T12:30:00Z"
  },
  "agents": [
    {
      "id": "607f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439010",
      "name": "Tech Content Agent",
      "description": "Generates technical articles and tutorials",
      "status": "active",
      "executionMode": "scheduled",
      "schedule": "0 0 * * *",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "language": "en",
      "isActive": true,
      "createdAt": "2024-01-10T12:00:00Z",
      "updatedAt": "2024-01-20T10:15:00Z",
      "articles": [
        {
          "id": "707f1f77bcf86cd799439012",
          "workspaceId": "507f1f77bcf86cd799439010",
          "agentId": "607f1f77bcf86cd799439011",
          "title": "Getting Started with Next.js",
          "slug": "getting-started-with-nextjs",
          "description": "A comprehensive guide to Next.js",
          "status": "published",
          "language": "en",
          "model": "llama-2-70b-chat",
          "tone": "professional",
          "tags": ["nextjs", "react", "web"],
          "createdAt": "2024-01-10T08:00:00Z",
          "updatedAt": "2024-01-15T12:30:00Z"
        }
      ]
    }
  ]
}

استجابات الأخطاء:

400 Bad Request: صيغة معرّف مساحة العمل غير صالحة
401 Unauthorized: مفتاح API غير صالح أو عدم تطابق مساحة العمل
402 Payment Required: تم تجاوز حصة API
404 Not Found: لم يتم العثور على مساحة العمل
500 Internal Server Error: خطأ في الخادم

مثال طلب:

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/workspaces/507f1f77bcf86cd799439010"

معالجة الأخطاء

تعيد جميع نقاط النهاية استجابات أخطاء موحّدة مع رموز حالة HTTP:

صيغة استجابة الخطأ

{
  "error": "Error type",
  "details": "Detailed error message"
}

رموز حالة HTTP

الحالة	الوصف
200	نجاح - اكتمل الطلب بنجاح
400	طلب غير صالح - معاملات استعلام أو صيغة مسار غير صحيحة
401	غير مصرح - مفتاح API مفقود أو غير صالح
402	الدفع مطلوب - تم تجاوز حصة API لخطة مساحة العمل
404	غير موجود - المورد غير موجود
500	خطأ خادم داخلي - حدث خطأ في جهة الخادم

نظام الحصص

لكل مساحة عمل حصة استدعاءات API بناءً على خطة الاشتراك الخاصة بها. تُعاد الحصة شهريًا ويتم فرضها على كل طلب.

حدود الخطط

Free: ‏0 استدعاء API/شهريًا
Starter: ‏0 استدعاء API/شهريًا
Pro: ‏10,000 استدعاء API/شهريًا
Agency: ‏~ استدعاء API/شهريًا
Enterprise: غير محدود

فرض الحصة

يُحتسب كل طلب API كاستدعاء واحد ضمن الحصة الشهرية. عند تجاوز الحصة:

HTTP Status: 402 Payment Required
Response: { error: "API access quota exceeded" }

تنسيقات الاستجابة

استجابة النجاح

تعيد جميع الاستجابات الناجحة رمز الحالة 200 مع بيانات JSON:

{
  "data": [...],
  "pagination": {...}
}

تنسيق التقسيم إلى صفحات

تستخدم جميع نقاط نهاية القوائم بيانات تعريف التقسيم نفسها:

{
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 45,
    "totalPages": 3,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

استجابة الخطأ

تتضمن جميع استجابات الخطأ حقلي error و details:

{
  "error": "Unauthorized",
  "details": "Invalid or missing API key"
}

ملخص نقاط النهاية

الطريقة	Endpoint	الوصف
GET	/agents	عرض قائمة الوكلاء مع التقسيم والفلاتر
GET	/agents/{agentId}	جلب وكيل واحد حسب المعرّف
GET	/articles	عرض قائمة المقالات مع التقسيم والفلاتر المتقدمة
GET	/articles/{articleId}	جلب مقالة واحدة حسب المعرّف مع المحتوى الكامل
GET	/agents/{agentId}/articles	جلب مقالات وكيل محدد
GET	/workspaces/{workspaceId}	جلب مساحة العمل مع جميع الوكلاء والمقالات
OPTIONS	/*	دعم CORS preflight

أفضل الممارسات

التقسيم إلى صفحات

استخدم دائمًا التقسيم في نقاط نهاية القوائم لتجنب المهلات الزمنية
ابدأ بـ skip: 0 و limit: 25-50
استخدم hasNextPage لتحديد وجود نتائج إضافية
طبّق آلية exponential backoff للطلبات الفاشلة

التصفية

استخدم فلاتر محددة لتقليل حجم الاستجابة
صفِّ النتائج حسب status و language لتضييق النطاق
استخدم search للبحث النصي الكامل بدلًا من جلب كل السجلات

معالجة الأخطاء

تحقّق دائمًا من أخطاء 401 (المصادقة) و402 (الحصة)
طبّق منطق إعادة المحاولة مع exponential backoff
سجّل تفاصيل الأخطاء لأغراض التصحيح
تعامل مع أخطاء 4xx كمشكلات من جهة العميل و5xx كمشكلات من جهة الخادم

الأداء

استخدم التخزين المؤقت لمدة 5-10 دقائق لتقليل استدعاءات API
استخدم limit=50 لأداء أمثل
اجمع بين الفلاتر لتقليل حجم النتائج
راعِ حجم دفعة التقسيم بناءً على حدود الحصة

إصدار المستند: 2.0 آخر تحديث: يناير 2026 إصدار API: v1 الحالة: جاهز للإنتاج لتوليد SDK

توثيق Inkpilots API الإصدار V1

المصادقة

المصادقة بمفتاح API

تتطلب جميع نقاط نهاية API في V1 المصادقة عبر مفتاح API. يتم تمرير مفتاح API داخل ترويسة الطلب.

صيغة الترويسة:

x-api-key: Bearer <your-api-key>

مثال:

curl -H "x-api-key: Bearer your_api_key_here" https://inkpilots.com/api/v1/agents

تدفق التحقق

يرسل العميل طلبًا مع ترويسة x-api-key
يستدعي الخادم الدالة verifyApiKey(apiKeyHeader)
إذا كان المفتاح صالحًا، يعيد:
- isValid: قيمة منطقية
- workspaceId: سلسلة نصية (MongoDB ObjectId كسلسلة)
إذا كان غير صالح، يعيد { isValid: false }

استجابات الأخطاء

401 Unauthorized: مفتاح API غير صالح أو مفقود، أو صلاحيات غير كافية
402 Payment Required: تم تجاوز حصة الوصول إلى API الخاصة بخطة مساحة العمل

Base URL و CORS

Base URL

https://inkpilots.com/api/v1

ترويسات CORS

تشمل جميع الاستجابات ترويسات CORS التالية:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, x-api-key

ملاحظة: يسمح CORS بجميع المصادر لأن الـ API لا يستخدم ملفات تعريف الارتباط (مصادقة عديمة الحالة).

طلبات Preflight

جميع نقاط النهاية تدعم طلبات OPTIONS الخاصة بـ CORS preflight:

curl -X OPTIONS https://inkpilots.com/api/v1/agents

الاستجابة: 204 No Content مع ترويسات CORS.

نقاط نهاية API

1. جلب قائمة الوكلاء

Endpoint: GET /agents

الملخص: عرض قائمة الوكلاء

المصادقة: مطلوبة (x-api-key)

الوسوم: Agents

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

المعامل	النوع	الافتراضي	الوصف	مثال
skip	number	0	عدد الوكلاء الذين سيتم تجاوزهم لأغراض التقسيم (offset)	0
limit	number	10	الحد الأقصى لعدد الوكلاء في الصفحة (بحد أقصى 100)	20
sortBy	string	createdAt	الحقل المستخدم للترتيب (مثل name, createdAt, model, isActive)	createdAt
sortOrder	enum	desc	اتجاه الترتيب (تصاعدي أو تنازلي)	desc
status	enum	optional	تصفية الوكلاء حسب الحالة (active أو inactive)	active
executionMode	enum	optional	تصفية الوكلاء حسب نمط التنفيذ (scheduled أو batched)	scheduled
model	string	optional	تصفية الوكلاء حسب اسم نموذج LLM	llama-2-70b-chat
search	string	optional	بحث نصي كامل في اسم الوكيل والـ prompt (غير حساس لحالة الأحرف)	blog writer

مخطط الاستجابة (200 OK):

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439010",
      "name": "Tech Blog Writer",
      "description": "Generates tech articles on a weekly schedule",
      "status": "active",
      "executionMode": "scheduled",
      "schedule": "0 0 * * MON",
      "model": "llama-2-70b-chat",
      "language": "en",
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T15:45:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 12,
    "totalPages": 1,
    "currentPage": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}

استجابات الأخطاء:

400 Bad Request: معاملات استعلام غير صالحة
401 Unauthorized: مفتاح API غير صالح
402 Payment Required: تم تجاوز حصة API
404 Not Found: لم يتم العثور على مساحة العمل
500 Internal Server Error: خطأ في الخادم

مثال طلب:

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents?limit=20&skip=0&status=active&sortBy=createdAt&sortOrder=desc&model=llama-2-70b-chat"

2. جلب وكيل حسب المعرّف

Endpoint: GET /agents/{agentId}

الملخص: جلب وكيل حسب المعرّف

الوصف: يجلب الإعداد الكامل والبيانات الوصفية لوكيل واحد. يتطلب المصادقة عبر ترويسة x-api-key وحصة API صالحة.

المصادقة: مطلوبة (x-api-key)

الوسوم: Agents

معاملات المسار:

المعامل	النوع	الوصف	مثال
agentId	string	MongoDB ObjectId الخاص بالوكيل المطلوب	507f1f77bcf86cd799439011

مخطط الاستجابة (200 OK):

{
  "agent": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f1f77bcf86cd799439010",
    "name": "Tech Blog Writer",
    "description": "Generates tech articles on a weekly schedule",
    "status": "active",
    "executionMode": "scheduled",
    "schedule": "0 0 * * MON",
    "model": "llama-2-70b-chat",
    "language": "en",
    "prompt": "Write an article about: {topic}",
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T15:45:00Z",
    "createdBy": "507f1f77bcf86cd799439050",
    "updatedBy": "507f1f77bcf86cd799439050"
  }
}

استجابات الأخطاء:

400 Bad Request: صيغة معرّف الوكيل غير صالحة
401 Unauthorized: مفتاح API غير صالح
402 Payment Required: تم تجاوز حصة API
404 Not Found: لم يتم العثور على الوكيل أو مساحة العمل
500 Internal Server Error: خطأ في الخادم

مثال طلب:

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents/507f1f77bcf86cd799439011"

3. جلب قائمة المقالات

Endpoint: GET /articles

الملخص: عرض قائمة المقالات

المصادقة: مطلوبة (x-api-key)

الوسوم: Articles

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

المعامل	النوع	الافتراضي	الوصف	مثال
skip	number	0	عدد المقالات التي سيتم تجاوزها لأغراض التقسيم (offset)	0
limit	number	10	الحد الأقصى لعدد المقالات في الصفحة (بحد أقصى 100)	20
sortBy	string	createdAt	الحقل المستخدم للترتيب (مثل title, createdAt, status, updatedAt)	createdAt
sortOrder	enum	desc	اتجاه الترتيب (تصاعدي أو تنازلي)	desc
agentId	string	optional	تصفية المقالات حسب معرّف الوكيل المصدر (MongoDB ObjectId)	507f1f77bcf86cd799439011
status	enum	optional	تصفية المقالات حسب حالة النشر (draft, published, archived)	published
slug	string	optional	تصفية المقالات حسب الـ slug المحدد.	generic-article-slug-as-example
language	string	optional	تصفية المقالات حسب رمز اللغة (مثل en, tr, de)	en
model	string	optional	تصفية المقالات حسب نموذج LLM المستخدم في التوليد	llama-2-70b-chat
tags	string	optional	التصفية بالوسوم (مفصولة بفواصل، تطابق أي وسم)	featured,trending,tech
search	string	optional	بحث نصي كامل في العنوان والوصف والكلمات المفتاحية والوسوم (غير حساس لحالة الأحرف)	artificial intelligence

مخطط الاستجابة (200 OK):

{
  "data": [
    {
      "id": "607f1f77bcf86cd799439012",
      "workspaceId": "507f1f77bcf86cd799439010",
      "agentId": "507f1f77bcf86cd799439011",
      "title": "Getting Started with Next.js 14",
      "slug": "getting-started-with-nextjs-14",
      "description": "Learn how to build modern web applications with Next.js 14",
      "status": "published",
      "language": "en",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "tags": ["nextjs", "react", "web-development"],
      "createdBy": "507f1f77bcf86cd799439050",
      "updatedBy": "507f1f77bcf86cd799439050",
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T12:30:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 45,
    "totalPages": 3,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

استجابات الأخطاء:

400 Bad Request: معاملات استعلام غير صالحة
401 Unauthorized: مفتاح API غير صالح
402 Payment Required: تم تجاوز حصة API
404 Not Found: لم يتم العثور على مساحة العمل
500 Internal Server Error: خطأ في الخادم

مثال طلب:

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/articles?limit=25&skip=0&status=published&agentId=507f1f77bcf86cd799439011&language=en&tags=featured,trending&search=artificial+intelligence"

4. جلب مقالة حسب المعرّف

Endpoint: GET /articles/{articleId}

الملخص: جلب مقالة حسب المعرّف

المصادقة: مطلوبة (x-api-key)

الوسوم: Articles

معاملات المسار:

المعامل	النوع	الوصف	مثال
articleId	string	MongoDB ObjectId الخاص بالمقالة المطلوب جلبها	607f1f77bcf86cd799439012

مخطط الاستجابة (200 OK):

{
  "article": {
    "id": "607f1f77bcf86cd799439012",
    "workspaceId": "507f1f77bcf86cd799439010",
    "agentId": "507f1f77bcf86cd799439011",
    "title": "Getting Started with Next.js 14",
    "slug": "getting-started-with-nextjs-14",
    "description": "Learn how to build modern web applications with Next.js 14",
    "content": "Full article markdown/text content here...",
    "status": "published",
    "language": "en",
    "model": "llama-2-70b-chat",
    "tone": "professional",
    "tags": ["nextjs", "react", "web-development"],
    "blocks": [
      {
        "type": "header",
        "content": "Getting Started with Next.js 14",
        "level": 1
      },
      {
        "type": "text",
        "content": "Next.js 14 introduces new features..."
      },
      {
        "type": "image",
        "url": "https://example.com/image.jpg",
        "caption": "Next.js logo"
      }
    ],
    "meta": {
      "keywords": "nextjs, react, web development",
      "description": "Learn how to build modern web applications with Next.js 14",
      "tags": ["nextjs", "react", "web-development"]
    },
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2024-01-15T12:30:00Z",
    "createdBy": "507f1f77bcf86cd799439050",
    "updatedBy": "507f1f77bcf86cd799439050"
  }
}

أنواع الكتل:

text: فقرة نصية عادية

{"type": "text", "content": "Paragraph text"}

header: عنوان (المستويات 1-6)

{"type": "header", "content": "Heading", "level": 1}

image: صورة مع تسمية توضيحية اختيارية

{"type": "image", "url": "https://example.com/img.jpg", "caption": "Caption"}

list: قائمة مرتبة أو غير مرتبة

{"type": "list", "items": ["item1", "item2"], "ordered": false}

code: كتلة كود مع اللغة

{"type": "code", "content": "const x = 1;", "language": "javascript"}

video: تضمين فيديو

{"type": "video", "url": "https://example.com/video.mp4", "title": "Video title"}

استجابات الأخطاء:

400 Bad Request: صيغة معرّف المقالة غير صالحة
401 Unauthorized: مفتاح API غير صالح
402 Payment Required: تم تجاوز حصة API
404 Not Found: لم يتم العثور على المقالة أو مساحة العمل
500 Internal Server Error: خطأ في الخادم

مثال طلب:

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/articles/607f1f77bcf86cd799439012"

5. جلب مقالات وكيل

Endpoint: GET /agents/{agentId}/articles

الملخص: جلب مقالات وكيل محدد

المصادقة: مطلوبة (x-api-key)

الوسوم: Agents

معاملات المسار:

المعامل	النوع	الوصف	مثال
agentId	string	MongoDB ObjectId الخاص بالوكيل	507f1f77bcf86cd799439011

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

المعامل	النوع	الافتراضي	الوصف	مثال
limit	number	50	الحد الأقصى لعدد المقالات المرجعة	30
skip	number	0	عدد السجلات التي سيتم تجاوزها للتقسيم	0
status	string	optional	التصفية حسب حالة المقالة (draft, published, archived)	published
sort	string	createdAt	الحقل المستخدم للترتيب	createdAt
order	enum	desc	اتجاه الترتيب (asc أو desc)	desc
slug	string	optional	تصفية المقالات حسب slug الصديق لعناوين URL	getting-started-with-nextjs

مخطط الاستجابة (200 OK):

{
  "articles": [
    {
      "id": "607f1f77bcf86cd799439012",
      "workspaceId": "507f1f77bcf86cd799439010",
      "agentId": "507f1f77bcf86cd799439011",
      "title": "Getting Started with Next.js",
      "slug": "getting-started-with-nextjs",
      "description": "A comprehensive guide to Next.js",
      "status": "published",
      "language": "en",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "tags": ["nextjs", "react", "web-development"],
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T12:30:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 30,
    "totalCount": 45,
    "totalPages": 2,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

استجابات الأخطاء:

400 Bad Request: صيغة معرّف الوكيل غير صالحة
401 Unauthorized: مفتاح API غير صالح
402 Payment Required: تم تجاوز حصة API
404 Not Found: لم يتم العثور على الوكيل أو مساحة العمل
500 Internal Server Error: خطأ في الخادم

مثال طلب:

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents/507f1f77bcf86cd799439011/articles?limit=30&skip=0&status=published&sort=createdAt&order=desc"

6. جلب بيانات مساحة العمل

Endpoint: GET /workspaces/{workspaceId}

الملخص: جلب بيانات مساحة العمل

المصادقة: مطلوبة (x-api-key) - يجب أن تطابق مساحة العمل المطلوب الوصول إليها

الوسوم: Workspaces

معاملات المسار:

المعامل	النوع	الوصف	مثال
workspaceId	string	MongoDB ObjectId الخاص بمساحة العمل المطلوب جلبها	507f1f77bcf86cd799439010

مخطط الاستجابة (200 OK):

{
  "workspace": {
    "id": "507f1f77bcf86cd799439010",
    "ownerId": "507f1f77bcf86cd799439001",
    "name": "My Content Studio",
    "description": "AI-powered content generation workspace",
    "plan": "pro",
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T12:30:00Z"
  },
  "agents": [
    {
      "id": "607f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439010",
      "name": "Tech Content Agent",
      "description": "Generates technical articles and tutorials",
      "status": "active",
      "executionMode": "scheduled",
      "schedule": "0 0 * * *",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "language": "en",
      "isActive": true,
      "createdAt": "2024-01-10T12:00:00Z",
      "updatedAt": "2024-01-20T10:15:00Z",
      "articles": [
        {
          "id": "707f1f77bcf86cd799439012",
          "workspaceId": "507f1f77bcf86cd799439010",
          "agentId": "607f1f77bcf86cd799439011",
          "title": "Getting Started with Next.js",
          "slug": "getting-started-with-nextjs",
          "description": "A comprehensive guide to Next.js",
          "status": "published",
          "language": "en",
          "model": "llama-2-70b-chat",
          "tone": "professional",
          "tags": ["nextjs", "react", "web"],
          "createdAt": "2024-01-10T08:00:00Z",
          "updatedAt": "2024-01-15T12:30:00Z"
        }
      ]
    }
  ]
}

استجابات الأخطاء:

400 Bad Request: صيغة معرّف مساحة العمل غير صالحة
401 Unauthorized: مفتاح API غير صالح أو عدم تطابق مساحة العمل
402 Payment Required: تم تجاوز حصة API
404 Not Found: لم يتم العثور على مساحة العمل
500 Internal Server Error: خطأ في الخادم

مثال طلب:

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/workspaces/507f1f77bcf86cd799439010"

معالجة الأخطاء

تعيد جميع نقاط النهاية استجابات أخطاء موحّدة مع رموز حالة HTTP:

صيغة استجابة الخطأ

{
  "error": "Error type",
  "details": "Detailed error message"
}

رموز حالة HTTP

الحالة	الوصف
200	نجاح - اكتمل الطلب بنجاح
400	طلب غير صالح - معاملات استعلام أو صيغة مسار غير صحيحة
401	غير مصرح - مفتاح API مفقود أو غير صالح
402	الدفع مطلوب - تم تجاوز حصة API لخطة مساحة العمل
404	غير موجود - المورد غير موجود
500	خطأ خادم داخلي - حدث خطأ في جهة الخادم

نظام الحصص

لكل مساحة عمل حصة استدعاءات API بناءً على خطة الاشتراك الخاصة بها. تُعاد الحصة شهريًا ويتم فرضها على كل طلب.

حدود الخطط

Free: ‏0 استدعاء API/شهريًا
Starter: ‏0 استدعاء API/شهريًا
Pro: ‏10,000 استدعاء API/شهريًا
Agency: ‏~ استدعاء API/شهريًا
Enterprise: غير محدود

فرض الحصة

يُحتسب كل طلب API كاستدعاء واحد ضمن الحصة الشهرية. عند تجاوز الحصة:

HTTP Status: 402 Payment Required
Response: { error: "API access quota exceeded" }

تنسيقات الاستجابة

استجابة النجاح

تعيد جميع الاستجابات الناجحة رمز الحالة 200 مع بيانات JSON:

{
  "data": [...],
  "pagination": {...}
}

تنسيق التقسيم إلى صفحات

تستخدم جميع نقاط نهاية القوائم بيانات تعريف التقسيم نفسها:

{
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 45,
    "totalPages": 3,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

استجابة الخطأ

تتضمن جميع استجابات الخطأ حقلي error و details:

{
  "error": "Unauthorized",
  "details": "Invalid or missing API key"
}

ملخص نقاط النهاية

الطريقة	Endpoint	الوصف
GET	/agents	عرض قائمة الوكلاء مع التقسيم والفلاتر
GET	/agents/{agentId}	جلب وكيل واحد حسب المعرّف
GET	/articles	عرض قائمة المقالات مع التقسيم والفلاتر المتقدمة
GET	/articles/{articleId}	جلب مقالة واحدة حسب المعرّف مع المحتوى الكامل
GET	/agents/{agentId}/articles	جلب مقالات وكيل محدد
GET	/workspaces/{workspaceId}	جلب مساحة العمل مع جميع الوكلاء والمقالات
OPTIONS	/*	دعم CORS preflight

أفضل الممارسات

التقسيم إلى صفحات

استخدم دائمًا التقسيم في نقاط نهاية القوائم لتجنب المهلات الزمنية
ابدأ بـ skip: 0 و limit: 25-50
استخدم hasNextPage لتحديد وجود نتائج إضافية
طبّق آلية exponential backoff للطلبات الفاشلة

التصفية

استخدم فلاتر محددة لتقليل حجم الاستجابة
صفِّ النتائج حسب status و language لتضييق النطاق
استخدم search للبحث النصي الكامل بدلًا من جلب كل السجلات

معالجة الأخطاء

تحقّق دائمًا من أخطاء 401 (المصادقة) و402 (الحصة)
طبّق منطق إعادة المحاولة مع exponential backoff
سجّل تفاصيل الأخطاء لأغراض التصحيح
تعامل مع أخطاء 4xx كمشكلات من جهة العميل و5xx كمشكلات من جهة الخادم

الأداء

استخدم التخزين المؤقت لمدة 5-10 دقائق لتقليل استدعاءات API
استخدم limit=50 لأداء أمثل
اجمع بين الفلاتر لتقليل حجم النتائج
راعِ حجم دفعة التقسيم بناءً على حدود الحصة

إصدار المستند: 2.0 آخر تحديث: يناير 2026 إصدار API: v1 الحالة: جاهز للإنتاج لتوليد SDK