Felo APIs

LiveDoc API

Tạo cơ sở tri thức, quản lý tài nguyên và chạy truy xuất ngữ nghĩa cùng định tuyến.

POST/v2/livedocs

Xác thực

Bearer API key

Loại nội dung

application/json or multipart/form-data

Ghi chú về giới hạn

Có thể áp dụng giới hạn riêng cho endpoint.

SuperAgent API PPT Task API

LiveDoc API cung cấp đầy đủ các thao tác CRUD cho LiveDoc và tài nguyên của chúng, bao gồm tạo tài liệu, tải tệp lên, nhập URL và truy xuất ngữ nghĩa.

Xác thực

Mọi yêu cầu đều cần khóa API trong header Authorization:

Authorization: Bearer YOUR_API_KEY

Dùng với AI Agent

Cài gói felo-ai đầy đủ để cung cấp cho một Agent khả năng hỗ trợ LiveDoc và mọi Felo Skill khác hiện có. Trình cài đặt tự động khám phá mọi thư mục gói có chứa SKILL.md, bao gồm các bổ sung gói trong tương lai. Hãy cài mọi Skill được phát hiện vào thư mục gốc của Agent: Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills hoặc Hermes Agent ~/.hermes/skills. Hướng dẫn thiết lập AI Agent thủ công trình bày các bước khóa API và xác minh riêng cho từng nền tảng.

1. Tạo LiveDoc

Endpoint

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

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`name`	string	Có	Tên LiveDoc
`description`	string	Không	Mô tả LiveDoc
`icon`	string	Không	Biểu tượng LiveDoc

Ví dụ

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"
  }'

Phản hồi thành công (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"
  }
}

Các trường phản hồi

Trường	Kiểu	Mô tả
`short_id`	string	ID LiveDoc
`name`	string	Tên LiveDoc
`description`	string	Mô tả LiveDoc
`icon`	string	Biểu tượng LiveDoc
`created_at`	string	Dấu thời gian tạo (ISO 8601)
`modified_at`	string	Dấu thời gian sửa đổi lần cuối (ISO 8601)
`is_shared`	boolean	LiveDoc này có được chia sẻ với người dùng hiện tại hay không (không thuộc sở hữu của họ)

2. Liệt kê LiveDoc

Endpoint

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

Tham số truy vấn

Tham số	Kiểu	Bắt buộc	Mô tả
`keyword`	string	Không	Lọc theo từ khóa
`page`	integer	Không	Số trang (bắt đầu từ 1)
`size`	integer	Không	Kích thước trang

Ví dụ

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

Phản hồi thành công (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..."
        }
      }
    ]
  }
}

Các trường phản hồi

Mỗi mục trong items chứa các trường giống như phản hồi Tạo LiveDoc, cộng thêm:

Trường	Kiểu	Mô tả
`readme`	object \| null	Thông tin README. `null` nếu không có README.
`readme.summary`	string \| null	Mô tả dự án một dòng
`readme.content`	string \| null	Nội dung README (Markdown)

Endpoint

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

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`name`	string	Không	Tên LiveDoc mới
`description`	string	Không	Mô tả LiveDoc mới

Ví dụ

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"
  }'

Phản hồi thành công (200)

Trả về đối tượng LiveDoc đã cập nhật (cấu trúc giống như Tạo).

4. Xóa LiveDoc

Endpoint

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

Ví dụ

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

Phản hồi thành công (200)

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

5. Liệt kê tài nguyên

Endpoint

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

Tham số truy vấn

Tham số	Kiểu	Bắt buộc	Mô tả
`resource_types`	string[]	Không	Lọc theo loại tài nguyên
`page`	integer	Không	Số trang (bắt đầu từ 1)
`size`	integer	Không	Kích thước trang

Ví dụ

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

Phản hồi thành công (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"
      }
    ]
  }
}

Các trường phản hồi tài nguyên

