World MachineAPI v1

Reference

接口参考

四个接口的完整定义。字段名、类型、取值范围与错误码均按当前服务实现列出。

Base URL:https://api.worldmachine.dev 鉴权:Bearer token 内容类型:application/json

总览

方法路径作用
POST/v1/memories写入一条原文记忆
GET/v1/entities/{entityId}按 ID 读一个实体
GET/v1/memories:recall按查询召回实体与记忆
DELETE/v1/users/me/data擦除当前凭证主体的全部数据

四个接口都不接受身份字段。租户与用户从 Authorization: Bearer <token> 派生。

Authorization: Bearer $WM_TOKEN
Content-Type: application/json

写记忆

POST /v1/memories 写入一条原文

请求头

头必需说明
Authorization是Bearer <token>
Content-Type是application/json
Idempotency-Key否幂等键,每条不同的写入各用一个。格式 [A-Za-z0-9][A-Za-z0-9_.:@-]{0,127};不合法返回 400。省略时按内容派生

请求体

字段类型必需说明
textstring是自然语言陈述,去除首尾空白后长度 1..8192 字节
occurredAtMsint64否发生时刻,epoch 毫秒。省略取服务器当前时间;负数或超过当前时间 24 小时返回 400
sourcestring否来源标签,如 crm、chat。原样保存
metadataobject否任意 JSON 对象,原样保存,不参与解释与检索
timezonestring否IANA 时区名,如 Asia/Shanghai。缺省按 UTC。非法值返回 400

请求体出现未定义字段时返回 400,不静默忽略。

响应 200

字段类型说明
eventIdstring该条记忆的稳定标识。同一幂等键重放时保持不变
deduplicatedbool仅在重放时为 true;首次写入时该字段不出现
{"eventId": "0136159b-eb97-54b5-a05d-e37619881c70"}

写入是同步的:返回 200 时原文已经可以被召回接口读到。结构化状态可能在稍后由抽取产生,本接口不承诺实体已经存在。

读实体

GET /v1/entities/{entityId} 按 ID 读一个实体

参数

参数位置必需说明
entityIdpath是实体标识,来自召回或写入后的响应
asOfValidTimeMsquery否返回该时刻成立的状态。省略为当前时刻;负数返回 400;未来时间可以传

响应 200

{ "entity": { …见 EntityView } }

实体在该时刻还不存在时返回 404 not_found。判断依据是实体头部本身:如果一个实体在指定时刻之前尚未被创建,就是 404;如果它已存在但没有任何组件(例如刚被提及的组织),返回 200,且响应里没有 components 字段(空对象按协议省略,不会出现 {})。可见性之外的数据同样返回 404,而不是 403——存在性本身也是信息。

curl -sS "$WM_API/v1/entities/ce7b7b0c-4dbd-5524-9392-13067cf6415c?asOfValidTimeMs=1759248000000" \
  -H "Authorization: Bearer $WM_TOKEN"

召回

GET /v1/memories:recall 按查询召回实体与记忆

参数

参数类型必需说明
querystring是自然语言查询,上限 8192 字节(URL 编码后计入,过长会先撞上 400)。空或全空白返回 400
maxEntitiesuint32否实体条数上限。缺省 20、硬上限 100;传 0 或超过 100 时替换为缺省值 20
maxEventsuint32否记忆条数上限。缺省 20、硬上限 100;传 0 或超过 100 时同样替换为 20
asOfValidTimeMsint64否有效时间快照,同时作用于 entities 和 memories:晚于该时刻发生的原文不会返回。省略为当前时刻;负数返回 400;未来时间可以传

响应 200

字段类型说明
entitiesEntityView[]按相关度排序的实体,含全部组件。可能为空
memoriesMemoryView[]原文列表,按词法相似度、向量距离与时间新鲜度三路融合评分排序。query 参与打分,但这里是排序权重而非硬过滤

两类结果都受各自的上限约束,且都不返回总数或游标。

{ "entities": [ … ], "memories": [ … ] }

擦除

DELETE /v1/users/me/data 擦除当前主体全部数据

没有参数,也没有请求体。被擦除的主体由凭证决定。

响应 200

{"completed": true}

成功后,该主体进入抑制状态:其后用任何指向这个人的凭证调用任何接口都返回 403 permission_denied,换一份同属此人的凭证也不例外;上游重放历史事件也不会使数据复活。擦除不可撤销,没有恢复接口。

