# LiveDoc API

Створюйте бази знань, керуйте ресурсами та запускайте семантичний пошук і маршрутизацію.

Ця сторінка документує наявні `/v2` Felo APIs, які використовують **права облікового запису Felo та правила Pro-кредитів**. Чи будуть списані кредити, залежить від [операції](https://openapi.felo.ai/uk/docs/faq/billing-and-credits.md#v2). Для викликів із балансу платформи обирайте підтримувану [кінцеву точку Felo OpenAPI](https://openapi.felo.ai/uk/docs/api-reference/openapi/overview.md); форми запиту й відповіді можуть відрізнятися.

Веб-URL LiveDoc мають формат `https://felo.ai/livedoc/{short_id}`. Може знадобитися браузерна сесія з доступом до цього LiveDoc. Зберігайте назви полів API для кожної кінцевої точки: SuperAgent повертає `live_doc_short_id`, тоді як створення mindmap і PPT повертає `livedoc_short_id`.

LiveDoc API надає повні CRUD-операції для LiveDocs і їхніх ресурсів, включно зі створенням документів, завантаженням файлів, імпортом URL і семантичним retrieval.

## Використання з AI Agents

Встановіть повний пакет `felo-ai`, щоб надати Agent підтримку LiveDoc і всі інші доступні Felo Skills. Інсталятор динамічно виявляє кожен каталог пакета, що містить `SKILL.md`, включно з майбутніми доповненнями пакетів. Встановлюйте всі виявлені Skills у нативний каталог Agent: Codex `~/.codex/skills`, Claude Code `~/.claude/skills`, OpenClaw `~/.agents/skills` або Hermes Agent `~/.hermes/skills`. [Посібник із ручного налаштування AI Agent](https://openapi.felo.ai/uk/docs/felo-skills.md) охоплює окремі API key і кроки перевірки для кожної платформи.


## Автентифікація

Усі запити потребують API Key у заголовку `Authorization`:

```
Authorization: Bearer YOUR_API_KEY
```

---

## 1. Створення LiveDoc

### Кінцева точка

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

### Тіло запиту

| Параметр | Тип | Обов’язковий | Опис |
|-----------|------|----------|-------------|
| `name` | string | Так | Назва LiveDoc |
| `description` | string | Ні | Опис LiveDoc |
| `icon` | string | Ні | Іконка LiveDoc |

### Приклад

```bash
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)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "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"
  }
}
```
### Поля відповіді

| Поле | Тип | Опис |
|-------|------|-------------|
| `short_id` | string | ID 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

### Кінцева точка

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

### Параметри запиту

| Параметр | Тип | Обов’язковий | Опис |
|-----------|------|----------|-------------|
| `keyword` | string | Ні | Фільтрація за ключовим словом |
| `page` | integer | Ні | Номер сторінки (нумерація з 1) |
| `size` | integer | Ні | Розмір сторінки |

### Приклад

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

### Успішна відповідь (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "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` містить ті самі поля, що й [відповідь Create LiveDoc](#section-5), а також:

| Поле | Тип | Опис |
|-------|------|-------------|
| `readme` | object \| null | Інформація README. `null`, якщо README не існує. |
| `readme.summary` | string \| null | Однорядковий опис проєкту |
| `readme.content` | string \| null | Вміст README (Markdown) |

---

### Кінцева точка

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

### Тіло запиту

| Параметр | Тип | Обов’язковий | Опис |
|-----------|------|----------|-------------|
| `name` | string | Ні | Нова назва LiveDoc |
| `description` | string | Ні | Новий опис LiveDoc |

### Приклад

```bash
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 (та сама структура, що й у Create).

---

## 4. Видалення LiveDoc

### Кінцева точка

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

### Приклад

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

### Успішна відповідь (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "message": null,
  "data": null
}
```
---

## 5. Список ресурсів

### Кінцева точка

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

### Параметри запиту

| Параметр | Тип | Обов’язковий | Опис |
|-----------|------|----------|-------------|
| `resource_types` | string[] | Ні | Фільтрація за типами ресурсів |
| `page` | integer | Ні | Номер сторінки (нумерація з 1) |
| `size` | integer | Ні | Розмір сторінки |

### Приклад

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

### Успішна відповідь (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "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 | ID ресурсу |
| `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. Отримання одного ресурсу

### Кінцева точка

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

### Приклад

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

### Успішна відповідь (200)

Повертає один об’єкт ресурсу (та сама структура, що й елементи в List Resources).

---

## 7. Оновлення ресурсу

Оновіть `title`, `snippet` або `thumbnail` ресурсу. Оновлюються лише надані поля; пропущені поля зберігають свої поточні значення.

### Кінцева точка

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

### Тіло запиту

Усі поля необов’язкові.

| Параметр | Тип | Обов’язковий | Опис |
|-----------|------|----------|-------------|
| `title` | string | Ні | Новий заголовок ресурсу (максимум 500 символів) |
| `snippet` | string | Ні | Новий підсумок ресурсу (максимум 2000 символів) |
| `thumbnail` | string | Ні | Новий URL мініатюри (максимум 2000 символів) |

### Приклад

```bash
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)

Повертає оновлений об’єкт ресурсу (та сама структура, що й елементи в List Resources).

---

## 8. Оновлення вмісту ресурсу

Оновіть Markdown-вміст ресурсу `ai_doc`. Підтримується лише для ресурсів із `resource_type == ai_doc`. Поле `snippet` автоматично оновлюється з перших 2000 байтів нового вмісту.

### Кінцева точка

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

### Тіло запиту

| Параметр | Тип | Обов’язковий | Опис |
|-----------|------|----------|-------------|
| `content` | string | Так | Новий Markdown-вміст ресурсу |

### Приклад

```bash
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)

Повертає оновлений об’єкт ресурсу (та сама структура, що й елементи в List Resources).

---

## 9. Створення документного ресурсу

### Кінцева точка

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

### Тіло запиту

| Параметр | Тип | Обов’язковий | Опис |
|-----------|------|----------|-------------|
| `title` | string | Ні | Заголовок документа (за замовчуванням "New Document") |
| `content` | string | Так | Markdown-вміст документа; звичайний текст також є коректним Markdown |

Це створює ресурс `ai_doc`. Надсилайте заголовки, списки та посилання як Markdown у JSON-рядку, де символи нового рядка екрануються як `\n`. Використовуйте Markdown для форматованого вмісту документа.

### Приклад

```bash
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": "# Research Notes\n\n## Key findings\n\n- First finding\n- Second finding"
  }'