Trường	Kiểu	Mô tả
`id`	string	ID tài nguyên
`title`	string	Tiêu đề tài nguyên
`link`	string	Liên kết/URL tài nguyên
`snippet`	string	Tóm tắt tài nguyên
`thumbnail`	string	URL ảnh thu nhỏ
`resource_type`	string	Loại tài nguyên (ví dụ `web`, `ai_doc`, `file`)
`resource_key`	string	Khóa liên kết tài nguyên
`status`	string	Trạng thái tài nguyên
`source`	string	Nguồn tài nguyên
`created_at`	string	Dấu thời gian tạo (ISO 8601)
`modified_at`	string	Dấu thời gian sửa đổi lần cuối (ISO 8601)

6. Lấy một tài nguyên

Endpoint

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

Ví dụ

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

Phản hồi thành công (200)

Trả về một đối tượng tài nguyên (cấu trúc giống như các mục trong Liệt kê tài nguyên).

7. Cập nhật tài nguyên

Cập nhật title, snippet hoặc thumbnail của một tài nguyên. Chỉ các trường được cung cấp mới được cập nhật; các trường bỏ qua giữ nguyên giá trị hiện tại.

Endpoint

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

Nội dung yêu cầu

Mọi trường đều tùy chọn.

Tham số	Kiểu	Bắt buộc	Mô tả
`title`	string	Không	Tiêu đề tài nguyên mới (tối đa 500 ký tự)
`snippet`	string	Không	Tóm tắt tài nguyên mới (tối đa 2000 ký tự)
`thumbnail`	string	Không	URL ảnh thu nhỏ mới (tối đa 2000 ký tự)

Ví dụ

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."
  }'

Phản hồi thành công (200)

Trả về đối tượng tài nguyên đã cập nhật (cấu trúc giống như các mục trong Liệt kê tài nguyên).

8. Cập nhật nội dung tài nguyên

Cập nhật nội dung Markdown của một tài nguyên ai_doc. Chỉ hỗ trợ cho các tài nguyên có resource_type == ai_doc. Trường snippet được tự động cập nhật từ 2000 byte đầu tiên của nội dung mới.

Endpoint

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

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`content`	string	Có	Nội dung Markdown mới cho tài nguyên

Ví dụ

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."
  }'

Phản hồi thành công (200)

Trả về đối tượng tài nguyên đã cập nhật (cấu trúc giống như các mục trong Liệt kê tài nguyên).

9. Tạo tài nguyên tài liệu

Endpoint

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

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`title`	string	Không	Tiêu đề tài liệu (mặc định là "New Document")
`content`	string	Có	Nội dung tài liệu

Ví dụ

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..."
  }'

Phản hồi thành công (200)

Trả về đối tượng tài nguyên đã tạo.

10. Tải tệp lên dưới dạng tài liệu

Tải một tệp lên và chuyển nó thành tài nguyên tài liệu (loại ai_doc).

Endpoint

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

Content-Type

multipart/form-data

Các phần yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`file`	file	Có	Tệp cần tải lên
`title`	string	Không	Tiêu đề tài liệu

Ví dụ

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'

Phản hồi thành công (200)

Trả về đối tượng tài nguyên đã tạo.

11. Tải tệp lên làm tài nguyên

Tải một tệp lên và giữ nguyên định dạng gốc của nó.

Endpoint

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

Content-Type

multipart/form-data

Các phần yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`file`	file	Có	Tệp cần tải lên

Ví dụ

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

Phản hồi thành công (200)

Trả về đối tượng tài nguyên đã tạo.

12. Thêm tài nguyên URL

Thêm một hoặc nhiều URL làm tài nguyên cho một LiveDoc.

Endpoint

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

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`urls`	array	Có	Danh sách các mục URL cần thêm (1-10). Mỗi mục có thể là chuỗi thuần hoặc một đối tượng có `url` và `title` tùy chọn.

Định dạng mục URL