数据模型 · EntityView

字段类型说明
entityIdstring实体标识,稳定不变
canonicalNamestring规范名。当前用户本人的实体规范名是 self,通过召回结果按名字筛选即可定位;没有按名字直查的接口
entityTypestring类型,如 Person、Organization。可能为空
aliasesstring[]别名。无别名时该字段不出现
componentsobject<string, ComponentView>以 <类型>/<实例> 为键。实体只有头部时该字段不出现,解析时请给缺省分支
不要在代码里假设 entityType 非空。刚被提及、尚未归类实体会没有类型。判断类型时给缺省分支。

数据模型 · ComponentView

字段类型说明
componentTypestring组件类型,如 Employment、Location
schemaVersionstring该组件使用的结构版本,如 wm.r1
payloadobject属性键值,结构由 componentType 与 schemaVersion 决定
validFromMsint64(字符串)生效时刻
validToMsint64(字符串)失效时刻;0 或缺省表示至今有效
confidencefloat抽取给出的置信度,0..1。可选字段,缺省时该字段不出现;示例数据里为 1。不要用它做召回阈值,召回不返回相关度分数
epistemicStatusstring认知分级,见下

epistemicStatus 取值

值含义
observed_fact经过验证的客观事实
stated_claim单方陈述。对外接口写入的默认等级
inferred_belief推断得出的结论
hypothetical_simulation假设情景下的值
disputed_claim有争议、待裁定
unknown无法归类。解析时必须处理这个取值,不要假设只有上面五种

数据模型 · MemoryView

字段类型说明
eventIdstring记忆标识,与写入响应的 eventId 一致
occurredAtMsint64(字符串)发生时刻
eventTypestring原文类型。对外写入为 text.employment.v1
summarystring原文内容,即写入时提交的 text
affectedEntityIdsstring[]该记忆影响到的实体。无关联时该字段不出现

错误码

所有错误共用一个信封,包括 401:

{"error": {"code": "invalid_argument", "message": "invalid argument: text must be 1..8192 bytes"}}
codeHTTP触发条件
invalid_argument400缺少必需参数、超长、时区非法、幂等键格式非法、请求体含未知字段
unauthenticated401缺少 Authorization 头,或凭证无法识别
permission_denied403凭证有效,但该主体已进入抑制状态
not_found404实体不存在,或在指定时刻不存在
conflict409同一幂等键配了不同内容
unsupported501该部署缺少请求所依赖的后端能力。四个接口的正常路径不会返回它,因此不能靠它探测是否启用了抽取
unavailable503依赖暂时不可用
deadline_exceeded504服务端等待超时
canceled499客户端提前断开
internal500未归类的内部错误。不返回细节

message 是给人读的诊断文本,措辞可能变化。程序逻辑请只依赖 code。

编码与类型

约定细节
64 位整数响应中一律是 JSON 字符串,如 "occurredAtMs":"1794968245880"。请求体可直接写数字
字段命名JSON 使用 lowerCamelCase,如 entityId、validFromMs
空值字段协议默认省略零值:validToMs 为 0、aliases 为空时字段不出现。解析时按缺省处理,不要当成错误
时间单位全部为 epoch 毫秒
未知字段请求体中的未知字段导致 400
请求体上限4 MiB。而 text 只占 8192 字节,其余空间留给 metadata

OpenAPI 3.1 描述文件暂未公开。本页覆盖上面四个路径与全部模型,字段以本页为准;需要机器可读文件时向服务方索取。

限制

以下是当前接口的硬约束,写入代码前先确认它们不会挡住你的用法。

项当前行为
写入粒度一次请求一条记忆,没有批量接口
文本长度1..8192 字节
查询结果条数每类上限 100,无分页游标,不返回总数
查询词的作用影响 entities 的候选与 memories 的排序权重,但不做硬过滤:无关查询仍会返回结果
未来时间写入上限为当前时间 + 24 小时
擦除主体级、不可撤销、无恢复接口;之后同一凭证返回 403
结构化抽取取决于部署是否配置抽取能力;未配置时只有原文,没有实体
分支与推演不通过对外接口提供
跨用户读取不存在。一份凭证只能访问一个主体空间