Справочник API: инфраструктура и источники данных
Регистрация и управление векторными хранилищами, файловыми хранилищами, службами веб-поиска и источниками данных; предусмотрены проверка подключения и операции синхронизации.
Общие правила: чтение — Viewer+, запись/проверка подключения — Admin+ (проверка учётных данных обращается к внешним системам). Возможности API key: векторные хранилища — manage_vector_stores, бэкенды хранилищ — manage_storage_backends, веб-поиск — manage_web_search, источники данных — manage_datasources (любой из них можно заменить на full-access).
Векторные хранилища (/api/v1/vector-stores)
GET /api/v1/vector-stores/types
Назначение: доступные типы движков и схема конфигурации. Права: Viewer+.
Ответ: 200 {"success":true,"data":[определение типа]}
curl $BASE/api/v1/vector-stores/types -H "Authorization: Bearer $TOKEN"POST /api/v1/vector-stores/test
Назначение: проверка подключения с использованием исходной конфигурации (без сохранения в БД). Права: Admin+.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
engine_type | string | да (binding:"required") | тип движка |
connection_config | object | да (binding:"required") | конфигурация подключения |
Ответ: 200 {"success":true|false,"version":"...","error":"..."}
curl -X POST $BASE/api/v1/vector-stores/test -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"engine_type":"qdrant","connection_config":{"addr":"qdrant:6334"}}'POST /api/v1/vector-stores
Назначение: создание конфигурации векторного хранилища. Права: Admin+. Поля: name (обязательно), engine_type (обязательно), connection_config (обязательно), index_config (необязательно).
Ответ: 201 {"success":true,"data":{VectorStoreResponse}} (id,tenant_id,name,engine_type,connection_config,index_config,...)
curl -X POST $BASE/api/v1/vector-stores -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"qdrant-main","engine_type":"qdrant","connection_config":{"addr":"qdrant:6334"}}'GET /api/v1/vector-stores
Назначение: список векторных хранилищ (хранилища __env_*, внедрённые через переменные окружения, идут первыми). Права: Viewer+.
Ответ: 200 {"success":true,"data":[VectorStoreResponse]}
curl $BASE/api/v1/vector-stores -H "Authorization: Bearer $TOKEN"GET /api/v1/vector-stores/:id
Назначение: подробности векторного хранилища (поддерживаются ID __env_*). Права: Viewer+.
Ответ: 200 {"success":true,"data":{VectorStoreResponse}}
curl $BASE/api/v1/vector-stores/vs-1 -H "Authorization: Bearer $TOKEN"PUT /api/v1/vector-stores/:id
Назначение: обновление (только переименование; env store изменить нельзя). Права: Admin+. Тело запроса: {"name":"..."} (binding:"required").
Ответ: 200 {"success":true,"data":{VectorStoreResponse}}
curl -X PUT $BASE/api/v1/vector-stores/vs-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"qdrant-prod"}'DELETE /api/v1/vector-stores/:id
Назначение: удаление (env store удалить нельзя). Права: Admin+.
Ответ: 200 {"success":true}
curl -X DELETE $BASE/api/v1/vector-stores/vs-1 -H "Authorization: Bearer $TOKEN"POST /api/v1/vector-stores/:id/test
Назначение: проверка сохранённого/env векторного хранилища. Права: Admin+.
Ответ: 200 {"success":true|false,"version","error"}
curl -X POST $BASE/api/v1/vector-stores/vs-1/test -H "Authorization: Bearer $TOKEN"Бэкенды хранилищ (/api/v1/storage-backends)
Тело запроса (Create/Update/TestRaw используют общий storageBackendRequest):
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да (binding:"required") | имя |
provider | string | да (binding:"required") | провайдер: local/minio/cos/tos/s3/oss/ks3/obs, ограничивается STORAGE_ALLOW_LIST |
config | object | нет | конфигурация провайдера, поля см. в Бэкенды хранилищ (в ответе учётные данные маскируются) |
status | string | нет | active (по умолчанию)/disabled |
GET /api/v1/storage-backends/types
Назначение: список имён провайдеров, разрешённых STORAGE_ALLOW_LIST (если не задан — возвращаются все). Права: Viewer+. Ответ: 200 {"success":true,"data":["local","minio",...]}
curl $BASE/api/v1/storage-backends/types -H "Authorization: Bearer $TOKEN"POST /api/v1/storage-backends/test
Назначение: проверка подключения с исходной конфигурацией. Права: Admin+. Ответ: 200 {"success":bool,"error"}
curl -X POST $BASE/api/v1/storage-backends/test -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"t","provider":"minio","config":{"endpoint":"minio:9000"}}'POST /api/v1/storage-backends
Назначение: создание бэкенда хранилища. Права: Admin+. Ответ: 201 {"success":true,"data":{StorageBackend}}
curl -X POST $BASE/api/v1/storage-backends -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"minio-main","provider":"minio","config":{"endpoint":"minio:9000"}}'GET /api/v1/storage-backends
Назначение: список (включает default_storage_backend_id). Права: Viewer+. Ответ: 200 {"success":true,"data":[...],"default_storage_backend_id":"..."}
curl $BASE/api/v1/storage-backends -H "Authorization: Bearer $TOKEN"GET /api/v1/storage-backends/:id
Назначение: подробности (учётные данные маскируются). Права: Viewer+. Ответ: 200 {"success":true,"data":{StorageBackend}}
curl $BASE/api/v1/storage-backends/sb-1 -H "Authorization: Bearer $TOKEN"PUT /api/v1/storage-backends/:id
Назначение: обновление. Права: Admin+. Ответ: 200 {"success":true,"data":{StorageBackend}}
curl -X PUT $BASE/api/v1/storage-backends/sb-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"minio-prod","provider":"minio"}'DELETE /api/v1/storage-backends/:id
Назначение: удаление. Права: Admin+. Ответ: 200 {"success":true}
curl -X DELETE $BASE/api/v1/storage-backends/sb-1 -H "Authorization: Bearer $TOKEN"POST /api/v1/storage-backends/:id/test
Назначение: проверка сохранённого бэкенда. Права: Admin+. Ответ: 200 {"success":bool,"error"}
curl -X POST $BASE/api/v1/storage-backends/sb-1/test -H "Authorization: Bearer $TOKEN"PUT /api/v1/storage-backends/:id/default
Назначение: назначение бэкенда по умолчанию. Права: Admin+. Ответ: 200 {"success":true}
curl -X PUT $BASE/api/v1/storage-backends/sb-1/default -H "Authorization: Bearer $TOKEN"Веб-поиск (/api/v1/web-search и /api/v1/web-search-providers)
Сейчас зарегистрировано 14 поставщиков поиска, включая Metaso, Exa, Bocha, Brave, Serply. Параметры api_key и extra_config для каждого см. в Веб-поиск.
GET /api/v1/web-search/providers
Назначение: каталог встроенных поставщиков поиска (только чтение). Права: Viewer+, только JWT (политика API key не объявлена). Handler: internal/handler/web_search.go
Ответ: 200 {"success":true,"data":[...]}
curl $BASE/api/v1/web-search/providers -H "Authorization: Bearer $TOKEN"GET /api/v1/web-search-providers/types
Назначение: типы поставщиков и схема параметров. Права: Viewer+. Handler: internal/handler/web_search_provider.go
Ответ: 200 {"success":true,"data":[...]}
curl $BASE/api/v1/web-search-providers/types -H "Authorization: Bearer $TOKEN"POST /api/v1/web-search-providers/test
Назначение: проверка исходных учётных данных (без сохранения в БД). Права: Admin+. Тело запроса: provider (binding:"required"), parameters (необязательно).
Ответ: 200 {"success":bool,"error"}
curl -X POST $BASE/api/v1/web-search-providers/test -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"provider":"tavily","parameters":{"api_key":"tvly-..."}}'POST /api/v1/web-search-providers
Назначение: создание конфигурации поставщика. Права: Admin+.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да (binding:"required") | имя |
provider | string | да (binding:"required") | тип (bing/tavily/google…) |
description | string | нет | описание |
parameters | object | нет | параметры (api_key рекомендуется передавать через подресурс credentials) |
is_default | bool | нет | поставщик по умолчанию |
Ответ: 201 {"success":true,"data":{WebSearchProviderResponse}}
curl -X POST $BASE/api/v1/web-search-providers -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"tavily-main","provider":"tavily"}'GET /api/v1/web-search-providers
Назначение: список поставщиков. Права: Viewer+. Ответ: 200 {"success":true,"data":[...]}
curl $BASE/api/v1/web-search-providers -H "Authorization: Bearer $TOKEN"GET /api/v1/web-search-providers/:id
Назначение: подробности. Права: Viewer+. Ответ: 200 {"success":true,"data":{...}}
curl $BASE/api/v1/web-search-providers/wsp-1 -H "Authorization: Bearer $TOKEN"PUT /api/v1/web-search-providers/:id
Назначение: обновление (пустые поля сохраняют исходные значения; APIKey сохраняется). Права: Admin+. Тело запроса: name/description/parameters/is_default (все необязательны).
Ответ: 200 {"success":true,"data":{...}}
curl -X PUT $BASE/api/v1/web-search-providers/wsp-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"is_default":true}'DELETE /api/v1/web-search-providers/:id
Назначение: удаление. Права: Admin+. Ответ: 200 {"success":true}
curl -X DELETE $BASE/api/v1/web-search-providers/wsp-1 -H "Authorization: Bearer $TOKEN"PUT /api/v1/web-search-providers/:id/credentials
Назначение: установка API key ({"api_key":"..."}; при пропуске возвращается состояние). Права: Admin+. Handler: internal/handler/web_search_provider_credentials.go
Ответ: 200 {"success":true,"data":{"fields":{"api_key":{"configured":bool}}}}
curl -X PUT $BASE/api/v1/web-search-providers/wsp-1/credentials -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"api_key":"tvly-..."}'DELETE /api/v1/web-search-providers/:id/credentials/:field
Назначение: удаление поля учётных данных (field может быть только api_key). Права: Admin+. Ответ: 204.
curl -X DELETE $BASE/api/v1/web-search-providers/wsp-1/credentials/api_key -H "Authorization: Bearer $TOKEN"POST /api/v1/web-search-providers/:id/test
Назначение: проверка сохранённого поставщика. Права: Admin+. Ответ: 200 {"success":bool,"error"}
curl -X POST $BASE/api/v1/web-search-providers/wsp-1/test -H "Authorization: Bearer $TOKEN"Источники данных (/api/v1/datasource)
Коннекторы внешнего контента (Feishu/Notion/Yuque и т. п.); задачи синхронизации записываются в KB. Handler: internal/handler/datasource.go. Большинство ответов этой группы — исходные объекты/массивы (без обёртки success).
Сейчас зарегистрированы типы: feishu, lark, feishu_drive, lark_drive, notion, confluence, yuque, dingtalk, ima, rss, gitlab. Про credentials, выбор ресурсов и ограничения синхронизации каждого коннектора см. в Импорт источников данных. После включения sync_deletions удалённые знания, принадлежащие этому источнику данных, удаляются по-настоящему; source_created_at/source_updated_at сохраняются в metadata знания.
GET /api/v1/datasource/types
Назначение: каталог доступных коннекторов. Права: Viewer+.
Ответ: 200 [{type,name,description,icon,priority,auth_type,capabilities}]
curl $BASE/api/v1/datasource/types -H "Authorization: Bearer $TOKEN"POST /api/v1/datasource/validate-credentials
Назначение: проверка исходных учётных данных (кнопка «Проверить подключение», без сохранения в БД). Права: Admin+.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
type | string | да (binding:"required") | тип коннектора |
credentials | map | да (binding:"required") | учётные данные |
Ответ: 200 {"status":"connected"}; при сбое 400 {"error":"..."}
curl -X POST $BASE/api/v1/datasource/validate-credentials -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"type":"notion","credentials":{"api_key":"ntn_xxx"}}'POST /api/v1/datasource
Назначение: создание источника данных. Права: Admin+. Тело запроса (types.DataSource):
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
knowledge_base_id | string | да | целевая KB (должна принадлежать текущему пространству) |
name | string | да | имя |
type | string | да | тип коннектора |
config | object | да | учётные данные (хранятся в зашифрованном виде) + выбор ресурсов + настройки |
sync_schedule | string | нет | выражение cron |
sync_mode | string | нет | incremental (по умолчанию)/full |
conflict_strategy | string | нет | overwrite (по умолчанию)/skip |
sync_deletions | bool | нет | по умолчанию true |
sync_log_retention_days | int | нет | по умолчанию 30 |
Ответ: 201 DataSourceResponse (учётные данные удалены, см. internal/handler/dto/datasource.go).
curl -X POST $BASE/api/v1/datasource -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"knowledge_base_id":"kb-1","name":"Синхронизация Notion","type":"notion","config":{}}'GET /api/v1/datasource
Назначение: список источников данных. Права: Viewer+. Параметры запроса: kb_id (обязательно).
Ответ: 200 [DataSourceResponse]
curl "$BASE/api/v1/datasource?kb_id=kb-1" -H "Authorization: Bearer $TOKEN"GET /api/v1/datasource/:id
Назначение: подробности. Права: Viewer+. Ответ: 200 DataSourceResponse; 404 {"error":"data source not found"}
curl $BASE/api/v1/datasource/ds-1 -H "Authorization: Bearer $TOKEN"PUT /api/v1/datasource/:id
Назначение: обновление (id/tenant_id/knowledge_base_id фиксируются на исходных значениях). Права: Admin+. Тело запроса, как при создании.
PUT полностью заменяет конфигурацию источника данных и не поддерживает частичное обновление: сначала выполните GET подробностей, затем отправьте изменённый полный объект (name, type, config, sync_schedule, sync_mode, conflict_strategy, sync_deletions, sync_log_retention_days, status и т. д.). sync_schedule и sync_deletions всегда записываются по телу запроса: при пропуске sync_schedule оно очищается до пустой строки (только ручная синхронизация, существующие задачи по расписанию при этом удаляются), при пропуске sync_deletions значение становится false; для остальных полей сохранение исходного значения при пропуске не гарантируется. Учётные данные через этот эндпоинт не изменяются: config.credentials из тела запроса игнорируется, сохранённые учётные данные остаются.
Ответ: 200 DataSourceResponse
curl -X PUT $BASE/api/v1/datasource/ds-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name":"Синхронизация Notion v2","type":"notion","knowledge_base_id":"kb-1",
"config":{"type":"notion","resource_ids":["page-1"]},
"sync_schedule":"0 0 */6 * * *","sync_mode":"incremental","conflict_strategy":"overwrite",
"sync_deletions":true,"sync_log_retention_days":30,"status":"active"}'DELETE /api/v1/datasource/:id
Назначение: удаление. Права: Admin+. Ответ: 204.
curl -X DELETE $BASE/api/v1/datasource/ds-1 -H "Authorization: Bearer $TOKEN"PUT /api/v1/datasource/:id/credentials
Назначение: полная замена учётных данных (учётные данные источника данных — атомарный map с «единственным логическим полем credentials»). Права: Admin+. Тело запроса: {"credentials":{...}} (обязателен непустой map). Handler: internal/handler/datasource_credentials.go
Ответ: 200 {"success":true,"data":{"fields":{"credentials":{"configured":bool}}}}
curl -X PUT $BASE/api/v1/datasource/ds-1/credentials -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"credentials":{"api_key":"ntn_xxx"}}'DELETE /api/v1/datasource/:id/credentials/:field
Назначение: очистка учётных данных (field должен быть credentials). Права: Admin+. Ответ: 204.
curl -X DELETE $BASE/api/v1/datasource/ds-1/credentials/credentials -H "Authorization: Bearer $TOKEN"POST /api/v1/datasource/:id/validate
Назначение: проверка подключения сохранённого источника данных. Права: Admin+. Ответ: 200 {"status":"connected"}
curl -X POST $BASE/api/v1/datasource/ds-1/validate -H "Authorization: Bearer $TOKEN"GET /api/v1/datasource/:id/resources
Назначение: просмотр дерева внешних ресурсов (ленивая загрузка). Права: Admin+. Параметры запроса: parent_id (необязательно, пусто = верхний уровень).
Ответ: 200 [{external_id,name,type,description,url,modified_at,parent_id,has_children,metadata}]
curl "$BASE/api/v1/datasource/ds-1/resources?parent_id=" -H "Authorization: Bearer $TOKEN"POST /api/v1/datasource/:id/resource-ancestors
Назначение: разбор цепочки предков ресурса (раскрытие в селекторе). Права: Admin+. Тело запроса: {"resource_ids":["..."]} (обязательно).
Ответ: 200 {"ancestors":[...]}
curl -X POST $BASE/api/v1/datasource/ds-1/resource-ancestors -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"resource_ids":["page-1"]}'POST /api/v1/datasource/:id/sync
Назначение: ручной запуск синхронизации. Права: Admin+. Ответ: 200 SyncLog (id,status,started_at,items_total,items_created,items_updated,items_deleted,items_failed,...)
curl -X POST $BASE/api/v1/datasource/ds-1/sync -H "Authorization: Bearer $TOKEN"POST /api/v1/datasource/:id/pause и POST /api/v1/datasource/:id/resume
Назначение: приостановка / возобновление синхронизации по расписанию. Права: Admin+.
Ответ: 200 {"status":"paused"} / {"status":"active"}
curl -X POST $BASE/api/v1/datasource/ds-1/pause -H "Authorization: Bearer $TOKEN"GET /api/v1/datasource/:id/logs
Назначение: список журналов синхронизации. Права: Viewer+. Параметры запроса: limit (по умолчанию 10, максимум 100), offset (по умолчанию 0).
Ответ: 200 [SyncLog]
curl "$BASE/api/v1/datasource/ds-1/logs?limit=10" -H "Authorization: Bearer $TOKEN"GET /api/v1/datasource/logs/:log_id
Назначение: одна запись журнала синхронизации. Права: Viewer+. Ответ: 200 SyncLog; 404 {"error":"sync log not found"}
curl $BASE/api/v1/datasource/logs/log-1 -H "Authorization: Bearer $TOKEN"Справочник по реализации
Регистрация маршрутов: RegisterVectorStoreRoutes, RegisterStorageBackendRoutes, RegisterWebSearchRoutes, RegisterWebSearchProviderRoutes, RegisterDataSourceRoutes в internal/router/routes_infra.go. Handler: internal/handler/vectorstore.go, internal/handler/storagebackend.go, internal/handler/web_search.go, internal/handler/web_search_provider.go, internal/handler/web_search_provider_credentials.go, internal/handler/datasource.go, internal/handler/datasource_credentials.go.