---
title: 'API 總覽'
description: 'Panguard AI 透過 Threat Cloud REST API 提供威脅情報服務。'
icon: 'code'
---

Panguard AI 提供 Threat Cloud API 做社群驅動的威脅情報交換。Community 不需要帳號、不需要登入 -- MIT 授權開源。生產級 F500 部署可選 [Pilot（$25K / 90 天）](https://panguard.ai/zh-TW/pricing)、[Enterprise（$150K-500K / 年）](https://panguard.ai/zh-TW/pricing)、或 [Sovereign（$5-20M / 國家）](https://panguard.ai/zh-TW/pricing),內含 Migrator Pro、五大框架合規 evidence、離網部署、SLA。

## API 服務

<CardGroup cols={1}>
  <Card title="Threat Cloud API" icon="cloud">
    **可自訂 port** -- IoC 管理、威脅 feed、攻擊活動追蹤、MITRE 熱力圖、地理查詢、稽核 log。
  </Card>
</CardGroup>

## Base URL

| 服務         | 預設 Base URL                                       | TLS  |
| ------------ | --------------------------------------------------- | ---- |
| Threat Cloud | `https://tc.panguard.ai` 或 `http://localhost:PORT` | 選配 |

## 認證

需要認證的 Threat Cloud endpoint 用 `Authorization` header 帶 **API key**。

```bash
curl -X GET https://tc.panguard.ai/api/iocs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

## 統一回應格式

所有 API endpoint 都回傳一致的 JSON 封套：

<Tabs>
  <Tab title="成功">
    ```json
    {
      "ok": true,
      "data": {
        "id": "agent-001",
        "hostname": "web-server-1"
      }
    }
    ```
  </Tab>
  <Tab title="錯誤">
    ```json
    {
      "ok": false,
      "error": "Agent not found"
    }
    ```
  </Tab>
</Tabs>

## Rate Limiting

API 有 rate limiting 防濫用。

| 服務         | 預設限制         | 範圍         |
| ------------ | ---------------- | ------------ |
| Threat Cloud | 依 endpoint 不同 | 每個 API key |

被限速時，API 回傳 `429` 加上 `Retry-After` header 告訴你什麼時候可以再打。

## 錯誤碼

| 狀態碼 | 意思                  | 說明                                     |
| ------ | --------------------- | ---------------------------------------- |
| `200`  | OK                    | 請求成功                                 |
| `201`  | Created               | 資源建立成功                             |
| `400`  | Bad Request           | request body 有問題或缺必填欄位          |
| `401`  | Unauthorized          | 沒帶或帶了無效的認證 token               |
| `403`  | Forbidden             | Token 有效但權限不夠                     |
| `404`  | Not Found             | 找不到你要的資源                         |
| `429`  | Too Many Requests     | 超過 rate limit，看 `Retry-After` header |
| `500`  | Internal Server Error | 非預期的伺服器錯誤，用 backoff 重試      |

## Content Type

除非特別說明，request 跟 response body 都用 `application/json`。Feed endpoint 可能回傳 `text/plain` 給 blocklist 格式。

## 分頁

回傳集合的 endpoint 支援分頁：

<ParamField query="page" type="number" default="1">
  頁碼（從 1 開始）。
</ParamField>

<ParamField query="limit" type="number" default="50">
  每頁幾筆。最大 200。
</ParamField>

分頁 response 含 metadata：

```json
{
  "ok": true,
  "data": [...],
  "pagination": {
    "total": 342,
    "page": 1,
    "limit": 50,
    "pages": 7
  }
}
```

## 下一步

<CardGroup cols={2}>
  <Card title="Threat Cloud API" icon="crosshairs" href="/api-reference/threat-cloud/ioc">
    查詢跟提交威脅情報。
  </Card>
  <Card title="設定" icon="gear" href="/configuration/environment-variables">
    設定 API port、token 跟相關 config。
  </Card>
</CardGroup>
