> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/api-integration/quickstart.md).

# 快速上手

開始呼叫 MaiAgent 平台 API：基本網址、取得 API 金鑰的兩種方式（成員自建、管理者代發）、金鑰的權限範圍，以及第一個請求範例。

本頁帶您完成呼叫平台 API 前的準備：確認網址、取得 API 金鑰、送出第一個請求。各端點的欄位與完整範例以 [API 文件](https://docs.maiagent.ai/api) 為準；認證、速率限制、錯誤格式等跨端點規則見 [API 共通規範](https://docs.maiagent.ai/api/preparation/conventions)。

## API 串接文件與範例程式碼 <a href="#examples" id="examples"></a>

{% embed url="<https://github.com/Playma-Co-Ltd/maiagent-api-examples/>" %}

## 基本 API 網址 <a href="#base-url" id="base-url"></a>

```
https://api.maiagent.ai/api/v1/
```

地端與私有雲部署請換成貴公司的平台網域。新的整合請一律使用 `/api/v1/` 前綴，說明見 [網址與版本前綴](https://docs.maiagent.ai/api/preparation/conventions#base-url)。

## 取得 API 金鑰 <a href="#get-api-key" id="get-api-key"></a>

API 金鑰有兩種取得方式，兩種金鑰的呼叫方式相同。

### 成員自建 <a href="#self-issued-key" id="self-issued-key"></a>

組織內的有效成員都可以在後台右上角頭像 → <mark style="color:blue;">帳號</mark> → <mark style="color:blue;">API 金鑰</mark> 為自己建立金鑰，不需要額外權限。金鑰建立在**目前切換到的組織**，完整金鑰只在建立當下顯示一次。操作步驟見使用者手冊的 [成員自行建立金鑰](https://docs.maiagent.ai/org/developer/api-keys#self-issued-keys)。

### 管理者代發 <a href="#admin-issued-key" id="admin-issued-key"></a>

具備「API Key 管理權限」的管理者，可以在 <mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">API Key 管理</mark> 替指定成員簽發金鑰，並設定到期時間、每分鐘請求數（RPM）、停用或撤銷。操作步驟見使用者手冊的 [建立 API Key](https://docs.maiagent.ai/org/developer/api-keys#create-api-key)。

## 金鑰的權限範圍 <a href="#key-scope" id="key-scope"></a>

金鑰綁定一位成員：呼叫時的組織與權限，就是這位成員在該組織的身分與角色權限，請求不需要另外帶組織 ID，也沒有依端點細分的權限範圍。成員被停用或移出組織後，金鑰立即失效。完整規則與整合用金鑰的建議見 [API 共通規範：認證](https://docs.maiagent.ai/api/preparation/conventions#authentication)。

## 送出第一個請求 <a href="#first-request" id="first-request"></a>

在 `Authorization` 標頭帶入金鑰，格式是 `Api-Key <金鑰>`（不是 `Bearer`）：

```
Authorization: Api-Key <您的 API 金鑰>
```

以列出 Agent 為例：

```bash
curl https://api.maiagent.ai/api/v1/chatbots/ \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

回應為分頁格式（`count`、`next`、`previous`、`results`），欄位一律是 camelCase，說明見 [分頁](https://docs.maiagent.ai/api/preparation/conventions#pagination) 與 [欄位格式](https://docs.maiagent.ai/api/preparation/conventions#field-format)。收到 `401` 時，請確認金鑰狀態與標頭格式，見 [錯誤回應](https://docs.maiagent.ai/api/preparation/conventions#errors)。

## 下一步 <a href="#next-steps" id="next-steps"></a>

* 端點與認證細節：[API 文件：API 認證方式](https://docs.maiagent.ai/api/preparation/authentication)
* 跨端點規則：[API 共通規範](https://docs.maiagent.ai/api/preparation/conventions)
* 建立對話、送出訊息與附件：[建立對話與訊息](https://docs.maiagent.ai/tech/api-integration/conversations-and-messages.md)
* 取得 Agent 回覆（串流或同步）：[對話與訊息回覆（串流／同步）](https://docs.maiagent.ai/tech/api-integration/dui-hua-yu-xun-xi-hui-fu-chuan-liu-tong-bu.md)
* 管理知識庫檔案與檢索：[使用知識庫—上傳、搜尋與管理](https://docs.maiagent.ai/tech/api-integration/knowledge-base-api.md)
* 把對話事件推送到您的系統：[Webhook](https://docs.maiagent.ai/tech/serve/webhook.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/api-integration/quickstart.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
