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

# 支持 API：创建并跟踪工单

> 通过 CLI 或支持 API 创建 LogBrew 支持工单。添加安全的诊断信息，跟踪工单状态，并补充后续上下文。

遇到需要后续跟进的情况时，创建支持工单。之后，人或 AI 智能体都可以跟踪工单，并补充所需的上下文。只有创建工单的账号和 LogBrew 支持团队可以查看工单。

<Warning>
  使用账号访问 Bearer 令牌，例如 `$LOGBREW_TOKEN`。不要使用项目接入密钥。填写标题、描述或诊断信息之前，先删除私密数据。自动隐藏敏感数据不能代替这次检查。
</Warning>

## 创建工单

在 CLI 中运行：

```bash theme={null}
logbrew support create --category docs_confusion \
  --title "First event is not visible" \
  --description "Steps: send one info event, then read logs in the same project. Expected: one row. Observed: no rows." \
  --project "<project_id>" --json
```

CLI 会把 `source` 设为 `cli`。`--diagnostics` 只添加二进制文件名、CLI 版本、操作系统和架构。运行 `logbrew support --help` 查看所有选项。

CLI 创建工单时不会发送重试键。如果结果不确定，先运行 `logbrew support list --json`，再决定是否重新运行命令。否则可能会创建第二个工单。

通过 API 创建时，发送 `POST /api/support/tickets`，并带上 `source`、`category`、`title` 和 `description`。为了能安全重试，为这份报告生成一次重试键，并放在 `Idempotency-Key` 请求头中发送。以下示例使用的是虚构的值：

```bash theme={null}
LOGBREW_SUPPORT_RETRY_KEY="$(uuidgen)"

curl -sS "https://api.logbrew.co/api/support/tickets" \
  -H "Authorization: Bearer ${LOGBREW_TOKEN:?Set an account access bearer}" \
  -H "Idempotency-Key: ${LOGBREW_SUPPORT_RETRY_KEY:?Create a retry key for this report}" \
  -H "Content-Type: application/json" \
  --data '{
    "source": "docs",
    "category": "docs_confusion",
    "title": "First event is not visible",
    "description": "Steps: send one info event, then read logs in the same project. Expected: one row. Observed: no rows.",
    "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
    "diagnostics": {
      "steps": 2,
      "expected": "one matching row",
      "observed": "no matching rows"
    }
  }'
```

重试键由 1 到 128 个可见 ASCII 字符组成，不含空格。重试时，用相同的键发送相同的请求体，响应会返回同一个工单。不同的报告使用新的键。超时并不能证明创建失败。`Idempotency-Key` 请求头是可选的。不带它时，重复的请求可能会再创建一个工单。

可选字段有 `project_id`、`environment`、`runtime`、`framework`、`sdk_package`、`sdk_version`、`release`、`trace_id`、`event_id` 和 `diagnostics`。如果情况与特定项目无关，省略 `project_id`。`project_id` 必须指向你账号中的一个活动项目。

| 字段 | 可接受的值 |
| - | - |
| `source` | `cli`、`sdk`、`website`、`docs`、`mobile` |
| `category` | `sdk_install_failure`、`ingest_failure`、`auth_failure`、`project_setup`、`dashboard_issue`、`docs_confusion`、`cli_issue`、`mobile_issue`、`billing_question`、`other` |
| `title` | LogBrew 去掉首尾空格后，长度为 1 到 160 个字符。 |
| `description` | LogBrew 去掉首尾空格后，长度为 1 到 4000 个字符。 |
| 其他文本字段 | 每个最多 256 个字符。 |

请求成功时返回 HTTP `200`：

```json theme={null}
{
  "ticket_id": "sup_11111111111141118111111111111111",
  "status": "open",
  "created_at": "2026-10-01T09:30:00Z",
  "next": "Support ticket created. LogBrew will review the attached diagnostics.",
  "next_action": {
    "code": "review_ticket",
    "target": "support_ticket"
  }
}
```

工单 ID 以 `sup_` 开头。`next` 是给人看的提示，`next_action` 用于程序控制。

要删除项目，使用项目设置或 `logbrew projects delete`。不要通过支持工单申请删除项目。

## 写一份有用的报告

* 每个工单只报告一件事。
* 选择最接近的 `category`。只有没有合适的类别时，才使用 `other`。
* `title` 写明一个症状和它出现的位置。
* `description` 先写步骤，再写预期结果和实际结果。
* 只有项目、版本、链路或事件 ID 指向同一个故障时，才添加它们。

使用以下 `diagnostics` 键：

| 键 | 内容 |
| - | - |
| `steps` | 复现步骤的数量。 |
| `expected` | 简短的预期结果。 |
| `observed` | 简短的实际结果。 |
| `command_name` | 命令和子命令名称，不带参数。 |
| `exit_code` | 进程退出码（数字）。 |
| `error_code` | 稳定的错误码。 |
| `error_summary` | 简短且已隐藏敏感信息的错误摘要。 |
| `retry_count` | 相同重试的次数。 |
| `last_delivery_status` | 最后一次投递尝试的 HTTP 状态，例如 `401`。 |

`diagnostics` 是一个 JSON 对象，隐藏敏感信息后最大 16 KB。如果某个键名表示凭据、会话或邮箱地址，LogBrew 会把它的值替换为 `[redacted]`。看起来像凭据、URL 或本地路径的文本也会被替换。LogBrew 还会缩短过长的字符串，并限制嵌套层数、键的数量和列表项数量。不要依赖这种自动隐藏。发送请求之前，先删除私密数据。

