用途:这是 iblai 平台的一个元数据接口,以键值对形式保存每个用户、每个组织的数据,常见用途包括用户偏好、应用设置、功能开关和引导(onboarding)进度。元数据按用户和按组织(platform_key)隔离,同一用户在不同组织可持有不同元数据。
认证与约定:基础地址为 https://api.iblai.app,每个请求需带请求头 Authorization: Api-Token $IBLAI_API_KEY。路径中的 {org} 对应 $IBLAI_ORG,以 platform_key 查询参数传递;{username} 对应 $IBLAI_USERNAME。所有操作都命中 …/dm/api/core/users/platform-metadata/,并携带 ?platform_key={org}。若尚未连接,先运行 /iblai-login 以填充 IBLAI_ORG、IBLAI_USERNAME 和 IBLAI_API_KEY。
读取:GET https://api.iblai.app/dm/api/core/users/platform-metadata/?platform_key={org} 可获取全部元数据,默认返回已认证用户的数据。
写入:PATCH 同一地址用于增量更新或删除指定键,不影响其他键,请求体需至少包含 metadata 或 delete_keys 之一,如 {"metadata":{"<key>":"<value>"},"delete_keys":["<key>"]};PUT 用于替换全部元数据,请求体为 {"metadata":{}},未包含的键会被丢弃;DELETE 用于清空该用户全部元数据,属破坏性操作,需先确认。
管理员操作:在上述任一请求后附加 &username={other_user},即可读取、更新、替换或删除其他用户的元数据(仅限管理员)。
示例:为当前登录用户保存引导进度和主题偏好而不动其他键:curl -X PATCH "https://api.iblai.app/dm/api/core/users/platform-metadata/?platform_key=$IBLAI_ORG" -H "Authorization: Api-Token $IBLAI_API_KEY" -H "Content-Type: application/json" -d '{ "metadata": { "onboarding_step": "3", "theme": "dark" } }'
限制:PATCH 若既没有 metadata 也没有 delete_keys 会返回 400;PUT 会整体替换对象,未列出的键将丢失;DELETE 会清空全部元数据。关于配额、调用频率、价格等信息,资料暂未提供。