World Machine

Low-Level REST API

底层 REST API 参考

日常个人使用与 AI 编程助手接入,请优先使用 world CLI 与 Agent Skill。本页专门面向需要在自有后端服务、无 CLI 容器或自定义 Agent 框架中直接调用 HTTP 接口的底层开发者。

Base URL:https://api.worldmachine.dev鉴权:Authorization: Bearer <API Key>格式:application/json
本页目录(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。省略时按内容特征自动派生
textstring是自然语言陈述,去首尾空白后长度 1..8192 字节
occurredAtMsint64(数字)否实际发生时刻(epoch 毫秒)。省略取服务器时刻;负数或超过当前时间 +24 小时返回 400
timezonestring否说话人 IANA 时区名(如 Asia/Shanghai)。缺省按 UTC,非法返回 400
sourcestring否来源标签(如 crm、chat),仅随原文留档,不在召回中返回
metadataobject否任意 JSON 对象,仅随原文留档,不参与索引且不在召回中返回

响应 200

Response 200
{"eventId": "0136159b-eb97-54b5-a05d-e37619881c70"}

原文同步落盘并立即可召回;结构化实体在后台异步更新。重放命中去重时额外返回 "deduplicated": true。

读实体

GET /v1/entities/{entityId} 按 ID 读取单个实体与历史快照
参数位置必需说明
entityIdpath是实体标识,来自召回结果
asOfValidTimeMsquery否读取该时刻成立的状态快照(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 按自然语言查询实体与记忆
查询参数类型必需说明
querystring是自然语言问题,上限 8192 字节;空或全空白返回 400
maxEntitiesuint32否实体返回上限:有效范围 1..100;省略、传 0 或超过 100 均按 20 处理
maxEventsuint32否原文返回上限:有效范围 1..100;省略、传 0 或超过 100 均按 20 处理
asOfValidTimeMsint64(数字)否有效时间快照,同时过滤 entities 与 memories;负数返回 400
Response 200
{ "entities": [ … ], "memories": [ … ] }

响应模型(View)

EntityView

字段类型说明
entityIdstring实体稳定唯一 ID
canonicalNamestring规范名(当前用户本人通常为 self)
entityTypestring随语义动态演进(如 Person、Organization);可能为空或省略
aliasesstring[]别名列表;无别名时省略
componentsobject<string, ComponentView>键为 <组件类型>/<实例标识>;无组件时省略

ComponentView

字段类型说明
componentTypestring组件类别(随语义动态演进,如 Employment、Location)
schemaVersionstring组件结构版本号
payloadobject属性键值对象
validFromMsint64(字符串)生效开始时刻(epoch 毫秒)
validToMsint64(字符串)生效结束时刻;省略或 0 表示至今有效
confidencefloat置信度(0..1),可选
epistemicStatusstringobserved_fact / stated_claim / inferred_belief / disputed_claim / unknown

MemoryView

字段类型说明
eventIdstring记忆唯一 ID,与写入返回值一致
occurredAtMsint64(字符串)事件发生时刻(epoch 毫秒)
eventTypestring记录分类标识
summarystring写入时提交的逐字原话文本
affectedEntityIdsstring[]关联到的实体 ID 列表;无关联时省略

错误码一览

包括 401 鉴权失败在内,所有错误均返回统一 JSON 信封,程序逻辑请严格按 error.code 分支:

Error Envelope
{"error": {"code": "invalid_argument", "message": "invalid argument: text must be 1..8192 bytes"}}
codeHTTP含义
invalid_argument400参数缺失、越界、非法时区、非法幂等键或请求体含未知字段
unauthenticated401缺少 Authorization 头,或 API 密钥无效/已撤销
permission_denied403当前凭证无权访问目标资源
not_found404实体不存在,或在指定的历史时间点尚未存在
conflict409同一 Idempotency-Key 携带了不同的请求内容
canceled499客户端提前关闭连接
internal500服务端内部异常(不暴露内部堆栈细节)
unsupported501当前请求的能力不受支持
unavailable503服务暂时不可用,请退避重试
deadline_exceeded504处理超时,请使用原幂等键重试

编码约定与硬性限制

项当前规范 / 上限
64 位整数编码响应体统一编码为 JSON 字符串(避免 JS 精度丢失);请求体与 Query 参数直接传数字
命名与零值省略统一 lowerCamelCase;空数组、空对象及为 0 的 validToMs 在响应中省略
单次文本 / 查询长度1..8192 字节(去首尾空白后)
单次 HTTP 请求体上限4 MiB
单次召回数量缺省 20 条,硬上限 100 条(无分页游标)
未来时间写入上限当前服务端时间 + 24 小时