Mỗi mục trong urls có thể là một trong hai:

Chuỗi thuần: "https://example.com/article"
Một đối tượng: {"url": "https://example.com/article", "title": "Custom Title"}

Trường	Kiểu	Bắt buộc	Mô tả
`url`	string	Có	URL cần thêm (5-2000 ký tự)
`title`	string	Không	Tiêu đề tùy chỉnh cho tài nguyên (tối đa 1000 ký tự). Nếu bỏ qua, tiêu đề được tự động tạo từ trang.

Ví dụ

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

Phản hồi thành công (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"
    }
  ]
}

Các trường kết quả URL

Trường	Kiểu	Mô tả
`url`	string	URL đã xử lý
`status`	string	Trạng thái kết quả: `success`, `failed` hoặc `existed`
`fail_reason`	string	Lý do thất bại (null nếu thành công)
`resource_id`	string	ID tài nguyên đã tạo

13. Xóa tài nguyên

Endpoint

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

Ví dụ

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

Phản hồi thành công (200)

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

14. Truy xuất (tìm kiếm ngữ nghĩa)

Thực hiện truy xuất ngữ nghĩa trên các tài nguyên trong một LiveDoc.

Endpoint

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

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`query`	string	Có	Nội dung truy vấn cho tìm kiếm ngữ nghĩa
`resource_ids`	string[]	Không	Các ID tài nguyên cụ thể để tìm kiếm bên trong (1-50). Nếu bỏ qua, các tài nguyên liên quan được tự động định tuyến theo truy vấn

Ví dụ

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

Phản hồi thành công (200)

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

Các trường kết quả truy xuất

Trường	Kiểu	Mô tả
`id`	string	ID tài nguyên
`title`	string	Tiêu đề tài nguyên
`content`	string	Nội dung khớp
`score`	number	Điểm liên quan
`metadata`	object	Siêu dữ liệu bổ sung

15. Định tuyến tài nguyên

Định tuyến các tài nguyên liên quan từ một LiveDoc dựa trên truy vấn. Trả về danh sách ID tài nguyên có thể được truyền cho endpoint truy xuất.

Endpoint

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

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`query`	string	Có	Nội dung truy vấn cho việc định tuyến
`max_resources`	integer	Không	Số ID tài nguyên tối đa cần trả về

Ví dụ

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

Phản hồi thành công (200)

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

16. Tải xuống tệp nguồn của tài nguyên

Lấy tệp nguồn của một tài nguyên. Trả về chuyển hướng 302 đến URL tải xuống đã ký trước.

Chỉ hỗ trợ cho các tài nguyên có tệp nguồn liên kết (ví dụ tài liệu đã tải lên).

Endpoint

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

Tham số truy vấn

Tham số	Kiểu	Bắt buộc	Mô tả
`expires_in`	integer	Không	Thời hạn URL tính bằng giây (mặc định: 3600)

Ví dụ

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

Phản hồi

Trả về 302 Found với header Location trỏ đến URL tải xuống S3 đã ký trước. Các HTTP client hỗ trợ chuyển hướng (ví dụ curl -L) sẽ theo chuyển hướng và tải tệp trực tiếp.

17. Lấy nội dung tài nguyên

Lấy nội dung văn bản đã trích xuất của một tài nguyên. Hỗ trợ cho hầu hết các loại tài nguyên (document, web, video, ai_doc, ai_ppt, text, voice, mindmap, v.v.). Trả về 400 cho các loại không được hỗ trợ như image.

Endpoint

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

Ví dụ

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

Phản hồi thành công (200)

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

Các trường phản hồi

Trường	Kiểu	Mô tả
`title`	string	Tiêu đề tài nguyên
`type`	string	Loại tài nguyên
`content`	string	Nội dung văn bản đã trích xuất

18. Truy xuất trang PPT