```

### Успішна відповідь (200)

Повертає створений об’єкт ресурсу.
---

## 10. Завантаження файла як документа

Завантажте файл і перетворіть його на документний ресурс (тип `ai_doc`).

### Кінцева точка

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

### Content-Type

`multipart/form-data`

### Частини запиту

| Параметр | Тип | Обов’язковий | Опис |
|-----------|------|----------|-------------|
| `file` | file | Так | Файл для завантаження |
| `title` | string | Ні | Заголовок документа |

### Приклад

```bash
curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/upload-doc' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@document.pdf' \
  -F 'title=My PDF Document'
```

### Успішна відповідь (200)

Повертає створений об’єкт ресурсу.

---

## 11. Завантаження файлового ресурсу

Завантажте файл і збережіть його в оригінальному форматі.

### Кінцева точка

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

### Content-Type

`multipart/form-data`

### Частини запиту

| Параметр | Тип | Обов’язковий | Опис |
|-----------|------|----------|-------------|
| `file` | file | Так | Файл для завантаження |

### Приклад

```bash
curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/upload' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@report.xlsx'
```

### Успішна відповідь (200)

Повертає створений об’єкт ресурсу.
---

## 12. Додавання URL-ресурсів

Додайте один або кілька URL як ресурси до LiveDoc.

### Кінцева точка

```
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 символів). Якщо пропущено, заголовок автоматично генерується зі сторінки. |

### Приклад

```bash
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)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "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 | ID створеного ресурсу |

---

## 13. Видалення ресурсу

### Кінцева точка

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

### Приклад

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

### Успішна відповідь (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "message": null,
  "data": null
}
```

---

## 14. Retrieve (семантичний пошук)

Виконайте семантичний retrieval за ресурсами в LiveDoc.

### Кінцева точка

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

### Тіло запиту

| Параметр | Тип | Обов’язковий | Опис |
|-----------|------|----------|-------------|
| `query` | string | Так | Вміст запиту для семантичного пошуку |
| `resource_ids` | string[] | Ні | Конкретні ID ресурсів, у межах яких виконувати пошук (1-50). Якщо пропущено, релевантні ресурси автоматично маршрутизуються за запитом |

### Приклад

```bash
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)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "message": null,
  "data": [
    {
      "id": "res_001",
      "title": "LLM Research Paper",
      "content": "Relevant content excerpt...",
      "score": 0.92,
      "metadata": {}
    }
  ]
}
```

### Поля результату Retrieve

| Поле | Тип | Опис |
|-------|------|-------------|
| `id` | string | ID ресурсу |
| `title` | string | Заголовок ресурсу |
| `content` | string | Зіставлений вміст |
| `score` | number | Оцінка релевантності |
| `metadata` | object | Додаткові метадані |

---

