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 برای LiveDocها و منابع آن‌ها را فراهم می‌کند، از جمله ساخت سند، بارگذاری فایل، وارد کردن URL و بازیابی معنایی.

احراز هویت

همه درخواست‌ها به یک کلید API در سرآیند Authorization نیاز دارند:

Authorization: Bearer YOUR_API_KEY

استفاده با عامل‌های هوش مصنوعی

بسته کامل felo-ai را نصب کنید تا یک عامل پشتیبانی LiveDoc و هر Felo Skill در دسترس دیگر را دریافت کند. نصب‌کننده به‌صورت پویا هر پوشه بسته شامل SKILL.md را کشف می‌کند، از جمله افزوده‌های آینده بسته. همه Skillهای کشف‌شده را در پوشه بومی عامل نصب کنید: 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. فهرست LiveDocها

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. اگر README وجود نداشته باشد `null` است.
`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 و غیره) پشتیبانی می‌شود. برای نوع‌های پشتیبانی‌نشده مانند image کد 400 برمی‌گرداند.

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 Retrieve یکسان است.

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
      }
    }
  ]
}

فیلدهای پاسخ

همان Retrieve Result Fields است.

کدهای خطا

کد	وضعیت 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	فهرست‌کردن LiveDocها شکست خورد
`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 وجود نداشته باشد، 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	فهرست‌کردن LiveDocها شکست خورد
`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	ساخت دیدگاه وظیفه شکست خورد