Thực hiện truy xuất nội dung chuyên sâu trên một trang cụ thể của tài nguyên PPT. Thu thập trang slide và trả về các đoạn nội dung đã xếp hạng. Định dạng phản hồi giống hệt endpoint Truy xuất.

Endpoint

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

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`resource_id`	string	Có	ID tài nguyên PPT
`page_number`	integer	Có	Số trang cần truy xuất (bắt đầu từ 1)
`query`	string	Có	Nội dung truy vấn mô tả nội dung cần tìm
`max_chunk`	integer	Không	Số đoạn tối đa cần trả về (mặc định: 3)

Ví dụ

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

Phản hồi thành công (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
      }
    }
  ]
}

Các trường phản hồi

Giống như Các trường kết quả truy xuất.

Mã lỗi

Mã	Trạng thái HTTP	Mô tả
`UNAUTHORIZED`	401	Khóa API không hợp lệ hoặc đã bị thu hồi
`LIVEDOC_CREATE_FAILED`	502	Tạo LiveDoc thất bại
`LIVEDOC_UPDATE_FAILED`	502	Cập nhật LiveDoc thất bại
`LIVEDOC_DELETE_FAILED`	502	Xóa LiveDoc thất bại
`LIVEDOC_NOT_FOUND`	404	Không tìm thấy LiveDoc
`LIVEDOC_LIST_FAILED`	502	Liệt kê LiveDoc thất bại
`LIVEDOC_RESOURCE_CREATE_FAILED`	502	Tạo tài nguyên thất bại
`LIVEDOC_RESOURCE_UPLOAD_FAILED`	502	Tải tài nguyên lên thất bại
`LIVEDOC_RESOURCE_DELETE_FAILED`	502	Xóa tài nguyên thất bại
`LIVEDOC_RESOURCE_NOT_FOUND`	404	Không tìm thấy tài nguyên
`LIVEDOC_RESOURCE_LIST_FAILED`	502	Liệt kê tài nguyên thất bại
`LIVEDOC_RESOURCE_RETRIEVE_FAILED`	502	Truy xuất tài nguyên thất bại
`LIVEDOC_RESOURCE_ADD_URLS_FAILED`	502	Thêm tài nguyên URL thất bại

19. Lấy README

Lấy nội dung README của một LiveDoc. Trả về chuỗi rỗng nếu chưa thiết lập README.

Endpoint

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

Ví dụ

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

Phản hồi thành công (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."
  }
}

Các trường phản hồi

Trường	Kiểu	Mô tả
`summary`	string \| null	Mô tả dự án một dòng. Tối đa 2000 ký tự.
`content`	string	Nội dung README (Markdown). Chuỗi rỗng nếu chưa thiết lập.

20. Tạo hoặc cập nhật README

Tạo hoặc cập nhật README của một LiveDoc (ngữ nghĩa upsert).

Endpoint

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

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`summary`	string	Không	Mô tả dự án một dòng (tối đa 2000 ký tự)
`content`	string	Không	Nội dung README (Markdown)

Lưu ý: Phải cung cấp ít nhất một trong summary hoặc content.

Ví dụ

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."
  }'

Phản hồi thành công (200)

Trả về đối tượng README đã cập nhật (cấu trúc giống như Lấy README).

21. Nối thêm vào README

Nối nội dung vào cuối một README hiện có. Nếu chưa có README, tạo mới với nội dung được cung cấp.

Endpoint

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

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`content`	string	Có	Nội dung cần nối thêm (Markdown)

Ví dụ

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."
  }'

Phản hồi thành công (200)

Trả về đối tượng README đầy đủ sau khi nối thêm (cấu trúc giống như Lấy README).

22. Xóa README

Xóa README của một LiveDoc.

Endpoint

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

Ví dụ

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

Phản hồi thành công (200)

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

23. Liệt kê tác vụ

Lấy danh sách tác vụ có phân trang trong một LiveDoc. Kết quả được sắp xếp theo sort tăng dần, status tăng dần, created_at giảm dần.

Endpoint

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

