Felo APIs

LiveDoc API

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

POST/v2/livedocs

المصادقة

Bearer API key

نوع المحتوى

application/json or multipart/form-data

ملاحظات السعر

قد تنطبق حدود خاصة بـ endpoint.

SuperAgent API PPT Task API

يوفر LiveDoc API عمليات CRUD كاملة لـLiveDocs ومواردها، بما في ذلك إنشاء المستندات ورفع الملفات واستيراد عناوين URL والاسترجاع الدلالي.

المصادقة

تتطلب كل الطلبات مفتاح API في رأس Authorization:

Authorization: Bearer YOUR_API_KEY

الاستخدام مع وكلاء الذكاء الاصطناعي

ثبّت حزمة felo-ai الكاملة لتزويد وكيل بدعم LiveDoc وكل مهارات Felo Skill الأخرى المتاحة. يكتشف المثبّت ديناميكيًا كل دليل حزمة يحتوي SKILL.md، بما في ذلك إضافات الحزم المستقبلية. ثبّت كل المهارات المكتشفة في الدليل الأصلي للوكيل: Codex ~/.codex/skills أو Claude Code ~/.claude/skills أو OpenClaw ~/.agents/skills أو Hermes Agent ~/.hermes/skills. يغطي دليل إعداد وكيل الذكاء الاصطناعي اليدوي خطوات مفتاح API والتحقق المميزة لكل منصة.

1. إنشاء LiveDoc

Endpoint

POST https://openapi.felo.ai/v2/livedocs

نص الطلب

المعامل	النوع	مطلوب	الوصف
`name`	string	نعم	اسم LiveDoc
`description`	string	لا	وصف LiveDoc
`icon`	string	لا	أيقونة LiveDoc

مثال

curl -X POST 'https://openapi.felo.ai/v2/livedocs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "AI Research Notes",
    "description": "Collection of AI research materials"
  }'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "short_id": "PvyKouzJirXjFdst4uKRK3",
    "name": "AI Research Notes",
    "description": "Collection of AI research materials",
    "icon": null,
    "created_at": "2026-03-09T10:00:00Z",
    "modified_at": "2026-03-09T10:00:00Z"
  }
}

Response Fields (حقول الاستجابة)

الحقل	النوع	الوصف
`short_id`	string	معرّف LiveDoc
`name`	string	اسم LiveDoc
`description`	string	وصف LiveDoc
`icon`	string	أيقونة LiveDoc
`created_at`	string	طابع زمني للإنشاء (ISO 8601)
`modified_at`	string	طابع زمني لآخر تعديل (ISO 8601)
`is_shared`	boolean	ما إذا كان LiveDoc هذا مشتركًا مع المستخدم الحالي (غير مملوك له)

2. سرد LiveDocs

Endpoint

GET https://openapi.felo.ai/v2/livedocs

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

المعامل	النوع	مطلوب	الوصف
`keyword`	string	لا	التصفية بكلمة مفتاحية
`page`	integer	لا	رقم الصفحة (يبدأ من 1)
`size`	integer	لا	حجم الصفحة

مثال

curl 'https://openapi.felo.ai/v2/livedocs?keyword=AI&page=1&size=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 2,
    "page": 1,
    "size": 20,
    "items": [
      {
        "short_id": "PvyKouzJirXjFdst4uKRK3",
        "name": "AI Research Notes",
        "description": "Collection of AI research materials",
        "icon": null,
        "created_at": "2026-03-09T10:00:00Z",
        "modified_at": "2026-03-09T10:05:00Z",
        "is_shared": false,
        "readme": {
          "summary": "AI research notes and papers collection",
          "content": "# AI Research Notes\n\nThis LiveDoc contains..."
        }
      }
    ]
  }
}

حقول الاستجابة

يحتوي كل عنصر في items على الحقول نفسها الموجودة في استجابة إنشاء LiveDoc، بالإضافة إلى:

الحقل	النوع	الوصف
`readme`	object \| null	معلومات README. `null` إذا لم يوجد README.
`readme.summary`	string \| null	وصف المشروع في سطر واحد
`readme.content`	string \| null	محتوى README (Markdown)

Endpoint

PUT https://openapi.felo.ai/v2/livedocs/{short_id}

