```yaml
---
sitemap:
  changefreq: yearly
  priority: 0.5
type: docs
group: Интеграции
g_num: 6
o_num: 1
title: "REST API справка – Програмен документ за разработчици на Procurize.AI"
description: Пълна справка за REST API на Procurize.AI. Научете как да достъпвате програмен начин документи, въпросници, RAG и отчети, използвайки API токени. Включва удостоверяване, крайни точки и примери.
breadcrumb: REST API справка
index_title: "REST API справка"
brief: Пълна справка за REST API на Procurize.AI. Програмен достъп до документи, въпросници, RAG, файлове и отчети чрез вашия API токен. Включва удостоверяване, всички поддържани модули и примери за заявки/отговори.
---
```

# Procurize.AI REST API справка

**Програмен достъп до вашата база от знания – документи, въпросници, RAG и отчети – чрез вашия API токен.**

> **Отнася се за:** Procurize.AI API v1  
> **Удостоверяване:** API ключ чрез заглавката `X-API-Key` (вижте [API Tokens](/api-tokens/) за управление на токени)  
> **Базов URL:** `https://api.procurize.com`

## Преглед

REST API‑то на Procurize.AI предоставя програмен достъп до ключови функции на платформата. То ви позволява да интегрирате Procurize.AI с вашите вътрешни системи, да автоматизирате управлението на базата от знания и да създавате персонализирани работни потоци.

**Поддържани модули (с токен‑удостоверяване):**

