介绍

MCSearch 统一 API 概览 —— 基础地址、通用响应头与公共参数。

MCSearch 对外提供统一的 HTTP / SSE API,覆盖服务器状态查询、状态 Banner、服务器图标、 Mod 聚合搜索与 Wiki 代理等能力。所有接口无需鉴权,默认允许跨域调用(支持 OPTIONS 预检)。

基础地址

线上服务部署于 https://search.tecostudio.cn,所有接口位于 /api/v1 路径下,例如:

https://search.tecostudio.cn/api/v1/server/status?host=mc.hypixel.net

通用响应头

每个 /api/v1/* 接口都会返回以下响应头:

响应头说明
X-Powered-By固定为 MCSearch
X-CacheHIT 命中缓存 / MISS 未命中
X-Response-Time服务端处理耗时(毫秒)
Access-Control-Allow-Origin*,允许任意来源跨域

限流

除 /api/v1/health 外的 /api/v1/* 接口按客户端 IP 限流(默认每分钟 60 次,可由 RATE_LIMIT_RPM 配置;未配置 Redis 时不限流)。每个响应附带以下响应头,超限时返回 429 并带 Retry-After:

响应头说明
X-RateLimit-Limit当前窗口的请求上限
X-RateLimit-Remaining当前窗口剩余可用次数
X-RateLimit-Reset窗口重置的 Unix 时间戳(秒)

公共参数

服务器类接口共用以下查询参数:

参数必填说明
host是服务器地址(域名或 IP)
port否端口;缺省时走 SRV 解析或版本默认端口
edition否java(默认)/ bedrock / auto

接口一览

想直接试一试?打开 Playground 在浏览器里调用任意接口。