نص الطلب

المعامل	النوع	مطلوب	الوصف
`name`	string	لا	اسم LiveDoc الجديد
`description`	string	لا	وصف LiveDoc الجديد

مثال

curl -X PUT 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Research Notes"
  }'

استجابة النجاح (200)

يعيد كائن LiveDoc المحدّث (البنية نفسها كالإنشاء).

4. حذف LiveDoc

Endpoint

DELETE https://openapi.felo.ai/v2/livedocs/{short_id}

مثال

curl -X DELETE 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3' \
  -H 'Authorization: Bearer YOUR_API_KEY'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": null
}

5. سرد الموارد

Endpoint

GET https://openapi.felo.ai/v2/livedocs/{short_id}/resources

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

المعامل	النوع	مطلوب	الوصف
`resource_types`	string[]	لا	التصفية حسب أنواع الموارد
`page`	integer	لا	رقم الصفحة (يبدأ من 1)
`size`	integer	لا	حجم الصفحة

مثال

curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources?page=1&size=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 2,
    "page": 1,
    "size": 20,
    "items": [
      {
        "id": "res_001",
        "title": "OpenAI Blog Post",
        "link": "https://openai.com/blog/...",
        "snippet": "Summary of the article...",
        "thumbnail": null,
        "resource_type": "web",
        "resource_key": "key_001",
        "status": "completed",
        "source": "url",
        "created_at": "2026-03-09T10:00:10Z",
        "modified_at": "2026-03-09T10:00:15Z"
      }
    ]
  }
}

حقول استجابة المورد

الحقل	النوع	الوصف
`id`	string	معرّف المورد
`title`	string	عنوان المورد
`link`	string	رابط المورد / عنوان URL
`snippet`	string	ملخص المورد
`thumbnail`	string	عنوان URL للصورة المصغّرة
`resource_type`	string	نوع المورد (مثل `web` و`ai_doc` و`file`)
`resource_key`	string	مفتاح ربط المورد
`status`	string	حالة المورد
`source`	string	مصدر المورد
`created_at`	string	طابع زمني للإنشاء (ISO 8601)
`modified_at`	string	طابع زمني لآخر تعديل (ISO 8601)

6. الحصول على مورد واحد

Endpoint

GET https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id}

مثال

curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001' \
  -H 'Authorization: Bearer YOUR_API_KEY'

استجابة النجاح (200)

يعيد كائن مورد واحدًا (البنية نفسها كعناصر سرد الموارد).

7. تحديث مورد

حدّث title أو snippet أو thumbnail لمورد. ولا تُحدَّث إلا الحقول المقدَّمة؛ وتحتفظ الحقول المحذوفة بقيمها الحالية.

Endpoint

PUT https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id}

نص الطلب

كل الحقول اختيارية.

المعامل	النوع	مطلوب	الوصف
`title`	string	لا	عنوان المورد الجديد (بحد أقصى 500 حرف)
`snippet`	string	لا	ملخص المورد الجديد (بحد أقصى 2000 حرف)
`thumbnail`	string	لا	عنوان URL الجديد للصورة المصغّرة (بحد أقصى 2000 حرف)

مثال

curl -X PUT 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Updated Title",
    "snippet": "Updated summary of the resource."
  }'

استجابة النجاح (200)

يعيد كائن المورد المحدّث (البنية نفسها كعناصر سرد الموارد).

8. تحديث محتوى المورد

حدّث محتوى Markdown لمورد من النوع ai_doc. مدعوم فقط للموارد ذات resource_type == ai_doc. ويُحدَّث الحقل snippet تلقائيًا من أول 2000 بايت من المحتوى الجديد.

Endpoint

PUT https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id}/content

نص الطلب

المعامل	النوع	مطلوب	الوصف
`content`	string	نعم	محتوى Markdown الجديد للمورد

مثال

curl -X PUT 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001/content' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "# Updated Document\n\nThis is the new content."
  }'

استجابة النجاح (200)

يعيد كائن المورد المحدّث (البنية نفسها كعناصر سرد الموارد).

9. إنشاء مورد مستند

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/doc

نص الطلب

