> ## 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.

# 项目

> 列出并获取您的品牌跟踪项目。

项目代表您在 Topify.ai 中跟踪的品牌。每个项目都包含搜索词、竞争对手、来源以及分析数据。

## 列出项目

```
GET /projects
```

返回您的 API 密钥可访问的所有项目，按创建日期排序（最早在前）。

### 请求

无查询参数。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects" \
      -H "X-API-Key: tk_live_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get("/projects")
    ```
  </Tab>

  <Tab title="Node.js（服务端）">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects`, { headers });
    ```
  </Tab>
</Tabs>

### 响应

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "My Brand Project",
      "brand_name": "Acme Corp",
      "website_url": "https://acme.com",
      "location": "US",
      "language": "en",
      "brand_aliases": [],
      "created_at": "2026-01-15T10:30:00+00:00"
    }
  ]
}
```

### 响应字段

| 字段              | 类型                | 可空  | 描述                            |
| --------------- | ----------------- | --- | ----------------------------- |
| `id`            | string (UUID)     | No  | 项目 ID                         |
| `name`          | string            | No  | 项目显示名称                        |
| `brand_name`    | string            | Yes | 正在跟踪的主要品牌名称                   |
| `website_url`   | string            | Yes | 品牌网站 URL                      |
| `location`      | string            | Yes | 目标市场国家代码                      |
| `language`      | string            | Yes | 目标语言代码                        |
| `brand_aliases` | string\[]         | No  | 列表视图中始终为 `[]`。请使用获取单个项目端点查看别名 |
| `created_at`    | string (ISO 8601) | No  | 创建时间                          |

***

## 获取项目

```
GET /projects/{project_id}
```

返回单个项目的详细信息，包括品牌别名。

### 路径参数

| 参数           | 类型            | 描述    |
| ------------ | ------------- | ----- |
| `project_id` | string (UUID) | 项目 ID |

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

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}")
    ```
  </Tab>

  <Tab title="Node.js（服务端）">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}`, { headers });
    ```
  </Tab>
</Tabs>

### 响应

```json theme={null}
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Brand Project",
    "brand_name": "Acme Corp",
    "website_url": "https://acme.com",
    "location": "US",
    "language": "en",
    "brand_aliases": ["ACME", "Acme Corporation", "acme.com"],
    "created_at": "2026-01-15T10:30:00+00:00"
  }
}
```

### 响应字段

与列出项目相同，区别在于 `brand_aliases` 包含实际的别名：

| 字段              | 类型        | 可空 | 描述                  |
| --------------- | --------- | -- | ------------------- |
| `brand_aliases` | string\[] | No | 用于在 AI 回复中匹配的备选品牌名称 |

### 错误

| 状态    | 详情                                     | 原因               |
| ----- | -------------------------------------- | ---------------- |
| `403` | `Project does not belong to your team` | API 密钥所在团队不拥有此项目 |
| `404` | `Project not found`                    | 不存在此 ID 的项目      |