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

# 舊版 API 路徑遷移至 /v1

> 對話補全、會話、Webhook 與外撥電話遷移至 /v1 的操作指引

<Note>
  **狀態：已棄用** — 舊路徑仍可使用，但將於 **2026-07-11 停止運作**。請在此之前遷移到 `/v1` 路徑。
</Note>

## 為什麼要這麼做

我們的對外開發者 API 正在收斂到單一的 `/v1` 前綴底下。先前有數個對外端點仍散落在 `/project/:projectId/integration/*` 與 `/project/:projectId/webhooks/*`，與其餘 V1 API 分開。把它們搬進 `/v1`，能提供一致、有文件、以 Developer Key 認證的單一介面。

這次是**純新增（additive）**：新的 `/v1` 路徑已經上線，舊路徑在下架日前仍可使用。今天不會有任何東西壞掉。

## 時間表

| 階段  | 日期                      | 說明                                                                 |
| --- | ----------------------- | ------------------------------------------------------------------ |
| 公告  | 2026-06-06              | 新的 `/v1` 路徑上線。舊路徑仍可使用，但回應會帶 `Deprecation` 與 `Sunset`（HTTP-date）標頭。 |
| 棄用期 | 2026-06-06 → 2026-07-10 | 遷移期間。舊路徑仍可使用，我們會持續監控舊路徑流量。                                         |
| 下架  | **2026-07-11**          | 舊路徑停止接受請求。                                                         |
| 移除  | TBD（預計 2026-07-18）      | 移除舊路徑的程式碼。本頁面保留供參考。                                                |

若舊路徑流量尚未歸零，下架日期會往後延，不會提前。

## 變更內容

所有受影響的端點認證方式不變（Developer Key `dk_` 或 secret key，透過 `Authorization: Bearer` 傳遞）。只有**路徑**改變 — 請求與回應主體完全相同。

| 舊路徑                                                     | 新 `/v1` 路徑                                           |
| ------------------------------------------------------- | ---------------------------------------------------- |
| `POST /project/{id}/integration/api/chat/completions`   | `POST /v1/projects/{id}/chat/completions`            |
| `POST /project/{id}/integration/api/session`            | `POST /v1/projects/{id}/sessions`                    |
| `DELETE /project/{id}/integration/api/session`          | `DELETE /v1/projects/{id}/sessions`                  |
| `POST /project/{id}/integration/api/session/terminate`  | `POST /v1/projects/{id}/sessions/terminate`          |
| `GET /project/{id}/integration/api/session/{sessionId}` | `GET /v1/projects/{id}/sessions/{sessionId}`         |
| `POST /project/{id}/integration/api/session/search`     | `POST /v1/projects/{id}/sessions/search`             |
| `GET /project/{id}/session`                             | `GET /v1/projects/{id}/session-history`              |
| `GET /project/{id}/session/stats`                       | `GET /v1/projects/{id}/session-history/stats`        |
| `GET /project/{id}/session/{sessionId}`                 | `GET /v1/projects/{id}/session-history/{sessionId}`  |
| `POST /project/{id}/webhooks`                           | `POST /v1/projects/{id}/webhooks`                    |
| `POST /project/{id}/webhooks/check`                     | `POST /v1/projects/{id}/webhooks/check`              |
| `DELETE /project/{id}/webhooks/{subscriptionId}`        | `DELETE /v1/projects/{id}/webhooks/{subscriptionId}` |
| `POST /project/{id}/integration/phone/call/outbound`    | `POST /v1/calls/outbound`                            |

<Note>
  **`sessions` 與 `session-history` 的差別。** 這是 `/v1` 底下兩組不同的端點。`/v1/projects/{id}/sessions/*` 負責會話生命週期（建立、結束、終止、搜尋，以及 `GET /{sessionId}` 取得即時的 runtime 狀態）。`/v1/projects/{id}/session-history/*` 則是唯讀的歷史查詢（列表、統計，以及 `GET /{sessionId}` 取得含事件的完整對話歷史）。注意 `GET .../sessions/{sessionId}` 回傳的是 runtime 狀態，而 `GET .../session-history/{sessionId}` 回傳的是已記錄的歷史 —— 依需求選擇對應的端點。
</Note>

## 如何遷移

換掉路徑即可；認證憑證與請求主體維持不變。

舊（2026-07-11 後停止運作）：

```bash theme={null}
curl -X POST https://api.pathors.com/project/PROJECT_ID/integration/api/chat/completions \
  -H "Authorization: Bearer dk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello!"}]}'
```

新：

```bash theme={null}
curl -X POST https://api.pathors.com/v1/projects/PROJECT_ID/chat/completions \
  -H "Authorization: Bearer dk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello!"}]}'
```

外撥電話端點是唯一一個主體略有不同的例外 — `/v1/calls/outbound` 以 V1 的方式取得專案上下文。詳見[建立外撥電話](/zh-Hant/api-reference/v1/calls/create-outbound-call)。

## 邊界情況

**我在 2026-07-11 前就看到 `Deprecation` / `Sunset` 標頭。**
這是預期行為。該請求仍會成功。標頭代表你用的是舊路徑。2026-07-11 後同樣的呼叫會失敗。

**我的整合跑在我無法完全掌控的伺服器上（n8n、Zapier、自訂 webhook）。**
在整合的設定中更新 URL、儲存／重新部署，並送出一次測試請求。憑證與請求主體不變 — 只有路徑改變。

**我用的是 secret key，不是 Developer Key。**
Secret key 在新的 `/v1` 路徑上一樣可以使用，行為不變。

## 需要協助

* **Discord**：[#support](https://discord.gg/e8g86Hqae)
* **Email**：[support@pathors.com](mailto:support@pathors.com)