المعامل	النوع	مطلوب	الوصف
`title`	string	لا	عنوان المستند (الافتراضي "New Document")
`content`	string	نعم	محتوى المستند

مثال

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/doc' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "My Research Notes",
    "content": "Key findings from the AI research paper..."
  }'

استجابة النجاح (200)

يعيد كائن المورد المنشأ.

10. رفع ملف كمستند

ارفع ملفًا وحوّله إلى مورد مستند (نوع ai_doc).

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/upload-doc

Content-Type

multipart/form-data

أجزاء الطلب

المعامل	النوع	مطلوب	الوصف
`file`	file	نعم	الملف المطلوب رفعه
`title`	string	لا	عنوان المستند

مثال

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/upload-doc' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F '[email protected]' \
  -F 'title=My PDF Document'

استجابة النجاح (200)

يعيد كائن المورد المنشأ.

11. رفع مورد ملف

ارفع ملفًا واحتفظ بتنسيقه الأصلي.

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/upload

Content-Type

multipart/form-data

أجزاء الطلب

المعامل	النوع	مطلوب	الوصف
`file`	file	نعم	الملف المطلوب رفعه

مثال

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/upload' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F '[email protected]'

استجابة النجاح (200)

يعيد كائن المورد المنشأ.

12. إضافة موارد URL

أضف عنوان URL واحدًا أو أكثر كموارد إلى LiveDoc.

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/urls

نص الطلب

المعامل	النوع	مطلوب	الوصف
`urls`	array	نعم	قائمة عناصر URL المطلوب إضافتها (1-10). ويمكن أن يكون كل عنصر سلسلة عادية أو كائنًا يحتوي `url` و`title` اختياريًا.

صيغ عنصر URL

يمكن أن يكون كل إدخال في urls إما:

سلسلة عادية: "https://example.com/article"
كائنًا: {"url": "https://example.com/article", "title": "Custom Title"}

الحقل	النوع	مطلوب	الوصف
`url`	string	نعم	عنوان URL المطلوب إضافته (5-2000 حرف)
`title`	string	لا	عنوان مخصص للمورد (بحد أقصى 1000 حرف). إذا حُذف، يُولَّد العنوان تلقائيًا من الصفحة.

مثال

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/urls' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": [
      "https://example.com/article-1",
      {"url": "https://example.com/article-2", "title": "My Custom Title"}
    ]
  }'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": [
    {
      "url": "https://example.com/article-1",
      "status": "success",
      "fail_reason": null,
      "resource_id": "res_003"
    },
    {
      "url": "https://example.com/article-2",
      "status": "existed",
      "fail_reason": null,
      "resource_id": "res_004"
    }
  ]
}

حقول نتيجة URL

الحقل	النوع	الوصف
`url`	string	عنوان URL المعالَج
`status`	string	حالة النتيجة: `success` أو `failed` أو `existed`
`fail_reason`	string	سبب الفشل (null إذا نجح)
`resource_id`	string	معرّف المورد المنشأ

13. حذف مورد

Endpoint

DELETE https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id}

مثال

curl -X DELETE 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001' \
  -H 'Authorization: Bearer YOUR_API_KEY'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": null
}

14. Retrieve (Semantic Search) (الاسترجاع الدلالي)

نفّذ استرجاعًا دلاليًا على موارد في LiveDoc.

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/retrieve

نص الطلب

المعامل	النوع	مطلوب	الوصف
`query`	string	نعم	محتوى الاستعلام للبحث الدلالي
`resource_ids`	string[]	لا	معرّفات موارد محددة للبحث داخلها (1-50). إذا حُذفت، يُوجَّه تلقائيًا إلى الموارد ذات الصلة حسب الاستعلام

مثال

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/retrieve' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "latest developments in large language models",
    "resource_ids": ["res_001", "res_002"]
  }'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": [
    {
      "id": "res_001",
      "title": "LLM Research Paper",
      "content": "Relevant content excerpt...",
      "score": 0.92,
      "metadata": {}
    }
  ]
}

Retrieve Result Fields (حقول نتيجة الاسترجاع)

الحقل	النوع	الوصف
`id`	string	معرّف المورد
`title`	string	عنوان المورد
`content`	string	المحتوى المطابق
`score`	number	درجة الصلة
`metadata`	object	بيانات وصفية إضافية

