LiveDoc API

The LiveDoc API provides full CRUD operations for LiveDocs and their resources, including document creation, file upload, URL import, and semantic retrieval.

Authentication

All requests require an API Key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

1. Create LiveDoc

Endpoint

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

Request Body

Example

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

Success Response (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

2. List LiveDocs

Endpoint

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

Query Parameters

Example

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

Success Response (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..."
        }
      }
    ]
  }
}

Response Fields

Each item in items contains the same fields as the Create LiveDoc response, plus:

Endpoint

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

Request Body

Example

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

Success Response (200)

Returns the updated LiveDoc object (same structure as Create).

4. Delete LiveDoc

Endpoint

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

Example

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

Success Response (200)

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

5. List Resources

Endpoint

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

Query Parameters

Example

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

Success Response (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"
      }
    ]
  }
}

Resource Response Fields

6. Get Single Resource

Endpoint

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

Example

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

Success Response (200)

Returns a single resource object (same structure as items in List Resources).

7. Update Resource

Update a resource's title, snippet, or thumbnail. Only provided fields are updated; omitted fields retain their current values.

Endpoint

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

Request Body

All fields are optional.

Example

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

Success Response (200)

Returns the updated resource object (same structure as items in List Resources).

8. Update Resource Content

Update the Markdown content of an ai_doc resource. Only supported for resources with resource_type == ai_doc. The snippet field is automatically updated from the first 2000 bytes of the new content.

Endpoint

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

Request Body

Example

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

Success Response (200)

Returns the updated resource object (same structure as items in List Resources).

9. Create Document Resource

Endpoint

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

Request Body

Example

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

Success Response (200)

Returns the created resource object.

10. Upload File as Document

Upload a file and convert it to a document resource (ai_doc type).

Endpoint

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

Content-Type

multipart/form-data

Request Parts

Example

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'

Success Response (200)

Returns the created resource object.

11. Upload File Resource

Upload a file and keep its original format.

Endpoint

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

Content-Type

multipart/form-data

Request Parts

Example

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

Success Response (200)

Returns the created resource object.

12. Add URL Resources

Add one or more URLs as resources to a LiveDoc.

Endpoint

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

Request Body

URL Item Formats

Each entry in urls can be either:

• A plain string: "https://example.com/article"
• An object: {"url": "https://example.com/article", "title": "Custom Title"}

Example

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

Success Response (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 Result Fields

13. Delete Resource

Endpoint

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

Example

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

Success Response (200)

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

14. Retrieve (Semantic Search)

Perform semantic retrieval against resources in a LiveDoc.

Endpoint

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

Request Body

Example

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

Success Response (200)

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

Retrieve Result Fields

15. Route Resources

Route relevant resources from a LiveDoc based on a query. Returns a list of resource IDs that can be passed to the retrieve endpoint.

Endpoint

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

Request Body

Example

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

Success Response (200)

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

16. Download Resource Source File

Get the source file of a resource. Returns a 302 redirect to the presigned download URL.

Only supported for resources that have an associated source file (e.g. uploaded documents).

Endpoint

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

Query Parameters

Example

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

Response

Returns 302 Found with a Location header pointing to the presigned S3 download URL. HTTP clients with redirect support (e.g. curl -L) will follow the redirect and download the file directly.

17. Get Resource Content

Fetch the extracted text content of a resource. Supported for most resource types (document, web, video, ai_doc, ai_ppt, text, voice, mindmap, etc.). Returns 400 for unsupported types such as image.

Endpoint

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

Example

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

Success Response (200)

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

Response Fields

18. PPT Page Retrieve

Perform deep content retrieval on a specific page of a PPT resource. Scrapes the slide page and returns ranked content chunks. The response format is identical to the Retrieve endpoint.

Endpoint

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

Request Body

Example

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

Success Response (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
      }
    }
  ]
}

Response Fields

Same as Retrieve Result Fields.

Error Codes

19. Get README

Get the README content of a LiveDoc. Returns an empty string if no README has been set.

Endpoint

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

Example

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

Success Response (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."
  }
}

Response Fields

20. Create or Update README

Create or update the README of a LiveDoc (upsert semantics).

Endpoint

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

Request Body

Note: At least one of summary or content must be provided.

Example

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

Success Response (200)

Returns the updated README object (same structure as Get README).

21. Append to README

Append content to the end of an existing README. If no README exists, creates a new one with the provided content.

Endpoint

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

Request Body

Example

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

Success Response (200)

Returns the complete README object after appending (same structure as Get README).

22. Delete README

Delete the README of a LiveDoc.

Endpoint

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

Example

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

Success Response (200)

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

23. List Tasks

Get a paginated list of tasks in a LiveDoc. Results are sorted by sort asc, status asc, created_at desc.

Endpoint

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

Query Parameters

Example

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

Success Response (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"
      }
    ]
  }
}

Task Response Fields

24. Create Task

Create a new task in a LiveDoc.

Endpoint

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

Request Body

Example

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

Success Response (200)

Returns the created task object (same structure as items in List Tasks).

25. Update Task

Partially update a task. Only provided fields are updated; omitted fields retain their current values.

Endpoint

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

Request Body

All fields are optional.

Example

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

Success Response (200)

Returns the updated task object (same structure as items in List Tasks).

26. Delete Task

Soft-delete a task.

Endpoint

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

Example

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

Success Response (200)

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

27. List Task Records

Get a paginated list of records for a task (comments and change history), sorted by created_at ascending.

Endpoint

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

Query Parameters

Example

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

Success Response (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"
      }
    ]
  }
}

Task Record Response Fields

28. Add Task Comment

Add a comment to a task.

Endpoint

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

Request Body

Example

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

Success Response (200)

Returns the created record object (same structure as items in List Task Records).

Error Codes (Updated)