API 参考（自动生成）

本文档由共享查询契约 @halfway/atlas-core/runtime 自动生成，与 GET /api/atlas/v1/openapi.json 同源。

端点总览

方法	路径	说明	鉴权
GET	/api/atlas/v1/ready	就绪检查（公开）	公开
GET	/api/atlas/v1/openapi.json	OpenAPI 文档（公开）	公开
GET	/api/atlas/v1/stats	知识包统计	Bearer
GET	/api/atlas/v1/lookup	精确查找	Bearer
POST	/api/atlas/v1/search	全文检索	Bearer
POST	/api/atlas/v1/graph	实体邻域图谱	Bearer
GET	/api/atlas/v1/admin/billing	月度账单（管理）	Bearer
GET	/api/atlas/v1/admin/usage	用量报表（管理）	Bearer
POST	/api/atlas/v1/admin/reload	触发热更新（管理）	Bearer

鉴权

除 GET /api/atlas/v1/ready 与 GET /api/atlas/v1/openapi.json 外，所有端点需请求头携带：

Authorization: Bearer <API_KEY>

Schema

AtlasError

{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "example": "UNAUTHORIZED"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

AtlasEntityKind

{
  "type": "string",
  "enum": [
    "person",
    "work",
    "place",
    "organization",
    "movement",
    "concept",
    "source"
  ]
}

AtlasSearchRequest

{
  "type": "object",
  "required": [
    "q"
  ],
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "example": "安藤忠雄"
    },
    "scope": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AtlasEntityKind"
      }
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    }
  }
}

AtlasSearchHit

{
  "type": "object",
  "required": [
    "id",
    "kind",
    "displayName",
    "slug",
    "score"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "kind": {
      "$ref": "#/components/schemas/AtlasEntityKind"
    },
    "displayName": {
      "type": "string"
    },
    "slug": {
      "type": "string"
    },
    "score": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "matchedField": {
      "type": "string"
    }
  }
}

AtlasSearchResponse

{
  "type": "object",
  "required": [
    "q",
    "count",
    "hits"
  ],
  "properties": {
    "q": {
      "type": "string"
    },
    "count": {
      "type": "integer"
    },
    "hits": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AtlasSearchHit"
      }
    }
  }
}

AtlasGraphRequest

{
  "type": "object",
  "required": [
    "rootId"
  ],
  "properties": {
    "rootId": {
      "type": "string",
      "example": "per_tadao-ando"
    },
    "maxDepth": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5,
      "default": 2
    },
    "maxNodes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 40
    }
  }
}

AtlasGraphNode

{
  "type": "object",
  "required": [
    "id",
    "label",
    "kind",
    "group"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "label": {
      "type": "string"
    },
    "kind": {
      "type": "string"
    },
    "group": {
      "type": "string"
    },
    "description": {
      "type": "string"
    }
  }
}

AtlasGraphEdge

{
  "type": "object",
  "required": [
    "id",
    "source",
    "target",
    "label",
    "type",
    "confidence"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "source": {
      "type": "string"
    },
    "target": {
      "type": "string"
    },
    "label": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "confidence": {
      "type": "number"
    }
  }
}

AtlasGraphResponse

{
  "type": "object",
  "required": [
    "rootId",
    "nodes",
    "edges",
    "truncated"
  ],
  "properties": {
    "rootId": {
      "type": "string"
    },
    "nodes": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AtlasGraphNode"
      }
    },
    "edges": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AtlasGraphEdge"
      }
    },
    "truncated": {
      "type": "boolean"
    }
  }
}

AtlasLookupResult

{
  "type": "object",
  "required": [
    "kind",
    "id",
    "data"
  ],
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "entity",
        "relationship",
        "evidence"
      ]
    },
    "id": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "additionalProperties": true
    }
  }
}

AtlasManifest

{
  "type": "object",
  "required": [
    "counts",
    "releasedEntityIds",
    "filter",
    "governance"
  ],
  "properties": {
    "counts": {
      "type": "object",
      "additionalProperties": {
        "type": "integer"
      }
    },
    "releasedEntityIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "filter": {
      "type": "object",
      "properties": {
        "visibility": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "governance": {
      "type": "object",
      "properties": {
        "totalEntities": {
          "type": "integer"
        },
        "published": {
          "type": "integer"
        },
        "withSources": {
          "type": "integer"
        },
        "reviewed": {
          "type": "integer"
        },
        "aiCandidateRelationships": {
          "type": "integer"
        },
        "relationshipsSkippedMissingEndpoint": {
          "type": "integer"
        }
      }
    }
  }
}

AtlasStatsResponse

{
  "type": "object",
  "required": [
    "version",
    "manifest"
  ],
  "properties": {
    "version": {
      "type": "object",
      "properties": {
        "version": {
          "type": "string"
        },
        "channel": {
          "type": "string"
        },
        "packId": {
          "type": "string"
        },
        "releasedAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "manifest": {
      "$ref": "#/components/schemas/AtlasManifest"
    }
  }
}

AtlasReadyResponse

{
  "type": "object",
  "required": [
    "ok",
    "service",
    "version"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "enum": [
        true
      ]
    },
    "service": {
      "type": "string"
    },
    "version": {
      "type": "string"
    },
    "packId": {
      "type": "string"
    },
    "packName": {
      "type": "string"
    },
    "channel": {
      "type": "string"
    },
    "releasedAt": {
      "type": "string",
      "format": "date-time"
    }
  }
}