15. توجيه الموارد

وجّه الموارد ذات الصلة من LiveDoc بناءً على استعلام. يعيد قائمة بمعرّفات الموارد التي يمكن تمريرها إلى endpoint الاسترجاع.

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/route

نص الطلب

المعامل	النوع	مطلوب	الوصف
`query`	string	نعم	محتوى الاستعلام للتوجيه
`max_resources`	integer	لا	أقصى عدد من معرّفات الموارد المطلوب إرجاعها

مثال

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/route' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "latest developments in large language models",
    "max_resources": 5
  }'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": ["res_001", "res_003", "res_007"]
}

16. تنزيل ملف المصدر للمورد

احصل على ملف المصدر لمورد. يعيد إعادة توجيه 302 إلى عنوان URL الموقّع للتنزيل.

مدعوم فقط للموارد التي لديها ملف مصدر مرتبط (مثل المستندات المرفوعة).

Endpoint

GET https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id}/download

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

المعامل	النوع	مطلوب	الوصف
`expires_in`	integer	لا	انتهاء صلاحية عنوان URL بالثواني (الافتراضي: 3600)

مثال

curl -L 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001/download' \
  -H 'Authorization: Bearer YOUR_API_KEY'

الاستجابة

يعيد 302 Found مع رأس Location يشير إلى عنوان URL الموقّع للتنزيل من S3. وعملاء HTTP الذين يدعمون إعادة التوجيه (مثل curl -L) سيتبعون إعادة التوجيه وينزّلون الملف مباشرةً.

17. الحصول على محتوى المورد

اجلب المحتوى النصي المستخرج لمورد. مدعوم لمعظم أنواع الموارد (document وweb وvideo وai_doc وai_ppt وtext وvoice وmindmap وغيرها). ويعيد 400 للأنواع غير المدعومة مثل image.

Endpoint

GET https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id}/content

مثال

curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001/content' \
  -H 'Authorization: Bearer YOUR_API_KEY'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "title": "Q4 Financial Report",
    "type": "document",
    "content": "Full extracted text content of the resource..."
  }
}

حقول الاستجابة

الحقل	النوع	الوصف
`title`	string	عنوان المورد
`type`	string	نوع المورد
`content`	string	المحتوى النصي المستخرج

18. استرجاع صفحة PPT

نفّذ استرجاع محتوى عميق في صفحة محددة من مورد PPT. يزحف إلى صفحة الشريحة ويعيد أجزاء محتوى مرتبة. وتنسيق الاستجابة مطابق لـendpoint الاسترجاع.

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/ppt-retrieve

نص الطلب

المعامل	النوع	مطلوب	الوصف
`resource_id`	string	نعم	معرّف مورد PPT
`page_number`	integer	نعم	رقم الصفحة المطلوب استرجاعها (يبدأ من 1)
`query`	string	نعم	محتوى الاستعلام الذي يصف ما تبحث عنه
`max_chunk`	integer	لا	أقصى عدد من الأجزاء المطلوب إرجاعها (الافتراضي: 3)

مثال

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/ppt-retrieve' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "resource_id": "res_001",
    "page_number": 3,
    "query": "product pricing information",
    "max_chunk": 3
  }'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": [
    {
      "id": "res_001_page_3_chunk_1",
      "title": "Q4 Product Deck",
      "content": "Relevant slide content excerpt...",
      "score": null,
      "metadata": {
        "resource_id": "res_001",
        "page_number": 3,
        "index": 1
      }
    }
  ]
}

حقول الاستجابة

مثل حقول نتيجة الاسترجاع.

رموز الأخطاء