Tham số truy vấn

Tham số	Kiểu	Bắt buộc	Mô tả
`status`	integer	Không	Lọc theo trạng thái: `0`=TODO, `1`=IN_PROGRESS, `2`=DONE
`labels`	string[]	Không	Lọc theo nhãn (tác vụ phải chứa tất cả nhãn được chỉ định)
`page`	integer	Không	Số trang (bắt đầu từ 1)
`size`	integer	Không	Kích thước trang

Ví dụ

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

Phản hồi thành công (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"
      }
    ]
  }
}

Các trường phản hồi tác vụ

Trường	Kiểu	Mô tả
`id`	string	ID tác vụ (UUID)
`title`	string	Tiêu đề tác vụ
`description`	string	Mô tả tác vụ
`status`	integer	Trạng thái tác vụ: `0`=TODO, `1`=IN_PROGRESS, `2`=DONE
`sort`	integer	Thứ tự sắp xếp (không âm)
`labels`	string[]	Danh sách nhãn
`operated_by`	string	Chữ ký người thao tác, ví dụ `claude-code`, `openclaw`
`created_at`	string	Dấu thời gian tạo (ISO 8601)
`modified_at`	string	Dấu thời gian sửa đổi lần cuối (ISO 8601)

24. Tạo tác vụ

Tạo một tác vụ mới trong một LiveDoc.

Endpoint

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

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`title`	string	Có	Tiêu đề tác vụ
`description`	string	Không	Mô tả tác vụ
`status`	integer	Có	Trạng thái tác vụ: `0`=TODO, `1`=IN_PROGRESS, `2`=DONE
`sort`	integer	Có	Thứ tự sắp xếp (số nguyên không âm)
`labels`	string[]	Không	Danh sách nhãn (tối đa 10, mỗi nhãn tối đa 50 ký tự)
`operated_by`	string	Không	Chữ ký người thao tác, ví dụ `claude-code`, `openclaw` (tối đa 100 ký tự)

Ví dụ

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

Phản hồi thành công (200)

Trả về đối tượng tác vụ đã tạo (cấu trúc giống như các mục trong Liệt kê tác vụ).

25. Cập nhật tác vụ

Cập nhật một phần của tác vụ. Chỉ các trường được cung cấp mới được cập nhật; các trường bỏ qua giữ nguyên giá trị hiện tại.

Endpoint

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

Nội dung yêu cầu

Mọi trường đều tùy chọn.

Tham số	Kiểu	Bắt buộc	Mô tả
`title`	string	Không	Tiêu đề tác vụ mới
`description`	string	Không	Mô tả tác vụ mới
`status`	integer	Không	Trạng thái mới: `0`=TODO, `1`=IN_PROGRESS, `2`=DONE
`sort`	integer	Không	Thứ tự sắp xếp mới (không âm)
`labels`	string[]	Không	Danh sách nhãn mới (tối đa 10, mỗi nhãn tối đa 50 ký tự)
`operated_by`	string	Không	Chữ ký người thao tác, ví dụ `claude-code`, `openclaw` (tối đa 100 ký tự)

Ví dụ

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

Phản hồi thành công (200)

Trả về đối tượng tác vụ đã cập nhật (cấu trúc giống như các mục trong Liệt kê tác vụ).

26. Xóa tác vụ

Xóa mềm một tác vụ.

Endpoint

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

Ví dụ

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

Phản hồi thành công (200)

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

27. Liệt kê bản ghi tác vụ

Lấy danh sách bản ghi có phân trang của một tác vụ (bình luận và lịch sử thay đổi), được sắp xếp theo created_at tăng dần.

Endpoint

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

Tham số truy vấn

Tham số	Kiểu	Bắt buộc	Mô tả
`record_type`	string	Không	Lọc theo loại bản ghi: `comment`, `edit`, `status_change`
`page`	integer	Không	Số trang (bắt đầu từ 1)
`size`	integer	Không	Kích thước trang