## <span id="track-the-ticket">跟踪工单</span>

| CLI 命令 | API 路由 | 结果 |
| - | - | - |
| `logbrew support list` | `GET /api/support/tickets` | 列出账号的工单。 |
| `logbrew support show <ticket_id>` | `GET /api/support/tickets/{ticket_id}` | 读取单个工单及其下一步建议。 |
| `logbrew support context <ticket_id>` | `GET /api/support/tickets/{ticket_id}/context` | 读取已添加到工单的上下文。 |
| `logbrew support reply <ticket_id>` | `POST /api/support/tickets/{ticket_id}/context` | 补充所需的上下文。 |
| `logbrew support close <ticket_id>` | `PATCH /api/support/tickets/{ticket_id}` | 设为 `closed`。 |
| `logbrew support reopen <ticket_id>` | `PATCH /api/support/tickets/{ticket_id}` | 设为 `open`。 |

列表接受 `project_id`、`status`、`source`、`category`、`release` 和 `limit`。`limit` 默认为 100，最大为 500。使用游标分页时，发送 `pagination=cursor`。请求后续页面时，重复相同的筛选条件，并发送 `next_cursor` 中的 `cursor_time` 和 `cursor_id`。游标 ID 是一个 `sup_` 工单 ID。`next_cursor` 为 `null` 时停止。CLI 对应的选项是 `--project`、`--status`、`--source`、`--category`、`--release`、`--limit`、`--pagination`、`--cursor-time` 和 `--cursor-id`。

状态值包括 `open`、`routed`、`in_progress`、`waiting_on_user`、`resolved` 和 `closed`。你只能设置 `open` 或 `closed`。重复的关闭或重新打开请求会成功返回，但不做任何更改，因此可以原样重试。根据返回的状态和 `next_action` 操作：

| 状态 | `next_action.code` | 下一步 |
| - | - | - |
| `open`、`routed`、`in_progress` | `await_owner_update` | 等待更新。稍后再次读取工单。 |
| `waiting_on_user` | `provide_context` | 发送所需的上下文。 |
| `resolved`、`closed` | `open_new_ticket_if_needed` | 如果同样的情况再次出现，创建新工单。 |

## 补充所需的上下文

工单要求提供上下文时再回复。这时工单的状态为 `waiting_on_user`，`next_action.code` 为 `provide_context`。

```bash theme={null}
logbrew support reply sup_11111111111141118111111111111111 \
  --context "The same project and time filters still return no logs." \
  --retry-key "<retry_key>" --json
```

API 请求体包含 `context` 和可选的 `diagnostics`。`context` 文本长度必须为 1 到 4000 个字符。不要在 `context` 中写入凭据、URL、主机名或本地路径。API 会以 `422` 拒绝这类文本。在 `Idempotency-Key` 请求头中发送重试键。上下文路由必须带这个请求头。键由 1 到 128 个可见 ASCII 字符组成，不含空格。每次回复使用新的键。只有重试同一条回复时才复用键。

工单状态为 `open`、`routed`、`in_progress` 或 `waiting_on_user` 时，API 接受上下文。每个工单状态只接受 1 条回复。回复后，等状态变化后再发送更多上下文。回复 `waiting_on_user` 状态的工单后，工单会变为 `open`。以返回的 `status` 为准，不要假定状态已经变化。

回复成功后返回 `ticket_id`、`context_id`、`status`、`created_at`、`next` 和 `next_action`。`context_id` 以 `ctx_` 开头。回应后续请求之前，先重新读取工单。

`GET /api/support/tickets/{ticket_id}/context` 返回最近的 20 条上下文记录，按从旧到新排列。每条记录包含 `context_id`、`context`、`diagnostics` 和 `created_at`。这个列表没有游标。

回复 `resolved` 或 `closed` 状态的工单会返回 `422` 和 `code: "validation_failed"`。只有用户想继续这个支持请求时，才重新打开工单。`next_action` 并不授予智能体更改账号状态的权限。

## 从错误中恢复

| HTTP 状态 | `code` | 恢复方法 |
| - | - | - |
| `401` | `unauthorized` | 发送有效的账号访问 Bearer 令牌。 |
| `404` | `not_found` | 列出账号的工单，使用返回的 `sup_` ID。如果是项目错误，检查 `project_id` 或省略它。 |
| `405` | `method_not_allowed` | 使用[跟踪工单](#track-the-ticket)表格中列出的方法。 |
| `409` | `idempotency_conflict` | 该重试键已用于另一个请求。重试原始请求，或读取工单后使用新的键。 |
| `422` | `validation_failed` | 修正错误中指出的字段。对于 PATCH，只发送 `status: "open"` 或 `status: "closed"`。 |
| `429` | `rate_limited` | 等待一段时间，然后重试。 |

错误响应包含 `error`、`code`、`next` 和 `next_action`。参见 [API 错误](/zh-Hans/reference/api-errors)。

## 确保报告安全

不要发送机密信息、令牌、授权请求头、接入密钥、原始日志、客户数据、本地路径、主机或无关的源代码。发送一份简短、已隐藏敏感信息的摘要。自助检查见[故障排除](/zh-Hans/guides/troubleshooting)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.