الرمز	حالة HTTP	الوصف
`UNAUTHORIZED`	401	مفتاح API غير صالح أو مُبطَل
`LIVEDOC_CREATE_FAILED`	502	فشل إنشاء LiveDoc
`LIVEDOC_UPDATE_FAILED`	502	فشل تحديث LiveDoc
`LIVEDOC_DELETE_FAILED`	502	فشل حذف LiveDoc
`LIVEDOC_NOT_FOUND`	404	LiveDoc غير موجود
`LIVEDOC_LIST_FAILED`	502	فشل سرد LiveDocs
`LIVEDOC_RESOURCE_CREATE_FAILED`	502	فشل إنشاء المورد
`LIVEDOC_RESOURCE_UPLOAD_FAILED`	502	فشل رفع المورد
`LIVEDOC_RESOURCE_DELETE_FAILED`	502	فشل حذف المورد
`LIVEDOC_RESOURCE_NOT_FOUND`	404	المورد غير موجود
`LIVEDOC_RESOURCE_LIST_FAILED`	502	فشل سرد الموارد
`LIVEDOC_RESOURCE_RETRIEVE_FAILED`	502	فشل استرجاع الموارد
`LIVEDOC_RESOURCE_ADD_URLS_FAILED`	502	فشل إضافة موارد URL

19. الحصول على README

احصل على محتوى README لـLiveDoc. يعيد سلسلة فارغة إذا لم يُضبط README.

Endpoint

GET https://openapi.felo.ai/v2/livedocs/{short_id}/readme

مثال

curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/readme' \
  -H 'Authorization: Bearer YOUR_API_KEY'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "summary": "A brief one-line description of the project.",
    "content": "# My LiveDoc\n\nThis is the README content in Markdown."
  }
}

حقول الاستجابة

الحقل	النوع	الوصف
`summary`	string \| null	وصف المشروع في سطر واحد. بحد أقصى 2000 حرف.
`content`	string	محتوى README (Markdown). سلسلة فارغة إذا لم يُضبط.

20. إنشاء README أو تحديثه

أنشئ README لـLiveDoc أو حدّثه (دلالات upsert).

Endpoint

PUT https://openapi.felo.ai/v2/livedocs/{short_id}/readme

نص الطلب

المعامل	النوع	مطلوب	الوصف
`summary`	string	لا	وصف المشروع في سطر واحد (بحد أقصى 2000 حرف)
`content`	string	لا	محتوى README (Markdown)

ملاحظة: يجب تقديم summary أو content على الأقل.

مثال

curl -X PUT 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/readme' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "summary": "A brief one-line description of the project.",
    "content": "# My LiveDoc\n\nThis is the README content in Markdown."
  }'

استجابة النجاح (200)

يعيد كائن README المحدّث (البنية نفسها كالحصول على README).

21. الإلحاق بـREADME

ألحق محتوى بنهاية README موجود. وإذا لم يوجد README، يُنشأ واحد جديد بالمحتوى المقدَّم.

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/readme/append

نص الطلب

المعامل	النوع	مطلوب	الوصف
`content`	string	نعم	المحتوى المطلوب إلحاقه (Markdown)

مثال

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/readme/append' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "\n\n## New Section\n\nAdditional content appended to README."
  }'

استجابة النجاح (200)

يعيد كائن README الكامل بعد الإلحاق (البنية نفسها كالحصول على README).

22. حذف README

احذف README الخاص بـLiveDoc.

Endpoint

DELETE https://openapi.felo.ai/v2/livedocs/{short_id}/readme

مثال

curl -X DELETE 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/readme' \
  -H 'Authorization: Bearer YOUR_API_KEY'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": null
}

23. سرد المهام

احصل على قائمة مقسّمة إلى صفحات بمهام LiveDoc. وتُرتَّب النتائج حسب sort تصاعديًا، ثم status تصاعديًا، ثم created_at تنازليًا.

Endpoint

GET https://openapi.felo.ai/v2/livedocs/{short_id}/tasks

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

المعامل	النوع	مطلوب	الوصف
`status`	integer	لا	التصفية حسب الحالة: `0`=TODO و`1`=IN_PROGRESS و`2`=DONE
`labels`	string[]	لا	التصفية حسب الوسوم (يجب أن تحتوي المهام على كل الوسوم المحددة)
`page`	integer	لا	رقم الصفحة (يبدأ من 1)
`size`	integer	لا	حجم الصفحة

مثال

curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks?status=0&page=1&size=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 1,
    "page": 1,
    "size": 20,
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "Write documentation",
        "description": "Write API documentation for the new endpoints",
        "status": 0,
        "sort": 0,
        "labels": ["docs", "priority-high"],
        "created_at": "2026-03-19T10:00:00Z",
        "modified_at": "2026-03-19T10:00:00Z"
      }
    ]
  }
}

