> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 基础 URL 与版本管理

# 基础 URL、版本管理与端点结构

Sorsa API 通过 URL 中的版本号保持集成稳定。版本号是基础 URL 的一部分，因此每个请求都会明确访问某个特定 API 版本。

## 基础 URL

所有请求均通过 HTTPS 发送。不支持纯 HTTP，此类请求会被拒绝。

```text theme={null}
https://api.sorsa.io/v3
```

所有端点路径都相对于此基础 URL。例如，获取用户资料的完整 URL 为：

```text theme={null}
https://api.sorsa.io/v3/info?username=elonmusk
```

## 当前版本：v3

`v3` 是 Sorsa API 当前的稳定版本，也是推荐使用的版本。所有新增端点、响应字段和改进均在 v3 下发布。

## 变更如何划分版本

并非每次更新都需要新的版本号。变更分为两类。

### 兼容性变更（在 v3 内发布）

这些变更直接添加到当前版本，不提升版本号。现有集成无需修改即可继续运行：

* 添加新端点
* 为已有端点添加新的可选查询参数
* 为 JSON 响应对象添加新字段
* 改进错误消息或在错误响应中提供更多信息

由于响应可能随时新增字段，请采用稳健的解析方式：读取所需字段并忽略未知字段，不要因出现意外字段而报错。

### 不兼容变更（使用新版本号）

如果需要移除响应字段、重命名参数、更改身份验证方式或修改端点的核心行为，我们会发布新版本（例如 `/v4`）。届时：

* 旧版本会在明确告知的停用过渡期内保持在线
* 提前发布包含字段对应关系和结构变化的迁移指南
* 通过控制台和文档公布弃用时间安排

## 旧版本：v2（已停用）

v2 已弃用并关闭。计划关闭日期为 **2026 年 5 月 1 日**，v2 端点现已返回 `410 Gone`。

如果你有现存的 Sorsa v2 集成，请通过当前 [API 参考](https://docs.sorsa.io/zh-Hans/api-reference-guide)查看 v3 请求和响应结构，并[联系支持团队](https://docs.sorsa.io/zh-Hans/support)获得迁移协助。另行提供的官方 X API 迁移指南针对的是不同的源 API。

## 后续步骤

* [身份验证](https://docs.sorsa.io/zh-Hans/authentication)：如何授权 v3 请求
* [支持](https://docs.sorsa.io/zh-Hans/support)：获取现有 Sorsa v2 集成的迁移协助
* [API 参考](https://docs.sorsa.io/zh-Hans/api-reference-guide)：浏览所有端点、参数和响应结构