用途:通过 ibl.ai 平台 API 读取和写入组织的全局设置。所有设置都保存在同一个组织元数据对象中,包括默认智能体(Default Agent)、帮助中心 URL、聊天区域宽度以及若干功能开关,适合用于配置组织范围内的行为。
认证与约定:基础 URL 为 https://api.iblai.app;每个请求都需携带请求头 Authorization: Api-Token $IBLAI_API_KEY。路径变量 {org} 对应 $IBLAI_ORG,{username} 对应 $IBLAI_USERNAME。尚未连接时,先运行 /iblai-login 以填充 IBLAI_ORG、IBLAI_USERNAME 和 IBLAI_API_KEY。
读取:GET https://api.iblai.app/dm/api/core/orgs/{org}/metadata/ 可读取全部组织设置;GET https://api.iblai.app/dm/api/search/orgs/{org}/users/{username}/mentors/ 可获取有效的默认智能体取值来源。
写入:PUT https://api.iblai.app/dm/api/core/orgs/{org}/metadata/ 保存设置,需将整个对象连同合并后的键一起回传,请求体形如 {"metadata": {"…existing…": "preserved", "<settingKey>": "boolean|string"}}。默认智能体对应 overall_default_mentor(取 mentor 的 unique_id 或字符串 "none");帮助中心 URL 对应 help_center_url(字符串);聊天区域宽度对应 chat_area_size(字符串);帮助菜单、无障碍菜单、持久聊天输入标签、社区智能体、举报不当内容等开关为布尔值,其键名由元数据目录在运行时分配。
限制与注意事项:PUT 会替换整个元数据对象,因此必须先 GET 读取、合并要修改的键,再回传完整对象,否则遗漏的键会丢失。overall_default_mentor 取 mentor 来源端点返回的 unique_id,或用字面量 "none" 清除。各开关的键名由元数据目录在运行时分配,应从 GET 响应中读取,不要硬编码。