حقول استجابة المهمة

الحقل	النوع	الوصف
`id`	string	معرّف المهمة (UUID)
`title`	string	عنوان المهمة
`description`	string	وصف المهمة
`status`	integer	حالة المهمة: `0`=TODO و`1`=IN_PROGRESS و`2`=DONE
`sort`	integer	ترتيب الفرز (غير سالب)
`labels`	string[]	قائمة الوسوم
`operated_by`	string	توقيع المشغّل، مثل `claude-code` و`openclaw`
`created_at`	string	طابع زمني للإنشاء (ISO 8601)
`modified_at`	string	طابع زمني لآخر تعديل (ISO 8601)

24. إنشاء مهمة

أنشئ مهمة جديدة في LiveDoc.

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/tasks

نص الطلب

المعامل	النوع	مطلوب	الوصف
`title`	string	نعم	عنوان المهمة
`description`	string	لا	وصف المهمة
`status`	integer	نعم	حالة المهمة: `0`=TODO و`1`=IN_PROGRESS و`2`=DONE
`sort`	integer	نعم	ترتيب الفرز (عدد صحيح غير سالب)
`labels`	string[]	لا	قائمة الوسوم (بحد أقصى 10، كل واحد بحد أقصى 50 حرفًا)
`operated_by`	string	لا	توقيع المشغّل، مثل `claude-code` و`openclaw` (بحد أقصى 100 حرف)

مثال

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Write documentation",
    "description": "Write API documentation for the new endpoints",
    "status": 0,
    "sort": 0,
    "labels": ["docs", "priority-high"]
  }'

استجابة النجاح (200)

يعيد كائن المهمة المنشأة (البنية نفسها كعناصر سرد المهام).

25. تحديث مهمة

حدّث مهمة جزئيًا. ولا تُحدَّث إلا الحقول المقدَّمة؛ وتحتفظ الحقول المحذوفة بقيمها الحالية.

Endpoint

PATCH https://openapi.felo.ai/v2/livedocs/{short_id}/tasks/{task_id}

نص الطلب

كل الحقول اختيارية.

المعامل	النوع	مطلوب	الوصف
`title`	string	لا	عنوان المهمة الجديد
`description`	string	لا	وصف المهمة الجديد
`status`	integer	لا	الحالة الجديدة: `0`=TODO و`1`=IN_PROGRESS و`2`=DONE
`sort`	integer	لا	ترتيب الفرز الجديد (غير سالب)
`labels`	string[]	لا	قائمة الوسوم الجديدة (بحد أقصى 10، كل واحد بحد أقصى 50 حرفًا)
`operated_by`	string	لا	توقيع المشغّل، مثل `claude-code` و`openclaw` (بحد أقصى 100 حرف)

مثال

curl -X PATCH 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": 1
  }'

استجابة النجاح (200)

يعيد كائن المهمة المحدّثة (البنية نفسها كعناصر سرد المهام).

26. حذف مهمة

احذف مهمة حذفًا ناعمًا.

Endpoint

DELETE https://openapi.felo.ai/v2/livedocs/{short_id}/tasks/{task_id}

مثال

curl -X DELETE 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_API_KEY'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": null
}

27. سرد سجلات المهام

احصل على قائمة مقسّمة إلى صفحات بسجلات مهمة (التعليقات وسجل التغييرات)، مرتبة حسب created_at تصاعديًا.

Endpoint

GET https://openapi.felo.ai/v2/livedocs/{short_id}/tasks/{task_id}/records

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

المعامل	النوع	مطلوب	الوصف
`record_type`	string	لا	التصفية حسب نوع السجل: `comment` أو `edit` أو `status_change`
`page`	integer	لا	رقم الصفحة (يبدأ من 1)
`size`	integer	لا	حجم الصفحة

مثال

curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks/550e8400-e29b-41d4-a716-446655440000/records' \
  -H 'Authorization: Bearer YOUR_API_KEY'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 2,
    "page": 1,
    "size": 20,
    "items": [
      {
        "id": "rec_001",
        "record_type": "comment",
        "content": "This is a comment",
        "meta": null,
        "task_id": "550e8400-e29b-41d4-a716-446655440000",
        "created_at": "2026-03-19T10:05:00Z",
        "modified_at": "2026-03-19T10:05:00Z"
      },
      {
        "id": "rec_002",
        "record_type": "status_change",
        "content": null,
        "meta": {"from": 0, "to": 1},
        "task_id": "550e8400-e29b-41d4-a716-446655440000",
        "created_at": "2026-03-19T10:10:00Z",
        "modified_at": "2026-03-19T10:10:00Z"
      }
    ]
  }
}

حقول استجابة سجل المهمة

الحقل	النوع	الوصف
`id`	string	معرّف السجل
`record_type`	string	نوع السجل: `comment` / `edit` / `status_change`
`content`	string	نص التعليق (فقط لنوع `comment`)
`meta`	object	تفاصيل التغيير (لنوعي `edit` و`status_change`)
`task_id`	string	معرّف المهمة الأصلية
`operated_by`	string	توقيع المشغّل، مثل `claude-code` و`openclaw`
`created_at`	string	طابع زمني للإنشاء (ISO 8601)
`modified_at`	string	طابع زمني لآخر تعديل (ISO 8601)

28. إضافة تعليق على مهمة

أضف تعليقًا إلى مهمة.

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/tasks/{task_id}/comments

نص الطلب

المعامل	النوع	مطلوب	الوصف
`content`	string	نعم	محتوى التعليق
`operated_by`	string	لا	توقيع المشغّل، مثل `claude-code` و`openclaw` (بحد أقصى 100 حرف)

مثال

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks/550e8400-e29b-41d4-a716-446655440000/comments' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "This task is now in progress."
  }'

استجابة النجاح (200)

يعيد كائن السجل المنشأ (البنية نفسها كعناصر سرد سجلات المهام).

رموز الأخطاء (المحدّثة)

الرمز	حالة HTTP	الوصف
`UNAUTHORIZED`	401	مفتاح API غير صالح أو مُبطَل
`LIVEDOC_CREATE_FAILED`	502	فشل إنشاء LiveDoc
`LIVEDOC_UPDATE_FAILED`	502	فشل تحديث LiveDoc
`LIVEDOC_DELETE_FAILED`	502	فشل حذف LiveDoc
`LIVEDOC_NOT_FOUND`	404	LiveDoc غير موجود
`LIVEDOC_LIST_FAILED`	502	فشل سرد LiveDocs
`LIVEDOC_RESOURCE_CREATE_FAILED`	502	فشل إنشاء المورد
`LIVEDOC_RESOURCE_UPLOAD_FAILED`	502	فشل رفع المورد
`LIVEDOC_RESOURCE_DELETE_FAILED`	502	فشل حذف المورد
`LIVEDOC_RESOURCE_NOT_FOUND`	404	المورد غير موجود
`LIVEDOC_RESOURCE_LIST_FAILED`	502	فشل سرد الموارد
`LIVEDOC_RESOURCE_RETRIEVE_FAILED`	502	فشل استرجاع الموارد
`LIVEDOC_RESOURCE_ADD_URLS_FAILED`	502	فشل إضافة موارد URL
`LIVEDOC_README_GET_FAILED`	502	فشل الحصول على README
`LIVEDOC_README_UPDATE_FAILED`	502	فشل إنشاء README أو تحديثه
`LIVEDOC_README_DELETE_FAILED`	502	فشل حذف README
`LIVEDOC_README_NOT_FOUND`	404	README غير موجود
`LIVEDOC_TASK_LIST_FAILED`	502	فشل سرد المهام
`LIVEDOC_TASK_CREATE_FAILED`	502	فشل إنشاء المهمة
`LIVEDOC_TASK_UPDATE_FAILED`	502	فشل تحديث المهمة
`LIVEDOC_TASK_DELETE_FAILED`	502	فشل حذف المهمة
`LIVEDOC_TASK_NOT_FOUND`	404	المهمة غير موجودة
`LIVEDOC_TASK_RECORD_LIST_FAILED`	502	فشل سرد سجلات المهام
`LIVEDOC_TASK_COMMENT_CREATE_FAILED`	502	فشل إنشاء تعليق المهمة