Ví dụ

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

Phản hồi thành công (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"
      }
    ]
  }
}

Các trường phản hồi bản ghi tác vụ

Trường	Kiểu	Mô tả
`id`	string	ID bản ghi
`record_type`	string	Loại bản ghi: `comment` / `edit` / `status_change`
`content`	string	Nội dung bình luận (chỉ với loại `comment`)
`meta`	object	Chi tiết thay đổi (với loại `edit` và `status_change`)
`task_id`	string	ID tác vụ cha
`operated_by`	string	Chữ ký người thao tác, ví dụ `claude-code`, `openclaw`
`created_at`	string	Dấu thời gian tạo (ISO 8601)
`modified_at`	string	Dấu thời gian sửa đổi lần cuối (ISO 8601)

28. Thêm bình luận cho tác vụ

Thêm một bình luận vào tác vụ.

Endpoint

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

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`content`	string	Có	Nội dung bình luận
`operated_by`	string	Không	Chữ ký người thao tác, ví dụ `claude-code`, `openclaw` (tối đa 100 ký tự)

Ví dụ

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."
  }'

Phản hồi thành công (200)

Trả về đối tượng bản ghi đã tạo (cấu trúc giống như các mục trong Liệt kê bản ghi tác vụ).

Mã lỗi (cập nhật)

Mã	Trạng thái HTTP	Mô tả
`UNAUTHORIZED`	401	Khóa API không hợp lệ hoặc đã bị thu hồi
`LIVEDOC_CREATE_FAILED`	502	Tạo LiveDoc thất bại
`LIVEDOC_UPDATE_FAILED`	502	Cập nhật LiveDoc thất bại
`LIVEDOC_DELETE_FAILED`	502	Xóa LiveDoc thất bại
`LIVEDOC_NOT_FOUND`	404	Không tìm thấy LiveDoc
`LIVEDOC_LIST_FAILED`	502	Liệt kê LiveDoc thất bại
`LIVEDOC_RESOURCE_CREATE_FAILED`	502	Tạo tài nguyên thất bại
`LIVEDOC_RESOURCE_UPLOAD_FAILED`	502	Tải tài nguyên lên thất bại
`LIVEDOC_RESOURCE_DELETE_FAILED`	502	Xóa tài nguyên thất bại
`LIVEDOC_RESOURCE_NOT_FOUND`	404	Không tìm thấy tài nguyên
`LIVEDOC_RESOURCE_LIST_FAILED`	502	Liệt kê tài nguyên thất bại
`LIVEDOC_RESOURCE_RETRIEVE_FAILED`	502	Truy xuất tài nguyên thất bại
`LIVEDOC_RESOURCE_ADD_URLS_FAILED`	502	Thêm tài nguyên URL thất bại
`LIVEDOC_README_GET_FAILED`	502	Lấy README thất bại
`LIVEDOC_README_UPDATE_FAILED`	502	Tạo hoặc cập nhật README thất bại
`LIVEDOC_README_DELETE_FAILED`	502	Xóa README thất bại
`LIVEDOC_README_NOT_FOUND`	404	Không tìm thấy README
`LIVEDOC_TASK_LIST_FAILED`	502	Liệt kê tác vụ thất bại
`LIVEDOC_TASK_CREATE_FAILED`	502	Tạo tác vụ thất bại
`LIVEDOC_TASK_UPDATE_FAILED`	502	Cập nhật tác vụ thất bại
`LIVEDOC_TASK_DELETE_FAILED`	502	Xóa tác vụ thất bại
`LIVEDOC_TASK_NOT_FOUND`	404	Không tìm thấy tác vụ
`LIVEDOC_TASK_RECORD_LIST_FAILED`	502	Liệt kê bản ghi tác vụ thất bại
`LIVEDOC_TASK_COMMENT_CREATE_FAILED`	502	Tạo bình luận cho tác vụ thất bại