Справочник API: организации и общий доступ
Управление участниками организации, а также отношениями общего доступа к базам знаний и агентам. Единицей участника организации является рабочее пространство.
Единицей участника организации (Organization) является «пространство (tenant)». Политика API key для группы маршрутов организаций — manage_spaces или full-access; управление общим доступом KB/Agent доступно только full-access key.
Управление организациями (/api/v1/organizations)
POST /api/v1/organizations
Назначение: создание организации. Права: Admin+.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
name | string | Да | Название организации |
description | string | Нет | Описание |
avatar | string | Нет | URL аватара |
searchable | bool | Нет | Можно ли обнаружить через поиск |
require_approval | bool | Нет | Требуется ли одобрение для вступления |
member_limit | int | Нет | Верхняя граница числа пространств-участников |
invite_code_validity_days | int | Нет | Срок действия кода приглашения (дни) |
Ответ: 201 {"success":true,"data":{OrganizationResponse}}
curl -X POST $BASE/api/v1/organizations -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"организация разработки"}'GET /api/v1/organizations
Назначение: список организаций, в которых я состою. Права: Viewer+.
Ответ: 200 {"success":true,"data":{"organizations":[...],"total":N,"resource_counts":{"knowledge_bases":{"by_organization":{}},"agents":{"by_organization":{}}}}}
curl $BASE/api/v1/organizations -H "Authorization: Bearer $TOKEN"GET /api/v1/organizations/preview/:code
Назначение: предпросмотр организации по коду приглашения (без вступления). Права: Viewer+. Параметр пути: code — код приглашения.
Ответ: 200 {"success":true,"data":{id,name,description,avatar,member_count,share_count,agent_share_count,is_already_member,require_approval,created_at}}
curl $BASE/api/v1/organizations/preview/ABC123 -H "Authorization: Bearer $TOKEN"POST /api/v1/organizations/join
Назначение: вступление в организацию по коду приглашения. Права: Admin+. Тело запроса: {"invite_code":"..."} (обязательно).
Ответ: 200 {"success":true,"data":{OrganizationResponse}}
curl -X POST $BASE/api/v1/organizations/join -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"invite_code":"ABC123"}'POST /api/v1/organizations/join-request
Назначение: подача заявки на вступление (для организаций, требующих одобрения). Права: Admin+.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
invite_code | string | Да | Код приглашения |
message | string | Нет | Сопроводительное сообщение заявки |
role | string | Нет | Желаемая роль |
Ответ: 200 {"success":true,"data":{JoinRequest}}
curl -X POST $BASE/api/v1/organizations/join-request -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"invite_code":"ABC123","message":"заявка на вступление"}'GET /api/v1/organizations/search
Назначение: поиск обнаружимых (searchable) организаций. Права: Viewer+.
| Параметр запроса | Тип | Обязательный | Описание |
|---|---|---|---|
q | string | Нет | Ключевое слово |
limit | int | Нет | По умолчанию 20, верхняя граница 100 |
Ответ: 200 {"success":true,"data":[SearchableOrganization],"total":N}
curl "$BASE/api/v1/organizations/search?q=разработка" -H "Authorization: Bearer $TOKEN"POST /api/v1/organizations/join-by-id
Назначение: вступление в обнаружимую организацию по ID организации (без кода приглашения). Права: Admin+.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
organization_id | string | Да | ID целевой организации |
message | string | Нет | Сопроводительное сообщение |
role | string | Нет | Желаемая роль |
Ответ: 200 {"success":true,"data":{OrganizationResponse}}
curl -X POST $BASE/api/v1/organizations/join-by-id -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"organization_id":"org-1"}'GET /api/v1/organizations/:id
Назначение: сведения об организации. Права: Viewer+.
Ответ: 200 {"success":true,"data":{OrganizationResponse}}
curl $BASE/api/v1/organizations/org-1 -H "Authorization: Bearer $TOKEN"PUT /api/v1/organizations/:id
Назначение: обновление организации (сервисный слой проверяет, что пространство вызывающего является admin организации, без ограничения owner). Права: Admin+. Поля тела запроса как при создании (все необязательны).
Ответ: 200 {"success":true,"data":{OrganizationResponse}}
curl -X PUT $BASE/api/v1/organizations/org-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"description":"обновлённое описание"}'DELETE /api/v1/organizations/:id
Назначение: удаление организации. Права: Admin+ (сервисный слой требует owner организации).
Ответ: 200 {"success":true,"message":"Organization deleted successfully"}
curl -X DELETE $BASE/api/v1/organizations/org-1 -H "Authorization: Bearer $TOKEN"POST /api/v1/organizations/:id/leave
Назначение: выход этого пространства из организации. Права: Admin+. Без тела запроса. Базы знаний и Agent, опубликованные этим пространством в организацию, будут отозваны вместе с ним.
Ответ: 200 {"success":true,"message":"Left organization successfully"}
curl -X POST $BASE/api/v1/organizations/org-1/leave -H "Authorization: Bearer $TOKEN"POST /api/v1/organizations/:id/request-upgrade
Назначение: заявка на повышение роли этого пространства в организации. Права: Admin+.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
requested_role | string | Да | Желаемая роль в организации (viewer/editor/admin) |
message | string | Нет | Сопроводительное сообщение |
Ответ: 200 {"success":true,"data":{JoinRequest}}
curl -X POST $BASE/api/v1/organizations/org-1/request-upgrade -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"requested_role":"editor"}'POST /api/v1/organizations/:id/invite-code
Назначение: генерация кода приглашения организации. Права: Admin+ (сервисный слой требует admin организации). Без тела запроса.
Ответ: 200 {"success":true,"data":{"invite_code":"..."}}
curl -X POST $BASE/api/v1/organizations/org-1/invite-code -H "Authorization: Bearer $TOKEN"GET /api/v1/organizations/:id/search-tenants
Назначение: определение приглашаемого пространства по ID пространства. Права: Admin+, и пространство вызывающего должно быть admin организации. Начиная с v0.8.2 принимается только полный ID пространства, поиск по названию пространства больше не выполняется, параметр limit удалён.
| Параметр запроса | Тип | Обязательный | Описание |
|---|---|---|---|
q | string | Да | Полный ID пространства |
Ответ: 200 {"success":true,"data":[{"tenant_id","tenant_name"}]}. Если q не является допустимым ID, пространство не существует или уже является участником организации, возвращается пустой массив, иначе — единственный кандидат.
curl "$BASE/api/v1/organizations/org-1/search-tenants?q=10002" -H "Authorization: Bearer $TOKEN"GET /api/v1/organizations/:id/search-users
Назначение: устаревший псевдоним, поведение как у search-tenants. Права: Admin+. Параметры как выше.
curl "$BASE/api/v1/organizations/org-1/search-users?q=10002" -H "Authorization: Bearer $TOKEN"POST /api/v1/organizations/:id/invite
Назначение: прямое приглашение пространства в организацию. Права: Admin+.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
tenant_id | uint64 | Одно из двух | ID целевого пространства (рекомендуется) |
user_id | string | Одно из двух | Совместимый путь: ID пользователя (разрешается в его пространство) |
representative_user_id | string | Нет | Игнорируется, сохранён только для совместимости: у напрямую добавленного пространства нет представителя-пользователя, чтобы приглашающая сторона не могла указать, информация какого пользователя из чужого пространства появится в списке участников |
role | string | Да | Роль в организации |
Ответ: 200 {"success":true,"message":"Member added successfully"}
curl -X POST $BASE/api/v1/organizations/org-1/invite -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"tenant_id":2,"role":"viewer"}'GET /api/v1/organizations/:id/members
Назначение: список участников организации (пространств). Права: Viewer+. email возвращается только для строки собственного пространства вызывающего; для остальных пространств возвращаются только имя пользователя и аватар.
Ответ: 200 {"success":true,"data":{"members":[{id,user_id,representative_user_id,role,tenant_id,tenant_name,username,email,avatar,joined_at}],"total":N}}
curl $BASE/api/v1/organizations/org-1/members -H "Authorization: Bearer $TOKEN"PUT /api/v1/organizations/:id/members/:tenant_id
Назначение: изменение роли пространства-участника в организации. Права: Admin+. Параметр пути tenant_id — ID пространства-участника. Тело запроса: {"role":"editor"} (обязательно, viewer/editor/admin).
Ответ: 200 {"success":true,"message":"Member role updated successfully"}
curl -X PUT $BASE/api/v1/organizations/org-1/members/2 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"role":"editor"}'DELETE /api/v1/organizations/:id/members/:tenant_id
Назначение: удаление пространства-участника (включая самоудаление). Права: Admin+. Базы знаний и Agent, опубликованные удаляемым пространством в организацию, будут отозваны вместе с ним.
Ответ: 200 {"success":true,"message":"Member removed successfully"}
curl -X DELETE $BASE/api/v1/organizations/org-1/members/2 -H "Authorization: Bearer $TOKEN"GET /api/v1/organizations/:id/join-requests
Назначение: очередь заявок на вступление. Права: Admin+.
Ответ: 200 {"success":true,"data":{"requests":[{id,user_id,username,email,message,request_type,prev_role,requested_role,status,created_at,reviewed_at}],"total":N}}
curl $BASE/api/v1/organizations/org-1/join-requests -H "Authorization: Bearer $TOKEN"PUT /api/v1/organizations/:id/join-requests/:request_id/review
Назначение: одобрение заявок на вступление/повышение. Права: Admin+.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
approved | bool | Да | Одобрить/отклонить |
message | string | Нет | Комментарий к решению |
role | string | Нет | Роль, предоставляемая при одобрении |
Ответ: 200 {"success":true,"message":"Review completed"}
curl -X PUT $BASE/api/v1/organizations/org-1/join-requests/req-1/review \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"approved":true}'GET /api/v1/organizations/:id/shares
Назначение: просмотр списка KB, опубликованных в эту организацию. Права: Viewer+.
Ответ: 200 {"success":true,"data":{"shares":[KnowledgeBaseShareResponse],"total":N}}
curl $BASE/api/v1/organizations/org-1/shares -H "Authorization: Bearer $TOKEN"GET /api/v1/organizations/:id/agent-shares
Назначение: просмотр списка Agent, опубликованных в эту организацию. Права: Viewer+.
Ответ: 200 {"success":true,"data":{"shares":[AgentShareResponse],"total":N}}
curl $BASE/api/v1/organizations/org-1/agent-shares -H "Authorization: Bearer $TOKEN"GET /api/v1/organizations/:id/shared-knowledge-bases
Назначение: представление пространства организации: все общие KB внутри организации (включая мои собственные). Права: Viewer+.
Ответ: 200 {"success":true,"data":[...с флагами is_mine, source_from_agent...],"total":N}
curl $BASE/api/v1/organizations/org-1/shared-knowledge-bases -H "Authorization: Bearer $TOKEN"GET /api/v1/organizations/:id/shared-agents
Назначение: представление пространства организации: все общие Agent внутри организации. Права: Viewer+.
Ответ: 200 {"success":true,"data":[SharedAgentInfo],"total":N}
curl $BASE/api/v1/organizations/org-1/shared-agents -H "Authorization: Bearer $TOKEN"Общий доступ к KB (/api/v1/knowledge-bases/:id/shares)
API key: только full-access. Handler: internal/handler/organization.go
POST /api/v1/knowledge-bases/:id/shares
Назначение: опубликовать KB в организацию. Права: создатель KB OR Admin+.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
organization_id | string | Да | Целевая организация |
permission | string | Да | Права общего доступа (семантика роли организации, например viewer/editor) |
Ответ: 201 {"success":true,"data":{KBShare}}
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/shares -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"organization_id":"org-1","permission":"viewer"}'GET /api/v1/knowledge-bases/:id/shares
Назначение: просмотр списка публикаций этой KB. Права: Viewer+.
Ответ: 200 {"success":true,"data":{"shares":[KnowledgeBaseShareResponse],"total":N}}
curl $BASE/api/v1/knowledge-bases/kb-1/shares -H "Authorization: Bearer $TOKEN"PUT /api/v1/knowledge-bases/:id/shares/:share_id
Назначение: изменение прав общего доступа. Права: создатель KB OR Admin+. Тело запроса: {"permission":"editor"} (обязательно).
Правила сервисного слоя (общие с отменой общего доступа):
- Изначальный издатель должен действовать внутри пространства, которому принадлежит KB, а его роль в пространстве — Contributor+;
- Admin+ пространства, которому принадлежит KB, может управлять всеми публикациями этого пространства;
- Для пространства с ролью admin в целевой организации его пользователи Admin+ могут только понижать права или отменять публикацию, но не могут повышать права выше текущего значения.
share_id должен принадлежать KB из пути, иначе 404.
Ответ: 200 {"success":true,"message":"Share permission updated successfully"}
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/shares/s-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"permission":"editor"}'DELETE /api/v1/knowledge-bases/:id/shares/:share_id
Назначение: отмена общего доступа. Права: создатель KB OR Admin+, правила сервисного слоя как выше. share_id должен принадлежать KB из пути, иначе 404.
Ответ: 200 {"success":true,"message":"Share removed successfully"}
curl -X DELETE $BASE/api/v1/knowledge-bases/kb-1/shares/s-1 -H "Authorization: Bearer $TOKEN"Общий доступ к Agent (/api/v1/agents/:id/shares)
API key: только full-access. Handler: internal/handler/organization.go
POST /api/v1/agents/:id/shares
Назначение: опубликовать Agent в организацию. Права: создатель Agent OR Admin+. Тело запроса как при публикации KB (organization_id + permission, обязательно). Встроенный агент нельзя опубликовать (400): в каждом пространстве есть встроенный агент с одним и тем же ID, и после публикации получатель не сможет их различить. Область баз знаний Agent открывается участникам организации, поэтому вызывающий должен иметь право напрямую опубликовать каждую из этих баз знаний (создатель базы знаний или Admin+); kb_selection_mode: all может опубликовать только Admin+, иначе 403.
Ответ: 201 {"success":true,"data":{AgentShare}}
curl -X POST $BASE/api/v1/agents/agent-1/shares -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"organization_id":"org-1","permission":"viewer"}'GET /api/v1/agents/:id/shares
Назначение: просмотр списка публикаций этого Agent. Права: создатель Agent OR Admin+.
Ответ: 200 {"success":true,"data":{"shares":[AgentShareResponse],"total":N}}
curl $BASE/api/v1/agents/agent-1/shares -H "Authorization: Bearer $TOKEN"DELETE /api/v1/agents/:id/shares/:share_id
Назначение: отмена публикации Agent. Права: создатель Agent OR Admin+, правила сервисного слоя как при отмене публикации KB. share_id должен принадлежать Agent из пути, иначе 404.
Ответ: 200 {"success":true,"message":"Share removed successfully"}
curl -X DELETE $BASE/api/v1/agents/agent-1/shares/s-1 -H "Authorization: Bearer $TOKEN"Агрегированное представление общих ресурсов
GET /api/v1/shared-knowledge-bases
Назначение: список KB, опубликованных мне через организацию (без метаданных векторного хранилища стороны владельца). Права: Viewer+; API key требует manage_spaces или full-access.
Ответ: 200 {"success":true,"data":[...],"total":N}
curl $BASE/api/v1/shared-knowledge-bases -H "Authorization: Bearer $TOKEN"GET /api/v1/shared-agents
Назначение: список Agent, опубликованных мне через организацию. Права: Viewer+; API key как выше.
Ответ: 200 {"success":true,"data":[SharedAgentInfo],"total":N}. SharedAgentInfo содержит source_tenant_id (пространство-источник), org_name, shared_by_username, permission, а также web_search_ready — возвращается только один булев бит «доступен ли веб-поиск в пространстве-источнике», конфигурация provider пространства-источника не передаётся (это раскрыло бы конфигурацию), и provider ID принимающего пространства не используется для сравнения (это дало бы ложное сообщение о недоступности).
При вызове других эндпоинтов с общим Agent, если Agent с одинаковым именем опубликован несколькими пространствами, можно передать agent_source_tenant_id, чтобы указать пространство-источник; это значение проверяется по каждому отношению публикации, при недопустимости или отсутствии прав сразу выдаётся ошибка, без молчаливого отката к другому источнику.
curl $BASE/api/v1/shared-agents -H "Authorization: Bearer $TOKEN"POST /api/v1/shared-agents/disabled
Назначение: установка «это пространство отключает некоторый общий Agent» (влияет на выпадающий список сессий всего пространства). Права: Admin+; API key как выше.
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
agent_id | string | Да (binding:"required") | ID общего Agent |
disabled | bool | Нет | Отключён ли (по умолчанию false) |
Ответ: 200 {"success":true}
curl -X POST $BASE/api/v1/shared-agents/disabled -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"agent_id":"agent-1","disabled":true}'Справочник по реализации
Регистрация маршрутов: RegisterOrganizationRoutes в internal/router/routes_agent.go. Handler: internal/handler/organization.go.