Low-Level REST API
底层 REST API 参考
日常个人使用与 AI 编程助手接入,请优先使用 world CLI 与 Agent Skill。本页专门面向需要在自有后端服务、无 CLI 容器或自定义 Agent 框架中直接调用 HTTP 接口的底层开发者。
本页目录(8 节)
适用场景与快速示例
前往 开发者控制台 · API 密钥 创建密钥并配置为服务端环境变量 WM_API_KEY,即可直接向 https://api.worldmachine.dev 发送 HTTPS 请求:
cURL
curl -sS -X POST "https://api.worldmachine.dev/v1/memories" \ -H "Authorization: Bearer $WM_API_KEY" \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: order-A1024-001' \ -d '{"text":"我上个月搬到上海,现在在 Acme 当架构师。","timezone":"Asia/Shanghai"}' # 召回实体与原话 curl -sS -G "https://api.worldmachine.dev/v1/memories:recall" \ -H "Authorization: Bearer $WM_API_KEY" \ --data-urlencode 'query=上海 工作' \ --data-urlencode 'maxEntities=5'
TypeScript
const res = await fetch("https://api.worldmachine.dev/v1/memories", { method: "POST", headers: { Authorization: `Bearer ${process.env.WM_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "conv-2026-001", }, body: JSON.stringify({ text: "我上个月搬到上海,现在在 Acme 当架构师。", timezone: "Asia/Shanghai", }), }); const { eventId } = await res.json();
Python
import os, requests resp = requests.post( "https://api.worldmachine.dev/v1/memories", headers={ "Authorization": f"Bearer {os.environ['WM_API_KEY']}", "Idempotency-Key": "conv-2026-001", }, json={ "text": "我上个月搬到上海,现在在 Acme 当架构师。", "timezone": "Asia/Shanghai", }, ) print(resp.json()["eventId"])
鉴权、幂等与批量重试
- 严格身份派生:所有请求通过
Authorization: Bearer <api_key>在服务端边界推导归属空间;请求体中严禁携带tenantId/userId等未定义字段,否则直接返回400 invalid_argument。 - 显式幂等键:生产写入与批量导入务必传入请求头
Idempotency-Key(匹配[A-Za-z0-9][A-Za-z0-9_.:@-]{0,127})。相同键 + 相同内容重试会返回同一eventId并附带"deduplicated":true;同键配不同内容返回409 conflict。 - 退避重试策略:网络超时、
429、500 internal、503 unavailable、504 deadline_exceeded可携带原幂等键指数退避重试;400/401/403/409不要盲目重试。 - 批量导入节奏:无批量端点,按单条写入;建议以源系统主键作幂等键,从 4–8 并发起步,先抽样验证 50–100 条再全量跑批。
写记忆
POST /v1/memories 写入一条原文陈述
请求头与请求体
| 字段 / 头 | 类型 | 必需 | 说明 |
|---|---|---|---|
| Idempotency-Key(头) | string | 否 | 格式 [A-Za-z0-9][A-Za-z0-9_.:@-]{0,127};非法返回 400。省略时按内容特征自动派生 |
| text | string | 是 | 自然语言陈述,去首尾空白后长度 1..8192 字节 |
| occurredAtMs | int64(数字) | 否 | 实际发生时刻(epoch 毫秒)。省略取服务器时刻;负数或超过当前时间 +24 小时返回 400 |
| timezone | string | 否 | 说话人 IANA 时区名(如 Asia/Shanghai)。缺省按 UTC,非法返回 400 |
| source | string | 否 | 来源标签(如 crm、chat),仅随原文留档,不在召回中返回 |
| metadata | object | 否 | 任意 JSON 对象,仅随原文留档,不参与索引且不在召回中返回 |
响应 200
Response 200
{"eventId": "0136159b-eb97-54b5-a05d-e37619881c70"} 原文同步落盘并立即可召回;结构化实体在后台异步更新。重放命中去重时额外返回 "deduplicated": true。
读实体
GET /v1/entities/{entityId} 按 ID 读取单个实体与历史快照
| 参数 | 位置 | 必需 | 说明 |
|---|---|---|---|
| entityId | path | 是 | 实体标识,来自召回结果 |
| asOfValidTimeMs | query | 否 | 读取该时刻成立的状态快照(int64 数字);省略取当前时刻;负数返回 400 |
Request
curl -sS "https://api.worldmachine.dev/v1/entities/ce7b7b0c-4dbd-5524-9392-13067cf6415c?asOfValidTimeMs=1759248000000" \ -H "Authorization: Bearer $WM_API_KEY"
Response 200
{
"entity": {
"entityId": "ce7b7b0c-4dbd-5524-9392-13067cf6415c",
"canonicalName": "self",
"entityType": "Person",
"components": {
"Location/loc:home": {
"componentType": "Location",
"schemaVersion": "wm.r1",
"payload": { "category": "home", "city": "上海" },
"validFromMs": "1790784000000",
"confidence": 1,
"epistemicStatus": "stated_claim"
}
}
}
} 若实体不存在、不属于当前主体或在指定时刻尚未创建,统一返回 404 not_found;若存在但暂无组件,返回 200 并省略 components。
召回
GET /v1/memories:recall 按自然语言查询实体与记忆
| 查询参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
| query | string | 是 | 自然语言问题,上限 8192 字节;空或全空白返回 400 |
| maxEntities | uint32 | 否 | 实体返回上限:有效范围 1..100;省略、传 0 或超过 100 均按 20 处理 |
| maxEvents | uint32 | 否 | 原文返回上限:有效范围 1..100;省略、传 0 或超过 100 均按 20 处理 |
| asOfValidTimeMs | int64(数字) | 否 | 有效时间快照,同时过滤 entities 与 memories;负数返回 400 |
Response 200
{ "entities": [ … ], "memories": [ … ] } 响应模型(View)
EntityView
| 字段 | 类型 | 说明 |
|---|---|---|
| entityId | string | 实体稳定唯一 ID |
| canonicalName | string | 规范名(当前用户本人通常为 self) |
| entityType | string | 随语义动态演进(如 Person、Organization);可能为空或省略 |
| aliases | string[] | 别名列表;无别名时省略 |
| components | object<string, ComponentView> | 键为 <组件类型>/<实例标识>;无组件时省略 |
ComponentView
| 字段 | 类型 | 说明 |
|---|---|---|
| componentType | string | 组件类别(随语义动态演进,如 Employment、Location) |
| schemaVersion | string | 组件结构版本号 |
| payload | object | 属性键值对象 |
| validFromMs | int64(字符串) | 生效开始时刻(epoch 毫秒) |
| validToMs | int64(字符串) | 生效结束时刻;省略或 0 表示至今有效 |
| confidence | float | 置信度(0..1),可选 |
| epistemicStatus | string | observed_fact / stated_claim / inferred_belief / disputed_claim / unknown |
MemoryView
| 字段 | 类型 | 说明 |
|---|---|---|
| eventId | string | 记忆唯一 ID,与写入返回值一致 |
| occurredAtMs | int64(字符串) | 事件发生时刻(epoch 毫秒) |
| eventType | string | 记录分类标识 |
| summary | string | 写入时提交的逐字原话文本 |
| affectedEntityIds | string[] | 关联到的实体 ID 列表;无关联时省略 |
错误码一览
包括 401 鉴权失败在内,所有错误均返回统一 JSON 信封,程序逻辑请严格按 error.code 分支:
Error Envelope
{"error": {"code": "invalid_argument", "message": "invalid argument: text must be 1..8192 bytes"}} | code | HTTP | 含义 |
|---|---|---|
| invalid_argument | 400 | 参数缺失、越界、非法时区、非法幂等键或请求体含未知字段 |
| unauthenticated | 401 | 缺少 Authorization 头,或 API 密钥无效/已撤销 |
| permission_denied | 403 | 当前凭证无权访问目标资源 |
| not_found | 404 | 实体不存在,或在指定的历史时间点尚未存在 |
| conflict | 409 | 同一 Idempotency-Key 携带了不同的请求内容 |
| canceled | 499 | 客户端提前关闭连接 |
| internal | 500 | 服务端内部异常(不暴露内部堆栈细节) |
| unsupported | 501 | 当前请求的能力不受支持 |
| unavailable | 503 | 服务暂时不可用,请退避重试 |
| deadline_exceeded | 504 | 处理超时,请使用原幂等键重试 |
编码约定与硬性限制
| 项 | 当前规范 / 上限 |
|---|---|
| 64 位整数编码 | 响应体统一编码为 JSON 字符串(避免 JS 精度丢失);请求体与 Query 参数直接传数字 |
| 命名与零值省略 | 统一 lowerCamelCase;空数组、空对象及为 0 的 validToMs 在响应中省略 |
| 单次文本 / 查询长度 | 1..8192 字节(去首尾空白后) |
| 单次 HTTP 请求体上限 | 4 MiB |
| 单次召回数量 | 缺省 20 条,硬上限 100 条(无分页游标) |
| 未来时间写入上限 | 当前服务端时间 + 24 小时 |