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

# 品牌别名

> 列出和管理用于分析 AI 回复的品牌备用名称。

品牌别名让 Topify 能将缩写、空格变体和产品名称识别为您的品牌。每个项目最多可设置 20 个别名。

每个别名可使用 `fuzzy` 匹配（容忍大小写和空格差异）或 `exact` 匹配（要求完整词匹配）。

## 列出别名

```http theme={null}
GET /projects/{project_id}/aliases
```

```bash theme={null}
curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/aliases" \
  -H "X-API-Key: tk_live_..."
```

### 响应

```json theme={null}
{
  "success": true,
  "data": {
    "project_id": "a1b2c3d4-...",
    "brand_name": "Acme",
    "aliases": [
      { "name": "ACME Corp", "match_type": "fuzzy" }
    ],
    "limit": 20,
    "remaining": 19
  }
}
```

***

## 添加别名

```http theme={null}
POST /projects/{project_id}/aliases
```

### 请求体

| 字段           | 类型     | 必填 | 说明                   |
| ------------ | ------ | -- | -------------------- |
| `alias`      | string | 是  | 1-100 个字符的别名文本       |
| `match_type` | string | 否  | `fuzzy`（默认）或 `exact` |

```bash theme={null}
curl -X POST "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/aliases" \
  -H "X-API-Key: tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"alias":"ACME Corp","match_type":"fuzzy"}'
```

响应会返回完整的更新后别名列表、剩余容量以及用于再次列出别名的 `next_actions`。

***

## 更新别名

```http theme={null}
PATCH /projects/{project_id}/aliases
```

可重命名别名、更改匹配类型，或同时执行两项操作。

### 请求体

| 字段               | 类型     | 必填 | 说明                                |
| ---------------- | ------ | -- | --------------------------------- |
| `original_alias` | string | 是  | 现有别名；匹配不区分大小写                     |
| `new_alias`      | string | 是  | 新的别名文本                            |
| `match_type`     | string | 否  | 新的 `fuzzy` 或 `exact` 设置；省略则保留当前设置 |

```bash theme={null}
curl -X PATCH "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/aliases" \
  -H "X-API-Key: tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"original_alias":"ACME Corp","new_alias":"Acme Corporation","match_type":"exact"}'
```

***

## 删除别名

```http theme={null}
DELETE /projects/{project_id}/aliases?alias={alias}
```

使用不区分大小写的匹配删除一个别名。此操作不会删除提示词或历史 AI 回复。

<Warning>
  别名会立即删除。发送请求前请确认别名值。
</Warning>

```bash theme={null}
curl -X DELETE "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/aliases?alias=Acme%20Corporation" \
  -H "X-API-Key: tk_live_..."
```

### 错误响应

| 状态码   | 错误代码                             | 原因             |
| ----- | -------------------------------- | -------------- |
| `400` | `ALIAS_EMPTY` 或 `ALIAS_TOO_LONG` | 别名文本无效         |
| `404` | `ALIAS_NOT_FOUND`                | 请求的别名不存在       |
| `409` | `ALIAS_DUPLICATE`                | 已存在不区分大小写的重复别名 |
| `429` | `ALIAS_LIMIT_REACHED`            | 项目已有 20 个别名    |