API 技術手冊，
標準化通訊與錯誤規格。

Documentation / API 技術文檔

星創網絡公開 API 規格與整合規範：包含健康檢查、諮詢意向提交、RFC 9457 錯誤模型、OpenAPI 3.1 規格與 IETF RateLimit 標頭。

基礎架構規範，
請求與協定要求。

Base Specs — 傳輸基礎

BASE URL

基礎伺服器網址

所有公開端點皆託管於全球邊緣網路，通訊強制採用 HTTPS / TLS 1.3：

https://www.star-chase.com

DATA FORMAT

資料編碼與內容協商

API 回應採用 application/json; charset=utf-8。支援 Accept: text/markdown 雙生檔案輸出。

OpenAPI 規格檔案 ↗

DEVELOPER PORTAL

開發者中心入口

快速入門、沙盒環境、免審核用量與 MCP 伺服器配置：

前往開發者中心 ↗

公開端點規格，
參數與範例。

API Reference — 呼叫規格

GET /api/v1/health 公開無須認證

檢查系統運行狀態、可用性與當前服務時間戳記。

回應範例 (Response 200 OK)

{
  "status": "healthy",
  "version": "2.0.0",
  "timestamp": "2026-08-24T08:35:00.000Z",
  "agent_readiness": "100%",
  "protocols": [
    "OpenAPI 3.1.0",
    "Streamable HTTP MCP",
    "RFC 9457 Problem Details",
    "IETF RateLimit"
  ]
}

POST /api/v1/lead 公開無須認證

提交商業諮詢需求。支援沙盒測試模式（提供 website 欄位即模擬成功，不發出真實通知）。

請求欄位 (Request Body JSON)

欄位	型別	必填	說明
`name`	string	是	聯絡人姓名
`phone`	string	是	聯絡電話或手機
`email`	string	否	電子郵件信箱
`service`	string	是	諮詢項目（如 `brand-consulting`）
`website`	string	否	沙盒標記：非空時進入模擬模式

成功回應 (Response 200 OK)

{
  "success": true,
  "message": "諮詢表單已成功送出，星創團隊將於 1-2 個工作天內與您聯繫。",
  "lead_id": "lead_01a032d290c27873"
}

POST /mcp 或 /api/mcp 公開無須認證

Model Context Protocol 2.0 端點。支援工具列出 (tools/list)、資源讀取 (resources/list) 與提示詞呼叫 (prompts/list)。

支援的 JSON-RPC 2.0 方法

initialize：初始化客戶端連線並回傳 Protocol 版本與伺服器資訊。
tools/list：取得星創工具清單（search_cases, get_service_info, get_company_info）。
tools/call：執行特定工具呼叫並回傳結構化資料。
ping：心跳檢測。

速率限制與標頭規範，
IETF 標準標頭。

Rate Limiting — 流控說明

所有 API 請求均會回傳標準 IETF 標頭，供客戶端與 AI Agent 即時監控配額並進行退避（Backoff）策略：

HTTP 標頭名稱	範例值	規範定義與說明
`RateLimit-Limit`	`120`	當前時間視窗（1 分鐘）內允許的最大請求總數。
`RateLimit-Remaining`	`118`	當前時間視窗內尚可使用的剩餘請求數。
`RateLimit-Reset`	`45`	距離當前時間視窗重置並恢復額度的剩餘秒數。
`Retry-After`	`60`	當觸發 HTTP 429（Too Many Requests）時，客戶端必須等待之冷卻秒數。

標準錯誤模型，
RFC 9457 Problem Details。

Error Handling — 錯誤結構

當發生驗證失敗或系統例外時，API 不會回傳空白內容，而是一律採用 Content-Type: application/problem+json 結構：

{
  "type": "https://www.star-chase.com/docs#errors",
  "title": "Invalid Request",
  "status": 400,
  "detail": "Missing required field: service",
  "instance": "/api/v1/lead",
  "code": "missing_required_field",
  "resolution": "Please provide 'name', 'phone', and 'service' in the JSON body.",
  "documentation_url": "https://www.star-chase.com/docs"
}

常見錯誤代碼對照表

代碼 (code)	HTTP 狀態	說明與建議排解
`missing_required_field`	400	缺少必填參數，請檢查 `name`, `phone`, `service`。
`invalid_email_format`	400	Email 格式不合法。
`rate_limit_exceeded`	429	超出每分鐘 120 次請求限制，請依 `Retry-After` 秒數重試。
`internal_server_error`	500	伺服器處理例外，請稍候重試或聯繫技術團隊。

OpenAPI 3.1.0 規格，
直接下載與程式庫生成。

OpenAPI Spec — 規格檔案

您可以直接下載官方 OpenAPI 規格檔案，並導入 Swagger UI、Postman、Insomnia 或透過 openapi-generator 生成多語言 SDK：

下載完整 openapi.json ↗ 返回開發者中心 ↗

Terminal BASH

# 取得 OpenAPI 規格並透過 jq 格式化檢視
curl -s https://www.star-chase.com/openapi.json | jq .info

# 使用 TypeScript 生成型別定義
npx openapi-typescript https://www.star-chase.com/openapi.json -o api-types.ts

API 技術手冊，標準化通訊與錯誤規格。

基礎架構規範，請求與協定要求。