HTTP API

HTTP API 是访问 PowerContext Server 的语言无关接口。默认 base URL 为 http://127.0.0.1:8000。

如果你要把 PowerContext 接入自己的 AI 应用，而不是查找单个字段，请先完成 HTTP API 生命周期教程。本页保留为路径、契约和错误语义参考。

查看契约

本地未启用鉴权的 Server 运行后，可以打开 /docs 查看交互式 Scalar API 参考，或打开 /openapi.json 获取该进程实际提供的 契约。

仓库中的契约源文件是 openapi/powercontext.yaml。 生成客户端或检查全部请求、响应字段时以它为准。启用 Server 鉴权后，/docs 仍保持公开以渲染参考页，但在其中发起的 请求仍需鉴权。/openapi.json 需要 Bearer token。浏览器地址栏无法添加该 header；应使用可信的代理或浏览器配置注入 header，或者通过带鉴权的命令下载 /openapi.json。不要把 token 放进 URL。

请求鉴权

默认的 loopback 安装不启用鉴权。运维者启用鉴权后，API 和 MCP 请求需要携带：

Authorization: Bearer <token>

下面的示例使用两个可选 shell 变量：

POWERCONTEXT_URL=http://127.0.0.1:8000
POWERCONTEXT_AUTH_HEADER="Authorization: Bearer ${POWERCONTEXT_CLIENT_API_TOKEN}"

未启用鉴权时，请去掉 --header "$POWERCONTEXT_AUTH_HEADER"。/health/live 和 /health/ready 始终公开。 允许远程访问前，请先阅读部署 Server。

Server 启用鉴权时，可以用以下命令下载该进程实际提供的契约：

curl --fail \
  --header "$POWERCONTEXT_AUTH_HEADER" \
  --output powercontext-openapi.json \
  "$POWERCONTEXT_URL/openapi.json"

保存并搜索一条 Memory

将 POWERCONTEXT_SCOPE_ID 设置为 create_scope 返回的已有 ID，并在不同会话中复用。会话 ID 不是持久的 项目身份。

保存一条已经整理好的 Memory：

curl --fail \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "$POWERCONTEXT_AUTH_HEADER" \
  --data "{
    \"scope_id\": \"${POWERCONTEXT_SCOPE_ID}\",
    \"kind\": \"decision\",
    \"text\": \"公开 API 保持异步。\"
  }" \
  "$POWERCONTEXT_URL/v1/memory/remember"

响应包含精确 citation。后续请求需要修订、停用或读取这个不可变 revision 时，应保留并传回该 citation。

在同一个 scope 中搜索 active entry：

curl --fail \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "$POWERCONTEXT_AUTH_HEADER" \
  --data "{
    \"scope_id\": \"${POWERCONTEXT_SCOPE_ID}\",
    \"query\": \"公开 API\",
    \"limit\": 5
  }" \
  "$POWERCONTEXT_URL/v1/memory/search"

Scope 内的操作提示词

操作提示词使用 family=prompt，遵循 Artifact 的 Scope 权限边界。启用 Access 后，创建提示词和生成示例需要 scope.contribute；读取当前内容、指定版本或版本历史需要 artifact.read；替换提示词需要 artifact.write。 Scope 的读取角色继承提示词的读取和使用权限，创建者拥有该逻辑 Prompt。当前不提供直接分享 Prompt 的可授予角色。

GET /v1/scopes/{scope_id}/prompts/{prompt_key} 读取当前配置，不保存版本，也不调用推理服务。 该接口需要 scope.read；已有保存记录时，还需要 artifact.read。返回内容包括：

• mode、status 和 reason：所选模式，以及当前操作是否支持自定义。
• effective：所选指令和案例。Auto 返回当前部署的内置指令，Custom 返回已保存的内容。
• builtin：当前部署的内置指令、版本和适用的 profile，记忆抽取会匹配运行时使用的 coding 或 conversation 配置。
• artifact 和 artifact_etag：已保存的当前版本引用及其条件更新标记。首次保存前两者均为 null。 已保存的 Auto 仍保留版本引用，其实际指令来自运行时。

未启用的操作仍可查看。外部注入组件自行管理提示词，因此其 effective 和 builtin 均为 null。 读取结果不能直接作为 Prompt 内容写回：保存 Auto 时，powercontext.prompt.v1 中的 instructions 和 demonstrations 仍为空。

/prompts 页面以只读方式展示 Auto 指令。首次切换到自定义时以默认指令为起点，切换模式会保留未保存的自定义 指令和案例，并可展开查看当前部署的内置指令进行对照。

通过 GET /v1/scopes/{scope_id}/artifacts/prompt/{prompt_key}/revisions 查看不可变的版本历史，通过 POST /v1/scopes/{scope_id}/prompts/{prompt_key}/demonstrations 生成可编辑示例。示例不会自动保存。 回滚时读取指定历史版本，再携带当前 If-Match 条件替换，生成新版本。例如当前为版本 3，恢复版本 2 会创建版本 4。 恢复 Auto 使用当前部署的内置指令，历史记录不会归档旧部署的内置模板。定时与手动推理使用相同的 Scope 提示词配置。

