# 快速上手

這份快速指南帶你用一把 API key 發出第一個請求，並看懂回應。

{% hint style="success" %}
**預計時間：5 分鐘。** 你只需要一把 API key 與一個能發 HTTP 請求的工具（cURL、Postman 或任何語言的 HTTP client）。
{% endhint %}

## 步驟

{% stepper %}
{% step %}

#### 取得 API key

API key 由你方的管理員在[管理後台](/documentation/cao-zuo-zhi-nan/admin-console.md)建立。建立時系統會回傳一次性的明碼 key，格式類似：

```
ak_live_3f9a2c7b8e1d4a605c...
```

{% hint style="warning" %}
明碼 key **只會出現這一次**，請當場妥善保存。遺失只能撤銷後重建。
{% endhint %}
{% endstep %}

{% step %}

#### 確認連線

先打不需認證的健康檢查端點，確認網路通暢：

```bash
curl https://api.atlantis.example/healthz
# {"status":"ok"}
```

{% endstep %}

{% step %}

#### 發出第一個已認證的請求

把你的 key 放進 `X-API-Key` header。以「列出 webhook 訂閱」為例：

{% tabs %}
{% tab title="cURL" %}

```bash
curl https://api.atlantis.example/v1/webhooks \
  -H "X-API-Key: ak_live_YOUR_KEY"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

resp = requests.get(
    "https://api.atlantis.example/v1/webhooks",
    headers={"X-API-Key": "ak_live_YOUR_KEY"},
)
print(resp.json())
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const resp = await fetch("https://api.atlantis.example/v1/webhooks", {
  headers: { "X-API-Key": "ak_live_YOUR_KEY" },
});
console.log(await resp.json());
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

#### 看懂回應

成功的回應一律包在 `{ data, meta }` 信封內：

{% code title="response.json" %}

```json
{
  "data": [],
  "meta": {
    "request_id": "9b1c2d3e-4f5a-6789-..."
  }
}
```

{% endcode %}

同時，回應 header 會帶上：

| Header               | 意義                      |
| -------------------- | ----------------------- |
| `X-Request-Id`       | 本次請求的追蹤碼，客服／除錯時請提供      |
| `X-Credit-Cost`      | 本次扣除的 credit（成功且需計費時才有） |
| `X-Credit-Remaining` | 扣除後的剩餘 credit           |
| {% endstep %}        |                         |
| {% endstepper %}     |                         |

## 常見問題

<details>

<summary>我收到 401 unauthorized</summary>

確認 `X-API-Key` 有帶上、值正確，且該 key 尚未被撤銷或停用。詳見[認證與 API key](/documentation/kai-shi-shi-yong/authentication.md)。

</details>

<details>

<summary>我收到 402 insufficient_credit</summary>

該 key 的 credit 餘額不足以支付本次請求。請聯絡你方管理員[加值](/documentation/cao-zuo-zhi-nan/admin-console.md)，或參考 [Credit 計費](/documentation/he-xin-gai-nian/credit-billing.md)。

</details>

<details>

<summary>我收到 429 rate_limited</summary>

觸發限流。回應的 `Retry-After` header 會告訴你建議幾秒後重試。詳見[限流](/documentation/he-xin-gai-nian/rate-limiting.md)。

</details>

## 下一步

{% content-ref url="/pages/MFQ1oeKPnts4wocXInGo" %}
[認證與 API key](/documentation/kai-shi-shi-yong/authentication.md)
{% endcontent-ref %}

{% content-ref url="/pages/IIOYHLhxhH8x5X7Vxdx1" %}
[回應格式](/documentation/he-xin-gai-nian/response-format.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blockchainsecurity.asia/documentation/kai-shi-shi-yong/quickstart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.