## 15. Маршрутизація ресурсів

Маршрутизуйте релевантні ресурси з LiveDoc на основі запиту. Повертає список ID ресурсів, які можна передати в кінцеву точку retrieve.

### Кінцева точка

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

### Тіло запиту

| Параметр | Тип | Обов’язковий | Опис |
|-----------|------|----------|-------------|
| `query` | string | Так | Вміст запиту для маршрутизації |
| `max_resources` | integer | Ні | Максимальна кількість ID ресурсів для повернення |

### Приклад

```bash
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)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "message": null,
  "data": ["res_001", "res_003", "res_007"]
}
```

---

## 16. Завантаження вихідного файла ресурсу

Отримайте вихідний файл ресурсу. Повертає редирект `302` на presigned URL завантаження.

Підтримується лише для ресурсів, які мають пов’язаний вихідний файл (напр., завантажені документи).

### Кінцева точка

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

### Параметри запиту

| Параметр | Тип | Обов’язковий | Опис |
|-----------|------|----------|-------------|
| `expires_in` | integer | Ні | Строк дії URL у секундах (за замовчуванням: 3600) |

### Приклад

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

### Відповідь

Повертає `302 Found` із заголовком `Location`, що вказує на presigned S3 URL завантаження. HTTP-клієнти з підтримкою редиректів (напр., `curl -L`) перейдуть за редиректом і завантажать файл безпосередньо.

---

## 17. Отримання вмісту ресурсу

Отримайте витягнутий текстовий вміст ресурсу. Підтримується для більшості типів ресурсів (document, web, video, ai_doc, ai_ppt, text, voice, mindmap тощо). Для непідтримуваних типів, як-от `image`, повертає 400.

### Кінцева точка

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

### Приклад

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

### Успішна відповідь (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "message": null,
  "data": {
    "title": "Q4 Financial Report",
    "type": "document",
    "content": "Full extracted text content of the resource..."
  }
}
```

### Поля відповіді

| Поле | Тип | Опис |
|-------|------|-------------|
| `title` | string | Заголовок ресурсу |
| `type` | string | Тип ресурсу |
| `content` | string | Вміст ресурсу; інтерпретація залежить від `type`, як описано нижче |

### Формати вмісту ресурсів

`data.content` — це рядок. Використовуйте `data.type`, щоб визначити, як його читати:

| Тип ресурсу | Формат вмісту | Кроки читання |
|---|---|---|
| `ai_doc` | Markdown | Рендеріть або зберігайте рядок як документ; сюди також належать дослідницькі звіти SuperAgent |
| `mindmap` | JSON-кодований об’єкт | Декодуйте один раз, щоб прочитати `layout` і структуру заголовків Markdown у `text` |
| `ai_ppt` | JSON-кодований об’єкт із `slides` | Декодуйте один раз, а потім декодуйте рядок `content` кожного слайда, якщо він містить JSON |
| Інші типи з текстовим вмістом | Витягнутий текст | Відображайте текст відповідно до потреб вашого застосунку |

Приклад вмісту mindmap після декодування:

```json
{
  "layout": "mindMap",
  "text": "# Topic\n## Branch\n### Leaf"
}
```

Приклад вмісту PPT після декодування:

```json
{
  "slides": [
    {
      "page": 1,
      "title": "Introduction",
      "content": "{\"coreIdea\":\"Introduce the topic\",\"slideOverview\":\"Overview of key points\",\"themeDescription\":\"Light background\"}",
      "theme": "light",
      "url": "https://example.com/slide-preview?signature=..."
    }
  ]
}
```

Поля слайда залежать від генератора й можуть бути відсутніми або містити додаткову інформацію. Розглядайте `coreIdea`, `slideOverview` і `themeDescription` як необов’язкові метадані презентації. Якщо `content` слайда є звичайним текстом, відображайте його безпосередньо.

Значення `url` у слайдах є тимчасовими підписаними посиланнями. Їхній строк дії визначається під час видачі; отримуйте новий вміст ресурсу, коли посилання закінчує дію. Для завантаження PPTX використовуйте окремий [робочий процес експорту PPT](https://openapi.felo.ai/uk/docs/api-reference/ppt-tasks.md#pptx), відповідь якого містить `expires_at`.

---

## 18. Retrieve сторінки PPT

Виконайте поглиблений retrieval вмісту на конкретній сторінці PPT-ресурсу. Витягує вміст сторінки слайда та повертає ранжовані фрагменти вмісту. Формат відповіді ідентичний кінцевій точці [Retrieve](#14-retrieve).

### Кінцева точка

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

### Тіло запиту

| Параметр | Тип | Обов’язковий | Опис |
|-----------|------|----------|-------------|
| `resource_id` | string | Так | ID PPT-ресурсу |
| `page_number` | integer | Так | Номер сторінки для retrieval (починається з 1) |
| `query` | string | Так | Вміст запиту, що описує, що саме шукати |
| `max_chunk` | integer | Ні | Максимальна кількість фрагментів для повернення (за замовчуванням: 3) |

### Приклад

```bash
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)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "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](#retrieve).