把一个逻辑 Handoff 授予接收者

scope_id 本身从不授予权限。Handoff owner 或获授权的 delegator 通过创建 Binding，把一个逻辑 committed Handoff 授予接收者已经认证的 Principal：

curl --fail \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "$POWERCONTEXT_AUTH_HEADER" \
  --data '{
    "subject": {"type": "user", "id": "idp:user-b", "description": "用户 B"},
    "resource": {
      "type": "artifact",
      "scope_id": "project:example",
      "identity": {"family": "handoff", "artifact_id": "handoff-42"},
      "selector": null
    },
    "role": "handoff.receiver",
    "idempotency_key": "handoff-42-to-user-b"
  }' \
  "$POWERCONTEXT_URL/v1/access/bindings/create"

接收者可以读取和确认这个 Handoff 的历史、当前及未来 Revision。Continue 会展示所选 Revision 的不可变 manifest 中的 citation，并检查这些被引用资源，不需要为每条 citation 再创建 Binding。这种 manifest 范围内的检查不会授权通用的 Source、Memory 或 Artifact 接口；除非另有 scope 或 Artifact role，否则接收者仍不能发现其他 Handoff 或读取父 scope。 它只能对已绑定的逻辑 Handoff 请求 latest。用 /v1/access/me 确认部署建立的 Principal，用 /v1/access/check 检查一个由 all 或 any 组合的权限要求， 用 /v1/access/resources/list 非发现式地列出已经可见的资源。创建操作按授权者与幂等键保证幂等；撤销时必须提交 binding_id 和 expected_version。/v1/access/bindings/replace 会原子撤销一个不可变 Binding，并用相同 Resource 和 role 创建后继 Binding；角色描述通过 many_per_resource 或 one_per_resource 声明活动 Binding 数量约束。Server 管理员可通过 /v1/access/audit/list 查看关系变更与决策事件。认证层确认代办执行时， 每条审计事件会把 effective principal 与可信 actor 记录为两个独立的 opaque identity。

Access wire contract 只使用 server、scope 和 artifact 三种 Resource Kind。Artifact Resource 使用逻辑 identity {family, artifact_id}，刻意不包含 Revision；Memory 可使用仅含 entry_id 的 memory_entry selector 缩小授权单位。 未知 Family、未实现 Prompt lifecycle 的 prompt 或不匹配的 selector/role 都不会创建 Binding。/v1/access/me 会报告 当前 mode、Provider 能力和每个 Artifact Family 的启用状态。

跨 Scope 的 Artifact 发布统一使用 POST /v1/artifact-publications。请求选择一个精确 source Revision，但授权检查的是 其逻辑 {family, artifact_id} identity 上的 artifact.share，以及目标 Scope 上的 scope.admin。因此一个逻辑分享授权 可以覆盖 source 的历史与后续 Revision，而每次 publication 仍会记录实际复制的精确 Revision 和 provenance。 host-local projection 由对应的 Scope 与 Artifact 权限保护。

Prompt 发布返回 422 / artifact_publication_unsupported，不会创建目标 Artifact。要在另一个 Scope 中配置 Prompt， 请使用 POST /v1/scopes/{scope_id}/artifacts，指定 family=prompt 和已注册的 prompt_key；更新时使用 PUT /v1/scopes/{scope_id}/artifacts/prompt/{prompt_key} 并携带 If-Match。这些操作会保留 Prompt 的固定身份并校验内容。

标准 Skill 生命周期复用同一 Access 边界：Library 列表要求 scope.read，生命周期变更要求 artifact.write， package manifest/download 要求 artifact.read，package proposal 要求 scope.contribute，替换已有 Skill 时还要求 artifact.write；usage capture 同时要求 scope.contribute 与 artifact.read。远端 target 管理要求 scope.admin，发布精确 Revision 还要求该 Skill 的 artifact.read。注册接口由一次性 enrollment code 保护， Receiver 的 reconcile/download/receipt 使用单独签发的 TargetBearerAuth 凭据，而不是用户 Principal。 公开 API 会在 scope 查询、package 检查、target 查询或文件系统操作之前执行对应 Access 检查。

内置静态 token 只代表一个本地管理员，无法表达不同的 A/B 用户。真正的多用户部署必须把每个调用者认证为不同的 Principal，并注入 Authorization Provider。HTTP 与 MCP 使用同一个策略执行点；MCP tool 可见不等于有权限。

查找操作

完整路径、schema、限制和状态码以 OpenAPI 契约为准。高层工作流和 Python 示例见接口。

处理错误和并发变更

错误统一使用以下 JSON envelope：

{
  "error": {
    "code": "invalid_request",
    "message": "The request violates the API contract.",
    "details": {}
  }
}

常见状态码：

每个响应都包含 X-PowerContext-Request-ID，排查失败请求时应记录它。修订或停用 Memory 时应传回精确 citation。 Candidate 审核写操作需要当前 expected_version；收到 409 后，应重新读取 Candidate，再决定是否重试。