- [**RagArticle**](#ragarticle) – управление на документи  
- [**RagFaq**](#ragfaq) – управление на FAQ записи  
- [**RagQuery**](#ragquery) – изпълнение на RAG заявки  

## Удостоверяване

Всички удостоверени крайни точки изискват API токен, предаден в заглавката на заявката.

| Заглавка | Стойност |
|----------|----------|
| `X-API-Key` | `<YOUR_API_TOKEN>` |

**Пример:**
```bash
curl -X GET "https://api.procurize.com/v1/..." \
  -H "X-API-Key: your-api-token-here"
```

> 💡 Токените са свързани с вашата организация – не е необходимо да посочвате ID на организация в заявката.

## Базов URL

Всички REST API крайни точки се обслужват под:
```
https://api.procurize.com
```

## Обработка на грешки

API‑то използва стандартни HTTP статус кодове.

| Код | Значение |
|-----|----------|
| `200 OK` | Заявката е успешна |
| `201 Created` | Ресурсът е създаден успешно |
| `204 No Content` | Заявката е успешна, без тяло на отговора |
| `400 Bad Request` | Невалидни параметри или неправилно форматирана заявка |
| `401 Unauthorized` | Липсващ или невалиден API токен |
| `403 Forbidden` | Токенът няма права за това действие |
| `404 Not Found` | Ресурсът не съществува |
| `500 Internal Server Error` | Неочаквана грешка в сървъра |

Отговорите при грешка включват машинно‑четим код за грешка и човешко‑четимо съобщение.

## Препратка към модули

### RagArticle

#### GET /questionnaire/rag/articles/summary

**Обобщение:** Обобщение за началната страница  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| proj | query | string (uuid) | Не | ID на проекта. |

**Отговор (200):**
```json
{
  "active": 5
}
```

---

#### GET /questionnaire/rag/articles/total

**Обобщение:** Брой статии  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| q | query | string | Не | Филтър по име или код на статия. |
| state | query | array | Не | Филтър по състояния. |
| project | query | array | Не | Филтър по проекти. |
| type | query | array | Не | Филтър по типове документи. |

**Отговор (200):**
```json
42
```

---

#### GET /questionnaire/rag/articles/list

**Обобщение:** Получете списък със статии  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| q | query | string | Не | Филтър по име или код на статия. |
| state | query | array | Не | Филтър по състояния. |
| project | query | array | Не | Филтър по проекти. |
| type | query | array | Не | Филтър по типове документи. |
| s | query | string | Не | Поле за сортиране. |
| asc | query | boolean | Не | Възходящо сортиране. |
| ps | query | integer (int32) | Не | Размер на страница. |
| p | query | integer (int32) | Не | Номерация на страници, започваща от 1. |

**Отговор (200):**
```json
{
  "paging": {
    "pageNumber": 1,
    "pageSize": 10,
    "total": 42,
    "totalPages": 5
  },
  "items": [
    {
      "code": "ART-001",
      "org": "00000000-0000-0000-0000-000000000000",
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Заглавие на статията",
      "description": "Описание на статията",
      "documentTypes": [
        {
          "id": "00000000-0000-0000-0000-000000000000",
          "name": "Име на тип",
          "plural": "Имена на типове",
          "count": 5
        }
      ],
      "size": 150,
      "revision": {
        "id": "00000000-0000-0000-0000-000000000000",
        "collectionId": "00000000-0000-0000-0000-000000000000",
        "rev": 3,
        "date": "2025-01-15T10:30:00Z",
        "author": {
          "id": "user123",
          "name": "John Doe",
          "email": "john.doe@example.com",
          "login": "johndoe",
          "ra": true
        },
        "authorName": "John Doe",
        "analysisSummary": {
          "id": "00000000-0000-0000-0000-000000000000",
          "initiator": {
            "id": "user123",
            "name": "John Doe",
            "email": "john.doe@example.com",
            "login": "johndoe",
            "ra": true
          },
          "created": "2025-01-15T10:30:00Z",
          "state": "Completed",
          "stateDate": "2025-01-15T10:35:00Z",
          "stateDetails": "Анализът завърши успешно",
          "operationId": "op-12345"
        }
      },
      "type": "Article",
      "state": "Active",
      "projects": [
        "00000000-0000-0000-0000-000000000000"
      ],
      "items": [
        "00000000-0000-0000-0000-000000000000"
      ],
      "isShared": false
    }
  ]
}
```

---

#### POST /questionnaire/rag/file-to-md

**Обобщение:** Връща Markdown съдържание от файл  

**Тяло на заявката (multipart/form-data):**
```json
{
  "url": "https://example.com/file.pdf",
  "file": "binary"
}
```

**Отговор (200):**
```json
"Markdown съдържание от файл"
```

---

#### POST /questionnaire/rag/article/create

**Обобщение:** Създаване на статия  

**Тяло на заявката (multipart/form-data):**
```json
{
  "code": "ART-001",
  "name": "Заглавие на статията",
  "description": "Описание на статията",
  "content": "# Съдържание на статията\n\nТова е съдържанието на статията.",
  "url": "https://example.com/file.pdf",
  "file": "binary"
}
```

**Отговор (200):**
```json
{
  "code": "ART-001",
  "org": "00000000-0000-0000-0000-000000000000",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "Заглавие на статията",
  "description": "Описание на статията",
  "documentTypes": null,
  "size": 150,
  "revision": null,
  "type": "Article",
  "state": "Active",
  "projects": null,
  "items": null,
  "isShared": false
}
```

---

#### GET /questionnaire/rag/article/check

**Обобщение:** Проверка за съществуване на статия.  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| code | query | string | Да | Код на статията. |

**Отговор (200):**
```json
true
```

---

#### GET /questionnaire/rag/article-info

**Обобщение:** Получаване на информация за статия по код.  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| code | query | string | Да | Код на статията. |

**Отговор (200):**
```json
{
  "code": "ART-001",
  "org": "00000000-0000-0000-0000-000000000000",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "Заглавие на статията",
  "description": "Описание на статията",
  "documentTypes": null,
  "size": 150,
  "revision": null,
  "type": "Article",
  "state": "Active",
  "projects": null,
  "items": null,
  "isShared": false
}
```

---

#### GET /questionnaire/rag/article

**Обобщение:** Получаване на съдържанието на статия по код  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| code | query | string | Да | Код на статията. |
| format | query | string | Не | Ако е `true`, връща HTML съдържание в тялото на отговора. В противен случай връща съдържанието в Markdown формат. |
| split | query | boolean | Не | Ако е `true`, връща съдържанието, разделено по RAG елементи. |
| css | query | boolean | Не | Ако е `true`, връща HTML/PDF съдържание с CSS. |

**Отговор (200):**
```json
"# Заглавие на статията\n\nТова е съдържанието на статията в Markdown формат."
```

#### POST /questionnaire/rag/article

**Обобщение:** Актуализиране на метаданни на статия  

**Тяло на заявката:**
```json
{
  "code": "ART-001",
  "name": "Актуализирано заглавие на статията",
  "description": "Актуализирано описание",
  "projects": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "documentTypes": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Име на тип",
      "plural": "Имена на типове"
    }
  ],
  "isShared": true,
  "state": "Active"
}
```

**Отговор (200):**
```json
{}
```

#### DELETE /questionnaire/rag/article

**Обобщение:** Изтриване на статия  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| code | query | string | Да | Код на статията. |

---

#### GET /questionnaire/rag/article/pdf

**Обобщение:** Получаване на статия като PDF по код  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| code | query | string | Да | Код на статията. |

**Отговор (200):**
```json
(pdf binary)
```

---

#### GET /questionnaire/rag/article/content

**Обобщение:** Получаване на съдържанието на статия  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| code | query | string | Да | Код на статията. |

**Отговор (200):**
```json
{
  "content": "# Заглавие на статията\n\nТук е съдържанието."
}
```

---

#### POST /questionnaire/rag/article/content

**Обобщение:** Актуализиране на съдържанието на статия  

**Тяло на заявката (multipart/form-data):**
```json
{
  "code": "ART-001",
  "content": "# Актуализирано съдържание",
  "file": "binary"
}
```

---

#### POST /questionnaire/rag/plural

**Обобщение:** Получаване на множествена форма на съществително  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| noun | query | string | Не | Съществително за множествено число. |

**Отговор (200):**
```json
{
  "plural": "Articles"
}
```

---

#### POST /questionnaire/rag/article/find-types

**Обобщение:** Анализиране на статия с AI и връщане на типове  

**Тяло на заявката (multipart/form-data):**
```json
{
  "code": "ART-001",
  "content": "# Съдържание на статията"
}
```

**Отговор (200):**
```json
[
  {
    "plural": "Types"
  }
]
```

---

#### POST /questionnaire/rag/article/format-with-ai

**Обобщение:** Форматиране на съдържанието на статия с AI  

**Тяло на заявката (multipart/form-data):**
```json
{
  "code": "ART-001",
  "content": "# Съдържание на статията"
}
```

**Отговор (200):**
```json
{
  "formattedContent": "# Форматирано съдържание на статията"
}
```

---

#### POST /questionnaire/rag/article/improve-on-suggestions

**Обобщение:** Подобряване на документа въз основа на предложения  

**Тяло на заявката (multipart/form-data):**
```json
{
  "suggestions": [
    {
      "sectionTitle": "Въведение",
      "suggestion": "Добавете повече детайли тук."
    }
  ],
  "code": "ART-001",
  "content": "# Съдържание на статията"
}
```

**Отговор (200):**
```json
{
  "improvedContent": "# Подобрено съдържание"
}
```

---

#### GET /questionnaire/rag/article/parts

**Обобщение:** Връща списък с части на статия  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| id | query | array | Да | Списък с части на статията. |

**Отговор (200):**
```json
[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "code": "part-1",
    "title": "Въведение",
    "orderNumber": 1,
    "content": "Съдържание на въведението."
  }
]
```

---

#### GET /questionnaire/rag/article/revisions

**Обобщение:** Връща списък с ревизии на статия  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| code | query | string | Да | Код на статията. |

**Отговор (200):**
```json
[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "collectionId": "00000000-0000-0000-0000-000000000000",
    "rev": 1,
    "date": "2025-01-15T10:30:00Z",
    "author": {
      "id": "user123",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "login": "johndoe",
      "ra": true
    },
    "authorName": "John Doe",
    "analysisSummary": {
      "id": "00000000-0000-0000-0000-000000000000",
      "initiator": {
        "id": "user123",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "login": "johndoe",
        "ra": true
      },
      "created": "2025-01-15T10:30:00Z",
      "state": "Completed",
      "stateDate": "2025-01-15T10:35:00Z",
      "stateDetails": "Анализът завърши",
      "operationId": "op-12345"
    }
  }
]
```

---

#### GET /questionnaire/rag/article/revisions/info/{id}

**Обобщение:** Получаване на информация за ревизия на статия  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| id | path | string (uuid) | Да | ID на ревизията. |

**Отговор (200):**
```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "collectionId": "00000000-0000-0000-0000-000000000000",
  "rev": 1,
  "date": "2025-01-15T10:30:00Z",
  "author": {
    "id": "user123",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "login": "johndoe",
    "ra": true
  },
  "authorName": "John Doe",
  "analysisSummary": {
    "id": "00000000-0000-0000-0000-000000000000",
    "initiator": {
      "id": "user123",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "login": "johndoe",
      "ra": true
    },
    "created": "2025-01-15T10:30:00Z",
    "state": "Completed",
    "stateDate": "2025-01-15T10:35:00Z",
    "stateDetails": "Анализът завърши",
    "operationId": "op-12345"
  }
}
```

---

#### GET /questionnaire/rag/article/revisions/{id}

**Обобщение:** Получаване на съдържанието на ревизия на статия  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| id | path | string (uuid) | Да | ID на ревизията. |

**Отговор (200):**
```json
"# Съдържание на ревизията на статията\n\nПредишна версия."
```

---

#### GET /questionnaire/rag/article/analyze

**Обобщение:** Анализиране на съдържанието на статия с AI  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| code | query | string | Да | Код на статията. |
| rev | query | integer (int32) | Не | Номер на ревизия. |
| force | query | boolean | Не | Принудително създаване на нов анализ и изтриване на предишен незавършен резултат, ако съществува. |

**Отговор (200):**
```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "initiator": {
    "id": "user123",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "login": "johndoe",
    "ra": true
  },
  "created": "2025-01-15T10:30:00Z",
  "state": "Completed",
  "stateDate": "2025-01-15T10:35:00Z",
  "stateDetails": "Анализът завърши",
  "operationId": "op-12345"
}
```

---

#### GET /questionnaire/rag/article/analyze/{id}

**Обобщение:** Получаване на резултат от анализ на статия  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| id | path | string (uuid) | Да | ID на анализа. |

**Отговор (200):**
```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "initiator": {
    "id": "user123",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "login": "johndoe",
    "ra": true
  },
  "created": "2025-01-15T10:30:00Z",
  "state": "Completed",
  "stateDate": "2025-01-15T10:35:00Z",
  "stateDetails": "Анализът завърши",
  "operationId": "op-12345",
  "fragments": [
    "fragment-1",
    "fragment-2"
  ],
  "ownInconcies": "Открити са собствени несъответствия",
  "ragInconcies": "Открити са RAG несъответствия",
  "proposals": "Предложения за подобрение"
}
```

---

#### GET /questionnaire/rag/messages/list

**Обобщение:** Списък с всички съобщения  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| id | query | string (uuid) | Да | ID на RAG колекцията. |
| item | query | string (uuid) | Не | ID на RAG елемент. |
| message | query | string (uuid) | Не | ID на съобщението. |
| asc | query | boolean | Не | Възходящо сортиране. |
| ps | query | integer (int32) | Не | Размер на страница. |
| p | query | integer (int32) | Не | Номерация на страници, започваща от 1. |

**Отговор (200):**
```json
{
  "paging": {
    "pageNumber": 1,
    "pageSize": 10,
    "total": 5,
    "totalPages": 1
  },
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "replyTo": null,
      "questionnaire": null,
      "section": null,
      "question": null,
      "ragCollection": "00000000-0000-0000-0000-000000000000",
      "ragItem": "00000000-0000-0000-0000-000000000000",
      "targetId": "00000000-0000-0000-0000-000000000000",
      "targetType": "Question",
      "targetNum": 1,
      "author": {
        "id": "user123",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "login": "johndoe",
        "ra": true
      },
      "text": "Съдържание на съобщението",
      "created": "2025-01-15T10:30:00Z",
      "updated": "2025-01-15T10:30:00Z",
      "replies": 0
    }
  ]
}
```

---

#### POST /questionnaire/rag/messages/add

**Обобщение:** Добавяне на ново съобщение  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| id | query | string (uuid) | Да | ID на RAG колекцията. |
| item | query | string (uuid) | Не | ID на RAG елемент. |
| message | query | string (uuid) | Не | ID на съобщението, към което се отговаря. |

**Тяло на заявката:**
```json
{
  "text": "Съдържание на новото съобщение"
}
```

**Отговор (200):**
```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "replyTo": null,
  "questionnaire": null,
  "section": null,
  "question": null,
  "ragCollection": "00000000-0000-0000-0000-000000000000",
  "ragItem": "00000000-0000-0000-0000-000000000000",
  "targetId": "00000000-0000-0000-0000-000000000000",
  "targetType": "Question",
  "targetNum": 1,
  "author": {
    "id": "user123",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "login": "johndoe",
    "ra": true
  },
  "text": "Съдържание на новото съобщение",
  "created": "2025-01-15T10:30:00Z",
  "updated": "2025-01-15T10:30:00Z",
  "replies": 0
}
```

---

#### POST /questionnaire/rag/message

**Обобщение:** Актуализиране на съществуващо съобщение  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| c | query | string (uuid) | Да | ID на RAG колекцията. |
| id | query | string (uuid) | Да | ID на съобщението. |

**Тяло на заявката:**
```json
{
  "text": "Актуализирано съдържание на съобщението"
}
```

**Отговор (200):**
```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "replyTo": null,
  "questionnaire": null,
  "section": null,
  "question": null,
  "ragCollection": "00000000-0000-0000-0000-000000000000",
  "ragItem": "00000000-0000-0000-0000-000000000000",
  "targetId": "00000000-0000-0000-0000-000000000000",
  "targetType": "Question",
  "targetNum": 1,
  "author": {
    "id": "user123",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "login": "johndoe",
    "ra": true
  },
  "text": "Актуализирано съдържание на съобщението",
  "created": "2025-01-15T10:30:00Z",
  "updated": "2025-01-15T10:45:00Z",
  "replies": 0
}
```

#### DELETE /questionnaire/rag/message

**Обобщение:** Изтриване на съществуващо съобщение  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| id | query | string (uuid) | Да | ID на съобщението. |

**Отговор (200):**
```json
{}
```

---

### RagFaq

#### GET /questionnaire/rag/faq-collections/summary

**Обобщение:** Обобщение за началната страница  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| proj | query | string (uuid) | Не | ID на проекта. |

**Отговор (200):**
```json
{
  "active": 3
}
```

---

#### GET /questionnaire/rag/faq-collections/total

**Обобщение:** Брой FAQ колекции.  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| q | query | string | Не | Филтър по име или код на колекция. |
| state | query | array | Не | Филтър по състояния. |
| project | query | array | Не | Филтър по проекти. |

**Отговор (200):**
```json
3
```

---

#### GET /questionnaire/rag/faq-collections/list

**Обобщение:** Получете списък с FAQ колекции.  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| q | query | string | Не | Филтър по име или код на колекция. |
| state | query | array | Не | Филтър по състояния. |
| project | query | array | Не | Филтър по проекти. |
| s | query | string | Не | Поле за сортиране. |
| asc | query | boolean | Не | Възходящо сортиране. |
| ps | query | integer (int32) | Не | Размер на страница. |
| p | query | integer (int32) | Не | Номерация на страници, започваща от 1. |

**Отговор (200):**
```json
{
  "paging": {
    "pageNumber": 1,
    "pageSize": 10,
    "total": 3,
    "totalPages": 1
  },
  "items": [
    {
      "code": "FAQ-001",
      "org": "00000000-0000-0000-0000-000000000000",
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "FAQ Колекция",
      "description": "Описание на FAQ колекцията",
      "documentTypes": null,
      "size": 5,
      "revision": null,
      "type": "Faq",
      "state": "Active",
      "projects": null,
      "items": null,
      "isShared": false
    }
  ]
}
```

---

#### GET /questionnaire/rag/faq-collections/find-items

**Обобщение:** Търсене на FAQ елементи.  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| q | query | string | Да | Филтър по въпрос. |
| project | query | string (uuid) | Не | Филтър по проект. |
| ps | query | integer (int32) | Не | Размер на страница. |
| p | query | integer (int32) | Не | Номерация на страници, започваща от 1. |

**Отговор (200):**
```json
{
  "paging": {
    "pageNumber": 1,
    "pageSize": 10,
    "total": 5,
    "totalPages": 1
  },
  "items": [
    {
      "index": 0,
      "question": "Какъв е този продукт?",
      "answer": "Това е страхотен продукт.",
      "comment": "FAQ за продукта",
      "state": "Active"
    }
  ]
}
```

---

#### POST /questionnaire/rag/faq-collection/create

**Обобщение:** Създаване на нова FAQ колекция.  

**Тяло на заявката (multipart/form-data):**
```json
{
  "code": "FAQ-001",
  "name": "FAQ Колекция",
  "description": "Описание на FAQ колекцията",
  "content": "Тук е съдържанието",
  "file": "binary"
}
```

**Отговор (200):**
```json
{
  "code": "FAQ-001",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "FAQ Колекция",
  "description": "Описание на FAQ колекцията",
  "documentTypes": null,
  "size": 5,
  "revision": null,
  "type": "Faq",
  "state": "Active",
  "projects": null,
  "items": null,
  "isShared": false
}
```

---

#### POST /questionnaire/rag/faq-collection

**Обобщение:** Актуализиране на метаданни на FAQ колекция.  

**Тяло на заявката:**
```json
{
  "code": "FAQ-001",
  "name": "Актуализирана FAQ Колекция",
  "description": "Актуализирано описание",
  "projects": null,
  "documentTypes": null,
  "isShared": false,
  "state": "Active"
}
```

#### DELETE /questionnaire/rag/faq-collection

**Обобщение:** Изтриване на FAQ колекция.  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| code | query | string | Да | Код на колекцията. |

#### GET /questionnaire/rag/faq-collection

**Обобщение:** Получаване на FAQ колекция.  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| code | query | string | Да | Код на колекцията. |

**Отговор (200):**
```json
{
  "code": "FAQ-001",
  "org": "00000000-0000-0000-0000-000000000000",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "FAQ Колекция",
  "description": "Описание на FAQ колекцията",
  "documentTypes": null,
  "size": 5,
  "revision": null,
  "type": "Faq",
  "state": "Active",
  "projects": null,
  "items": null,
  "isShared": false
}
```

---

#### GET /questionnaire/rag/faq-collection/check

**Обобщение:** Проверка за съществуване на FAQ колекция.  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| code | query | string | Да | Код на колекцията. |

**Отговор (200):**
```json
true
```

---

#### GET /questionnaire/rag/faq-collection/items-total

**Обобщение:** Брой FAQ елементи.  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| code | query | string | Да | Код на колекцията. |
| q | query | string | Не | Филтър по съдържание на FAQ елемент. |

**Тяло на заявката:**
```json
["Active", "Default"]
```

**Отговор (200):**
```json
5
```

---

#### GET /questionnaire/rag/faq-collection/items

**Обобщение:** Получаване на списък с FAQ елементи.  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| code | query | string | Да | Код на колекцията. |
| q | query | string | Не | Филтър по съдържание на FAQ елемент. |
| state | query | array | Не | Филтър по състояния. |
| s | query | string | Не | Поле за сортиране. |
| asc | query | boolean | Не | Възходящо сортиране. |
| ps | query | integer (int32) | Не | Размер на страница. |
| p | query | integer (int32) | Не | Номерация на страници, започваща от 1. |

**Отговор (200):**
```json
{
  "paging": {
    "pageNumber": 1,
    "pageSize": 10,
    "total": 5,
    "totalPages": 1
  },
  "items": [
    {
      "index": 0,
      "question": "Какъв е този продукт?",
      "answer": "Това е страхотен продукт.",
      "comment": "FAQ за продукта",
      "state": "Active"
    }
  ]
}
```

---

#### POST /questionnaire/rag/faq-collection/item/create

**Обобщение:** Създаване на нов FAQ елемент.  

**Тяло на заявката:**
```json
{
  "code": "FAQ-001",
  "index": 0,
  "question": "Какъв е този продукт?",
  "answer": "Това е страхотен продукт.",
  "comment": "FAQ за продукта",
  "state": "Active"
}
```

**Отговор (200):**
```json
{
  "index": 0,
  "question": "Какъв е този продукт?",
  "answer": "Това е страхотен продукт.",
  "comment": "FAQ за продукта",
  "state": "Active"
}
```

---

#### GET /questionnaire/rag/faq-collection/item

**Обобщение:** Получаване на FAQ елемент.  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| code | query | string | Да | Код на колекцията. |
| index | query | integer (int32) | Да | Нулево‑базов индекс на елемента в колекцията. |

**Отговор (200):**
```json
{
  "index": 0,
  "question": "Какъв е този продукт?",
  "answer": "Това е страхотен продукт.",
  "comment": "FAQ за продукта",
  "state": "Active"
}
```

#### POST /questionnaire/rag/faq-collection/item

**Обобщение:** Актуализиране на FAQ елемент.  

**Тяло на заявката:**
```json
{
  "code": "FAQ-001",
  "index": 0,
  "newIndex": 1,
  "question": "Актуализиран въпрос?",
  "answer": "Актуализиран отговор.",
  "comment": "Актуализиран коментар",
  "state": "Active"
}
```

#### DELETE /questionnaire/rag/faq-collection/item

**Обобщение:** Изтриване на FAQ елемент.  

**Параметри:**
| Име | В | Тип | Задължително | Описание |
|-----|---|-----|--------------|----------|
| code | query | string | Да | Код на колекцията. |
| index | query | integer (int32) | Да | Нулево‑базов индекс на елемента в колекцията. |

---

### RagQuery

#### POST /questionnaire/rag/query

**Обобщение:** Изпълнение на заявка в RAG Knowledge Base  

**Тяло на заявката:**
```json
{
  "project": "00000000-0000-0000-0000-000000000000",
  "excludeCollections": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "question": "Какъв е този продукт?",
  "yourCompanyName": "Acme Corp",
  "yourCompanyAlias": "Acme",
  "customerName": "John Doe",
  "options": [
    "option1",
    "option2"
  ],
  "multiselect": false,
  "nArticles": 5,
  "nFaqs": 3,
  "threshold": 0.5,
  "debug": false,
  "withJustification": true,
  "withConfidenceLevel": true,
  "withFragments": true,
  "nAttempts": 3
}
```

**Отговор (200):**
```json
{
  "attempt": 1,
  "preparedQuery": {
    "original": "Какъв е този продукт?",
    "enhanced": "Какъв е този продукт и какви са неговите характеристики?"
  },
  "ragItems": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "distance": 0.25
    }
  ],
  "question": "Какъв е този продукт?",
  "generalInstructions": "Въз основа на базата от знания, ето отговорът:",
  "text": "Този продукт е отличното решение за вашите нужди.",
  "explanation": "Отговорът беше намерен в множество източници с висока увереност."
}
```

---

#### POST /questionnaire/rag/query-stream

**Обобщение:** Изпълнение на заявка в RAG Knowledge Base (стрийм)  

**Тяло на заявката:** (същото като предишното)

**Отговор (200):**
```json
[
  {
    "text": "Този продукт е отличното решение",
    "fragments": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "part": 1,
        "distance": 0.25,
        "type": "Article",
        "code": "ART-001",
        "title": "Заглавие на продукта",
        "fragment": "Фрагмент от съдържанието на продукта"
      }
    ]
  },
  {
    "text": " за вашите нужди.",
    "fragments": []
  }
]
```

---

#### POST /questionnaire/rag/query-fragments

**Обобщение:** Изпълнение на заявка в RAG Knowledge Base (фрагменти)  

**Тяло на заявката:**
```json
{
  "project": "00000000-0000-0000-0000-000000000000",
  "exclude_documents": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "query": "Какъв е този продукт?",
  "top_k": 5,
  "similarity_threshold": 0.5,
  "prepare_query": true
}
```

**Отговор (200):**
```json
{
  "results": [
    {
      "document_id": "00000000-0000-0000-0000-000000000000",
      "document_code": "ART-001",
      "document_title": "Заглавие на продукта",
      "revision": 3,
      "chunk_index": 0,
      "content": "Фрагмент от съдържанието на продукта",
      "metadata": {
        "author": "John Doe",
        "created_at": "2025-01-15T10:30:00Z",
        "last_updated_at": "2025-01-15T10:35:00Z",
        "doc_categories": [
          "Product",
          "Information"
        ]
      },
      "similarity_score": 0.85
    }
  ]
}
```

## Свързани статии

- [API Tokens – Генериране & Управление](/api-tokens/) – как да създавате и управлявате токени  
- [Питайте AI с вашата база от знания](/ask-ai-with-your-knowledge-base/) – използване на RAG заявки