---

## Коди помилок


| Код | HTTP-статус | Опис |
|------|-------------|-------------|
| `INVALID_API_KEY` | 401 | API Key недійсний або відкликаний |
| `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 | Не вдалося виконати retrieval ресурсів |
| `LIVEDOC_RESOURCE_ADD_URLS_FAILED` | 502 | Не вдалося додати URL-ресурси |

---

## 19. Отримання README

Отримайте вміст README для LiveDoc. Повертає порожній рядок, якщо README не було задано.

### Кінцева точка

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

### Приклад

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

### Успішна відповідь (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "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).

### Кінцева точка

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

### Тіло запиту

| Параметр | Тип | Обов’язковий | Опис |
|-----------|------|----------|-------------|
| `summary` | string | Ні | Однорядковий опис проєкту (максимум 2000 символів) |
| `content` | string | Ні | Вміст README (Markdown) |

> **Примітка:** Потрібно надати принаймні одне з полів `summary` або `content`.

### Приклад

```bash
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 (та сама структура, що й у Get README).

---

## 21. Додавання до README

Додайте вміст у кінець наявного README. Якщо README не існує, створюється новий із наданим вмістом.

### Кінцева точка

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

### Тіло запиту

| Параметр | Тип | Обов’язковий | Опис |
|-----------|------|----------|-------------|
| `content` | string | Так | Вміст для додавання (Markdown) |

### Приклад

```bash
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 після додавання (та сама структура, що й у Get README).

---

## 22. Видалення README

Видаліть README для LiveDoc.

### Кінцева точка

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

### Приклад

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

### Успішна відповідь (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "message": null,
  "data": null
}
```

---

## 23. Список завдань

Отримайте пагінований список завдань у LiveDoc. Результати відсортовано за `sort` за зростанням, `status` за зростанням, `created_at` за спаданням.

### Кінцева точка

```
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 | Ні | Розмір сторінки |

### Приклад

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

### Успішна відповідь (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "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 | ID завдання (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.

### Кінцева точка

```
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 символів) |

### Приклад

```bash
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)

Повертає створений об’єкт завдання (та сама структура, що й елементи в List Tasks).

---

## 25. Оновлення завдання

Частково оновіть завдання. Оновлюються лише надані поля; пропущені поля зберігають свої поточні значення.

### Кінцева точка

```
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 символів) |

### Приклад

```bash
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)

Повертає оновлений об’єкт завдання (та сама структура, що й елементи в List Tasks).

---

## 26. Видалення завдання

М’яке видалення завдання.

### Кінцева точка

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

### Приклад

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

### Успішна відповідь (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "message": null,
  "data": null
}
```

---

## 27. Список записів завдання

Отримайте пагінований список записів для завдання (коментарі та історія змін), відсортований за `created_at` за зростанням.

### Кінцева точка

```
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 | Ні | Розмір сторінки |

### Приклад

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

### Успішна відповідь (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "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 | ID запису |
| `record_type` | string | Тип запису: `comment` / `edit` / `status_change` |
| `content` | string | Текст коментаря (лише для типу `comment`) |
| `meta` | object | Деталі змін (для типів `edit` і `status_change`) |
| `task_id` | string | ID батьківського завдання |
| `operated_by` | string | Підпис оператора, напр. `claude-code`, `openclaw` |
| `created_at` | string | Часова мітка створення (ISO 8601) |
| `modified_at` | string | Часова мітка останньої зміни (ISO 8601) |

---

## 28. Додавання коментаря до завдання

Додайте коментар до завдання.

### Кінцева точка

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

### Тіло запиту

| Параметр | Тип | Обов’язковий | Опис |
|-----------|------|----------|-------------|
| `content` | string | Так | Вміст коментаря |
| `operated_by` | string | Ні | Підпис оператора, напр. `claude-code`, `openclaw` (максимум 100 символів) |

### Приклад

```bash
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)

Повертає створений об’єкт запису (та сама структура, що й елементи в List Task Records).

---

## Коди помилок (оновлено)

| Код | HTTP-статус | Опис |
|------|-------------|-------------|
| `INVALID_API_KEY` | 401 | API Key недійсний або відкликаний |
| `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 | Не вдалося виконати retrieval ресурсів |
| `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 | Не вдалося створити коментар до завдання |
