> 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/api/api-reference/zu-zhi-he-cheng-yuan.md).
# 組織與成員
### 帳號註冊
POST `/api/v1/auth/registration/`
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------- | -------------------------- | -- | -- |
| email | string (email) | 是 | |
| password1 | string | 是 | |
| password2 | string | 是 | |
| name | string | 是 | |
| company | string | 是 | |
| referralCode | string | 否 | |
| authSource | object (含 2 個屬性: id, name) | 否 | |
| authSource.id | string (uuid) | 是 | |
**請求結構範例**
```typescript
{
"email": string (email)
"password1": string
"password2": string
"name": string
"company": string
"referralCode"?: string // 非必填
"authSource"?: // 非必填
{
"id": string (uuid)
}
}
```
**請求範例值**
```json
{
"email": "user@example.com",
"password1": "範例字串",
"password2": "範例字串",
"name": "範例名稱",
"company": "範例字串",
"referralCode": "範例字串",
"authSource": {
"id": "550e8400-e29b-41d4-a716-446655440000"
}
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/auth/registration/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password1": "範例字串",
"password2": "範例字串",
"name": "範例名稱",
"company": "範例字串",
"referralCode": "範例字串",
"authSource": {
"id": "550e8400-e29b-41d4-a716-446655440000"
}
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"email": "user@example.com",
"password1": "範例字串",
"password2": "範例字串",
"name": "範例名稱",
"company": "範例字串",
"referralCode": "範例字串",
"authSource": {
"id": "550e8400-e29b-41d4-a716-446655440000"
}
};
axios.post("https://api.maiagent.ai/api/v1/auth/registration/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/auth/registration/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"email": "user@example.com",
"password1": "範例字串",
"password2": "範例字串",
"name": "範例名稱",
"company": "範例字串",
"referralCode": "範例字串",
"authSource": {
"id": "550e8400-e29b-41d4-a716-446655440000"
}
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/auth/registration/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"email": "user@example.com",
"password1": "範例字串",
"password2": "範例字串",
"name": "範例名稱",
"company": "範例字串",
"referralCode": "範例字串",
"authSource": {
"id": "550e8400-e29b-41d4-a716-446655440000"
}
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"email": string (email)
"password1": string
"password2": string
"name": string
"company": string
"referralCode"?: string // 非必填
"authSource"?: // 非必填
{
"id": string (uuid)
"name": string
}
}
```
**回應範例值**
```json
{
"email": "response@example.com",
"password1": "回應字串",
"password2": "回應字串",
"name": "回應字串",
"company": "回應字串",
"referralCode": "回應字串",
"authSource": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
}
```
***
### 更換密碼
POST `/api/v1/auth/password/change/`
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------ | ------ | -- | -- |
| oldPassword | string | 是 | |
| newPassword1 | string | 是 | |
| newPassword2 | string | 是 | |
**請求結構範例**
```typescript
{
"oldPassword": string
"newPassword1": string
"newPassword2": string
}
```
**請求範例值**
```json
{
"oldPassword": "範例字串",
"newPassword1": "範例字串",
"newPassword2": "範例字串"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/auth/password/change/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"oldPassword": "範例字串",
"newPassword1": "範例字串",
"newPassword2": "範例字串"
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"oldPassword": "範例字串",
"newPassword1": "範例字串",
"newPassword2": "範例字串"
};
axios.post("https://api.maiagent.ai/api/v1/auth/password/change/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/auth/password/change/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"oldPassword": "範例字串",
"newPassword1": "範例字串",
"newPassword2": "範例字串"
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/auth/password/change/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"oldPassword": "範例字串",
"newPassword1": "範例字串",
"newPassword2": "範例字串"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"detail": string
}
```
**回應範例值**
```json
{
"detail": "回應字串"
}
```
***
### 建立新組織
POST `/api/v1/organizations/`
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------- | --------------- | -- | -------------------- |
| name | string | 是 | 組織名稱 |
| compact\_logo | string (binary) | 否 | 簡潔版 Logo（選填，僅企業方案可用） |
| full\_logo | string (binary) | 否 | 完整版 Logo（選填，僅企業方案可用） |
**請求結構範例**
```typescript
{
"name": string // 組織名稱
"compact_logo"?: string (binary) // 簡潔版 Logo（選填，僅企業方案可用） (非必填)
"full_logo"?: string (binary) // 完整版 Logo（選填，僅企業方案可用） (非必填)
}
```
**請求範例值**
```json
{
"name": "My Organization"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/organizations/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My Organization"
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": "My Organization"
};
axios.post("https://api.maiagent.ai/api/v1/organizations/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": "My Organization"
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/organizations/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"name": "My Organization"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"createdAt": string (timestamp)
"compactLogo"?: string (uri) // 非必填
"fullLogo"?: string (uri) // 非必填
"themePrimaryColor"?: string // UI 主題色，用於按鈕、連結等元素的顏色（HEX 格式，如 #0960bd） (非必填)
"usageStatistics": object
"organizationPlan": object
"creditWallet": object // Return credit wallet with ID only.
"maigptInboxId": string (uuid)
"canUseCustomElasticsearch": boolean // Allow this organization to configure custom Elasticsearch endpoints for knowledge bases.
"canUseVoiceAgent": boolean // Allow this organization to use voice agent features.
"canUseMeetingRecords": boolean // Allow this organization to use meeting records features.
"canUseCallCenter": boolean // Allow this organization to use call center features.
"canUseHookSystem": boolean // Manual override to grant this organization the hook system regardless of plan. Enterprise-plan organizations get access automatically without this flag. Layered under the global Config.hook_system_enabled switch: it must also be enabled.
"canUseAiGateway": boolean // Allow this organization to call the OpenAI-compatible `/api/v1/chat/completions` Gateway. Disabled by default; must be explicitly enabled by platform admin.
"canUseAgentTeams": boolean // Read-only projection of the platform-wide Agent Teams switch (Config.enable_agent_teams). Not a per-organization flag; member-level access is still governed by RBAC.
"canUseMaigptWorkspaceMount": boolean // Allow MaiGPT conversations to mount a file workspace as read-only context. Off by default for gradual rollout; independent of the other file library P2 switches.
"gatewayServiceFeePercent": string (decimal) // Markup applied on top of the token price when billing MaiAgent-managed models called through the AI Gateway (/v1/chat/completions and /v1/embeddings). Managed gateway markup only; the organization's own models (BYOK / self-hosted) are billed via the AI Gateway traffic fee percent instead.
"gatewayTrafficFeePercent": string (decimal) // Pass-through fee for calls that run on this organization's own AI Gateway models (BYOK / self-hosted): charged as the call's total tokens (input, output, and prompt-cache) x this percent in credits, with no LLM token pricing. Adjustable per organization; changes apply to new calls only.
"platformProcessingFeePercent": string (decimal) // Surcharge on every credit consumption of this organization, billed as a separate "Platform Processing Fee" line equal to the consumed credits x this percent. 0 disables the fee. Applies to new consumption only; the percent is shown read-only on the customer pricing page.
"platformProcessingFeeEnabled": boolean // Whether new consumption of this organization accrues the platform processing fee. The percent is exposed read-only as platform_processing_fee_percent.
"isTrial": boolean // 是否為試用期。判定邏輯：組織只有一個試用方案且目前有效
"expirationDays": integer // 已過期天數。正數=已過期天數，null=尚未到期或永久方案
"showTrialBanner": boolean // 控制前端是否顯示試用/免費方案橫幅
"noActivePlanDays": integer // Consecutive days without an active paid plan. null when cleanup is disabled.
"cleanupRemainingDays": integer // Days remaining before organization data is permanently deleted. null when cleanup is disabled, org has an active paid plan, or no_active_plan_days is 0.
"estimatedCleanupDate": string // ISO date when organization data will be permanently deleted. null when cleanup_remaining_days is null.
"approvalStatus": // Trial-eligibility review status. Only approved organizations can receive a trial plan when organization approval is enabled. Paid plan activation auto-approves the organization.
* `pending` - Pending Review
* `approved` - Approved
* `rejected` - Rejected
{
}
"companyName"?: string // Applicant-reported company name collected at organization creation for approval review. (非必填)
"taxId"?: // 可能有不同的類型 (非必填)
string // Applicant-reported business tax ID (8 digits, optional). Stored as-is; not verified. (非必填)
"contactPhone"?: string // Applicant-reported contact phone collected at organization creation for approval review. (非必填)
"applicationMetadata"?: object // Extra applicant-reported key-value fields collected at organization creation. Lets the frontend collect additional review fields without a schema migration; the core review fields (company name, tax ID, contact phone) stay as named columns. (非必填)
"invitationCode"?: string // 非必填
}
```
**回應範例值**
```json
{
"id": "5b01e0b9-0b0e-4079-8150-d12015576d2c",
"name": "My Organization",
"createdAt": "1748336288000",
"compactLogo": null,
"fullLogo": null,
"usageStatistics": {
"chatbotsCount": 0,
"countableChatbotsCount": 0,
"exemptChatbotsByMode": {},
"canCreateChatbot": true,
"createChatbotLimit": 1,
"currentMonthWordsCountTotal": 1000000,
"currentMonthUsedWordsCountTotal": 0,
"currentMonthUsedConversationsCountTotal": 0,
"availableUploadFilesSizeTotal": 104857600,
"usedUploadFileSizeTotal": 0
},
"organizationPlan": {
"id": "cac825e8-cb9b-4a16-b440-4ff6b2e73911",
"planName": "免費方案",
"planType": "free",
"expiredAt": null
},
"maigptInboxId": null,
"canUseCustomElasticsearch": false,
"isTrial": true,
"expirationDays": null
}
```
***
### 新增成員至指定組織
POST `/api/v1/organizations/{organizationPk}/members/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------ | -------------- | -- | -- |
| email | string (email) | 是 | |
| organization | string (uuid) | 否 | |
**請求結構範例**
```typescript
{
"email": string (email)
"organization"?: string (uuid) // 非必填
}
```
**請求範例值**
```json
{
"organization": "613c86f7-a45f-4e29-b255-29caff89de32",
"is_owner": false
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"organization": "613c86f7-a45f-4e29-b255-29caff89de32",
"is_owner": false
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"organization": "613c86f7-a45f-4e29-b255-29caff89de32",
"is_owner": false
};
axios.post("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"organization": "613c86f7-a45f-4e29-b255-29caff89de32",
"is_owner": false
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"organization": "613c86f7-a45f-4e29-b255-29caff89de32",
"is_owner": false
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"organization": string (uuid) // 組織 ID
"is_owner": boolean // 是否為組織擁有者
}
```
**回應範例值**
```json
{
"organization": "613c86f7-a45f-4e29-b255-29caff89de32",
"is_owner": false
}
```
***
### 取得組織列表
GET `/api/v1/organizations/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ------------ | -- | ------- | ---------------------------------------------- |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `pagination` | ❌ | string | 是否分頁 (true/false) |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/?page=1&pageSize=1&pagination=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/?page=1&pageSize=1&pagination=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/?page=1&pageSize=1&pagination=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/?page=1&pageSize=1&pagination=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"name": string
"createdAt": string (timestamp)
"memberCreatedAt": string (timestamp)
"approvalStatus": string
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"createdAt": "回應字串",
"memberCreatedAt": "回應字串",
"approvalStatus": "回應字串"
}
]
}
```
***
### 取得特定組織資訊
GET `/api/v1/organizations/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ---------------------------------- |
| `id` | ✅ | string | A UUID string identifying this 組織. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"createdAt": string (timestamp)
"compactLogo"?: string (uri) // 非必填
"fullLogo"?: string (uri) // 非必填
"themePrimaryColor"?: string // UI 主題色，用於按鈕、連結等元素的顏色（HEX 格式，如 #0960bd） (非必填)
"usageStatistics": object
"organizationPlan": object
"creditWallet": object // Return credit wallet with ID only.
"maigptInboxId": string (uuid)
"canUseCustomElasticsearch": boolean // Allow this organization to configure custom Elasticsearch endpoints for knowledge bases.
"canUseVoiceAgent": boolean // Allow this organization to use voice agent features.
"canUseMeetingRecords": boolean // Allow this organization to use meeting records features.
"canUseCallCenter": boolean // Allow this organization to use call center features.
"canUseHookSystem": boolean // Manual override to grant this organization the hook system regardless of plan. Enterprise-plan organizations get access automatically without this flag. Layered under the global Config.hook_system_enabled switch: it must also be enabled.
"canUseAiGateway": boolean // Allow this organization to call the OpenAI-compatible `/api/v1/chat/completions` Gateway. Disabled by default; must be explicitly enabled by platform admin.
"canUseAgentTeams": boolean // Read-only projection of the platform-wide Agent Teams switch (Config.enable_agent_teams). Not a per-organization flag; member-level access is still governed by RBAC.
"canUseMaigptWorkspaceMount": boolean // Allow MaiGPT conversations to mount a file workspace as read-only context. Off by default for gradual rollout; independent of the other file library P2 switches.
"gatewayServiceFeePercent": string (decimal) // Markup applied on top of the token price when billing MaiAgent-managed models called through the AI Gateway (/v1/chat/completions and /v1/embeddings). Managed gateway markup only; the organization's own models (BYOK / self-hosted) are billed via the AI Gateway traffic fee percent instead.
"gatewayTrafficFeePercent": string (decimal) // Pass-through fee for calls that run on this organization's own AI Gateway models (BYOK / self-hosted): charged as the call's total tokens (input, output, and prompt-cache) x this percent in credits, with no LLM token pricing. Adjustable per organization; changes apply to new calls only.
"platformProcessingFeePercent": string (decimal) // Surcharge on every credit consumption of this organization, billed as a separate "Platform Processing Fee" line equal to the consumed credits x this percent. 0 disables the fee. Applies to new consumption only; the percent is shown read-only on the customer pricing page.
"platformProcessingFeeEnabled": boolean // Whether new consumption of this organization accrues the platform processing fee. The percent is exposed read-only as platform_processing_fee_percent.
"isTrial": boolean // 是否為試用期。判定邏輯：組織只有一個試用方案且目前有效
"expirationDays": integer // 已過期天數。正數=已過期天數，null=尚未到期或永久方案
"showTrialBanner": boolean // 控制前端是否顯示試用/免費方案橫幅
"noActivePlanDays": integer // Consecutive days without an active paid plan. null when cleanup is disabled.
"cleanupRemainingDays": integer // Days remaining before organization data is permanently deleted. null when cleanup is disabled, org has an active paid plan, or no_active_plan_days is 0.
"estimatedCleanupDate": string // ISO date when organization data will be permanently deleted. null when cleanup_remaining_days is null.
"approvalStatus": // Trial-eligibility review status. Only approved organizations can receive a trial plan when organization approval is enabled. Paid plan activation auto-approves the organization.
* `pending` - Pending Review
* `approved` - Approved
* `rejected` - Rejected
{
}
"companyName"?: string // Applicant-reported company name collected at organization creation for approval review. (非必填)
"taxId"?: // 可能有不同的類型 (非必填)
string // Applicant-reported business tax ID (8 digits, optional). Stored as-is; not verified. (非必填)
"contactPhone"?: string // Applicant-reported contact phone collected at organization creation for approval review. (非必填)
"applicationMetadata"?: object // Extra applicant-reported key-value fields collected at organization creation. Lets the frontend collect additional review fields without a schema migration; the core review fields (company name, tax ID, contact phone) stay as named columns. (非必填)
"invitationCode"?: string // 非必填
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"createdAt": "回應字串",
"compactLogo": "https://example.com/file.jpg",
"fullLogo": "https://example.com/file.jpg",
"themePrimaryColor": "回應字串",
"usageStatistics": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"organizationPlan": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"creditWallet": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"maigptInboxId": "550e8400-e29b-41d4-a716-446655440000",
"canUseCustomElasticsearch": false,
"canUseVoiceAgent": false,
"canUseMeetingRecords": false,
"canUseCallCenter": false,
"canUseHookSystem": false,
"canUseAiGateway": false,
"canUseAgentTeams": false,
"canUseMaigptWorkspaceMount": false,
"gatewayServiceFeePercent": "回應字串",
"gatewayTrafficFeePercent": "回應字串",
"platformProcessingFeePercent": "回應字串",
"platformProcessingFeeEnabled": false,
"isTrial": false,
"expirationDays": 456,
"showTrialBanner": false,
"noActivePlanDays": 456,
"cleanupRemainingDays": 456,
"estimatedCleanupDate": "回應字串",
"approvalStatus": {},
"companyName": "回應字串",
"taxId": "回應字串",
"contactPhone": "回應字串",
"applicationMetadata": null,
"invitationCode": "回應字串"
}
```
***
### 取得當前用戶詳細資訊
GET `/api/v1/users/current/`
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/users/current/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/users/current/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/users/current/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/users/current/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"avatar"?: string (uri) // 非必填
"originalAvatar"?: string (uri) // 使用者上傳的頭貼原圖（長邊已限制在 2048px 內），每次編輯都從這張重裁，避免在裁切結果上再裁而累積失真。本功能上線前的舊資料為空，不回填 (非必填)
"avatarCropBox"?: object // 上次裁切框在原圖上的位置與大小（x/y/width/height，選填 rotate/scale_x/scale_y），座標基準為被保存的原圖 (非必填)
"name": string
"email": string (email)
"authSource":
{
"id": string (uuid)
"name": string
}
"company"?: string // 非必填
"invitationCode"?: // 可能有不同的類型 (非必填)
string // 非必填
"apiKeys": [ // 取得使用者在指定組織中的 API 金鑰列表。
流程：
1. 從 request 中取得當前組織實例
2. 如果沒有組織實例（通常發生在第三方 SSO 登入時），則透過使用者的認證來源
查找該認證來源的預設組織（is_auth_source_default_organization=True）
注意：
- 第三方 SSO 登入時 request 不會包含 organization_instance
- 需要透過 auth_source 和 is_auth_source_default_organization 標記來定位組織
object
]
"permissions": object // 取得使用者在當前組織中的權限（巢狀父子結構）。
"resourcePermissions": object // 取得使用者在當前組織中的資源建立權限。
"isOwner": boolean // 判斷使用者在當前組織中是否為 Owner。
"maigptCapabilities": object // 成員在 MaiGPT 的有效內建功能能力（角色權限解析結果），供前端 show/hide。
無 member context（未綁組織）時解析結果為全開，與 resolver「缺資料不鎖死」
一致；前端隱藏僅為體驗層，權威把關在回覆路徑的 gate。
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"avatar": "https://example.com/file.jpg",
"originalAvatar": "https://example.com/file.jpg",
"avatarCropBox": null,
"name": "回應字串",
"email": "response@example.com",
"authSource": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"company": "回應字串",
"invitationCode": "回應字串",
"apiKeys": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"permissions": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"resourcePermissions": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"isOwner": false,
"maigptCapabilities": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
}
```
***
### 取得當前用戶權限
GET `/api/v1/permissions/`
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/permissions/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/permissions/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/permissions/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/permissions/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
[
{
"id": string (uuid)
"name": string
"value": string
"description": string
"children": [
object
]
}
]
```
**回應範例值**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"value": "回應字串",
"description": "回應字串",
"children": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
]
}
]
```
***
### 取得指定組織的成員列表
GET `/api/v1/organizations/{organizationPk}/members/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `group` | ❌ | string | |
| `ids` | ❌ | string | |
| `inbox` | ❌ | string | |
| `isActive` | ❌ | boolean | |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `pagination` | ❌ | string | 是否分頁 (true/false) |
| `query` | ❌ | string | |
| `search` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/?group=550e8400-e29b-41d4-a716-446655440000&ids=example&inbox=550e8400-e29b-41d4-a716-446655440000&isActive=true&page=1&pageSize=1&pagination=example&query=example&search=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/?group=550e8400-e29b-41d4-a716-446655440000&ids=example&inbox=550e8400-e29b-41d4-a716-446655440000&isActive=true&page=1&pageSize=1&pagination=example&query=example&search=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/?group=550e8400-e29b-41d4-a716-446655440000&ids=example&inbox=550e8400-e29b-41d4-a716-446655440000&isActive=true&page=1&pageSize=1&pagination=example&query=example&search=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/?group=550e8400-e29b-41d4-a716-446655440000&ids=example&inbox=550e8400-e29b-41d4-a716-446655440000&isActive=true&page=1&pageSize=1&pagination=example&query=example&search=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"name": string
"email": string
"isActive": boolean
"isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）
使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效
優先使用 annotation 的結果（如果有的話）避免重複查詢
"permissions": [
object
]
"groups": [
object
]
"creditQuotaRequired"?: boolean // When True, member must have an active quota to consume credits (非必填)
"activeQuota": object // Return the most recent quota summary (active first), via prefetch to avoid N+1.
"metadata": object // Organization-scoped member attributes, injected into LLM system prompt
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"email": "回應字串",
"isActive": false,
"isOwner": false,
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"creditQuotaRequired": false,
"activeQuota": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"metadata": null,
"createdAt": "回應字串"
}
]
}
```
***
### 取得特定成員詳細資訊
GET `/api/v1/organizations/{organizationPk}/members/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this 成員. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"email": string
"isActive": boolean
"isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）
使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效
優先使用 annotation 的結果（如果有的話）避免重複查詢
"permissions": [
object
]
"groups": [
object
]
"creditQuotaRequired"?: boolean // When True, member must have an active quota to consume credits (非必填)
"activeQuota": object // Return the most recent quota summary (active first), via prefetch to avoid N+1.
"metadata": object // Organization-scoped member attributes, injected into LLM system prompt
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"email": "回應字串",
"isActive": false,
"isOwner": false,
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"creditQuotaRequired": false,
"activeQuota": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"metadata": null,
"createdAt": "回應字串"
}
```
***
### 取得特定成員詳細資訊
GET `/api/v1/organizations/{organizationPk}/members/current/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/current/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/current/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/current/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/current/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"email": string
"isActive": boolean
"isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）
使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效
優先使用 annotation 的結果（如果有的話）避免重複查詢
"permissions": [
object
]
"groups": [
object
]
"creditQuotaRequired"?: boolean // When True, member must have an active quota to consume credits (非必填)
"activeQuota": object // Return the most recent quota summary (active first), via prefetch to avoid N+1.
"metadata": object // Organization-scoped member attributes, injected into LLM system prompt
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"email": "回應字串",
"isActive": false,
"isOwner": false,
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"creditQuotaRequired": false,
"activeQuota": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"metadata": null,
"createdAt": "回應字串"
}
```
***
### 取得特定成員詳細資訊
GET `/api/v1/organizations/{organizationPk}/members/export/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/export/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/export/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/export/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/export/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
string (binary)
```
**回應範例值**
```json
"回應字串"
```
***
### 取得特定成員詳細資訊
GET `/api/v1/organizations/{organizationPk}/members/export-template/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/export-template/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/export-template/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/export-template/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/export-template/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
string (binary)
```
**回應範例值**
```json
"回應字串"
```
***
### 取得特定成員詳細資訊
GET `/api/v1/organizations/{organizationPk}/members/metadata-template/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/metadata-template/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/metadata-template/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/metadata-template/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/metadata-template/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"email": string
"isActive": boolean
"isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）
使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效
優先使用 annotation 的結果（如果有的話）避免重複查詢
"permissions": [
object
]
"groups": [
object
]
"creditQuotaRequired"?: boolean // When True, member must have an active quota to consume credits (非必填)
"activeQuota": object // Return the most recent quota summary (active first), via prefetch to avoid N+1.
"metadata": object // Organization-scoped member attributes, injected into LLM system prompt
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"email": "回應字串",
"isActive": false,
"isOwner": false,
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"creditQuotaRequired": false,
"activeQuota": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"metadata": null,
"createdAt": "回應字串"
}
```
***
### 更新組織資訊
PUT `/api/v1/organizations/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ---------------------------------- |
| `id` | ✅ | string | A UUID string identifying this 組織. |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------------- | ------------ | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | 是 | |
| compactLogo | string (uri) | 否 | |
| fullLogo | string (uri) | 否 | |
| themePrimaryColor | string | 否 | UI 主題色，用於按鈕、連結等元素的顏色（HEX 格式，如 #0960bd） |
| companyName | string | 否 | Applicant-reported company name collected at organization creation for approval review. |
| taxId | object | 否 | Applicant-reported business tax ID (8 digits, optional). Stored as-is; not verified. |
| contactPhone | string | 否 | Applicant-reported contact phone collected at organization creation for approval review. |
| applicationMetadata | object | 否 | Extra applicant-reported key-value fields collected at organization creation. Lets the frontend collect additional review fields without a schema migration; the core review fields (company name, tax I... |
| invitationCode | string | 否 | |
**請求結構範例**
```typescript
{
"name": string
"compactLogo"?: string (uri) // 非必填
"fullLogo"?: string (uri) // 非必填
"themePrimaryColor"?: string // UI 主題色，用於按鈕、連結等元素的顏色（HEX 格式，如 #0960bd） (非必填)
"companyName"?: string // Applicant-reported company name collected at organization creation for approval review. (非必填)
"taxId"?: // 可能有不同的類型 (非必填)
string // Applicant-reported business tax ID (8 digits, optional). Stored as-is; not verified. (非必填)
"contactPhone"?: string // Applicant-reported contact phone collected at organization creation for approval review. (非必填)
"applicationMetadata"?: object // Extra applicant-reported key-value fields collected at organization creation. Lets the frontend collect additional review fields without a schema migration; the core review fields (company name, tax ID, contact phone) stay as named columns. (非必填)
"invitationCode"?: string // 非必填
}
```
**請求範例值**
```json
{
"id": "5b01e0b9-0b0e-4079-8150-d12015576d2c",
"name": "Updated Org Name",
"created_at": "1748336288000",
"usage_statistics": {
"chatbots_count": 0,
"countable_chatbots_count": 0,
"exempt_chatbots_by_mode": {},
"allowed_chatbot_reply_modes": [],
"can_create_chatbot": true,
"create_chatbot_limit": 1,
"current_month_words_count_total": 1000000,
"current_month_used_words_count_total": 0,
"current_month_used_conversations_count_total": 0,
"available_upload_files_size_total": 104857600,
"used_upload_file_size_total": 0
},
"organization_plan": {
"id": "cac825e8-cb9b-4a16-b440-4ff6b2e73911",
"plan_name": "免費方案",
"expired_at": null
},
"is_trial": false,
"expiration_days": null
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"id": "5b01e0b9-0b0e-4079-8150-d12015576d2c",
"name": "Updated Org Name",
"created_at": "1748336288000",
"usage_statistics": {
"chatbots_count": 0,
"countable_chatbots_count": 0,
"exempt_chatbots_by_mode": {},
"allowed_chatbot_reply_modes": [],
"can_create_chatbot": true,
"create_chatbot_limit": 1,
"current_month_words_count_total": 1000000,
"current_month_used_words_count_total": 0,
"current_month_used_conversations_count_total": 0,
"available_upload_files_size_total": 104857600,
"used_upload_file_size_total": 0
},
"organization_plan": {
"id": "cac825e8-cb9b-4a16-b440-4ff6b2e73911",
"plan_name": "免費方案",
"expired_at": null
},
"is_trial": false,
"expiration_days": null
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"id": "5b01e0b9-0b0e-4079-8150-d12015576d2c",
"name": "Updated Org Name",
"created_at": "1748336288000",
"usage_statistics": {
"chatbots_count": 0,
"countable_chatbots_count": 0,
"exempt_chatbots_by_mode": {},
"allowed_chatbot_reply_modes": [],
"can_create_chatbot": true,
"create_chatbot_limit": 1,
"current_month_words_count_total": 1000000,
"current_month_used_words_count_total": 0,
"current_month_used_conversations_count_total": 0,
"available_upload_files_size_total": 104857600,
"used_upload_file_size_total": 0
},
"organization_plan": {
"id": "cac825e8-cb9b-4a16-b440-4ff6b2e73911",
"plan_name": "免費方案",
"expired_at": null
},
"is_trial": false,
"expiration_days": null
};
axios.put("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"id": "5b01e0b9-0b0e-4079-8150-d12015576d2c",
"name": "Updated Org Name",
"created_at": "1748336288000",
"usage_statistics": {
"chatbots_count": 0,
"countable_chatbots_count": 0,
"exempt_chatbots_by_mode": {},
"allowed_chatbot_reply_modes": [],
"can_create_chatbot": true,
"create_chatbot_limit": 1,
"current_month_words_count_total": 1000000,
"current_month_used_words_count_total": 0,
"current_month_used_conversations_count_total": 0,
"available_upload_files_size_total": 104857600,
"used_upload_file_size_total": 0
},
"organization_plan": {
"id": "cac825e8-cb9b-4a16-b440-4ff6b2e73911",
"plan_name": "免費方案",
"expired_at": null
},
"is_trial": false,
"expiration_days": null
}
response = requests.put(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"id": "5b01e0b9-0b0e-4079-8150-d12015576d2c",
"name": "Updated Org Name",
"created_at": "1748336288000",
"usage_statistics": {
"chatbots_count": 0,
"countable_chatbots_count": 0,
"exempt_chatbots_by_mode": {},
"allowed_chatbot_reply_modes": [],
"can_create_chatbot": true,
"create_chatbot_limit": 1,
"current_month_words_count_total": 1000000,
"current_month_used_words_count_total": 0,
"current_month_used_conversations_count_total": 0,
"available_upload_files_size_total": 104857600,
"used_upload_file_size_total": 0
},
"organization_plan": {
"id": "cac825e8-cb9b-4a16-b440-4ff6b2e73911",
"plan_name": "免費方案",
"expired_at": null
},
"is_trial": false,
"expiration_days": null
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid) // 組織 ID
"name": string // 組織名稱
"created_at": string (timestamp) // 建立時間戳記
"usage_statistics": { // 使用統計資訊
{
"chatbots_count"?: integer // 聊天機器人數量 (非必填)
"countable_chatbots_count"?: integer // 佔用建立額度的聊天機器人數量（模式不在方案白名單內的不計入） (非必填)
"exempt_chatbots_by_mode"?: object // 不佔額度的聊天機器人數量，依使其不計入的模式分組 (非必填)
"allowed_chatbot_reply_modes"?: [ // 方案允許建立的回覆模式白名單（空陣列表示不限制） (非必填)
string
]
"can_create_chatbot"?: boolean // 是否可以建立聊天機器人 (非必填)
"create_chatbot_limit"?: integer // 可建立的聊天機器人數量上限（-1 表示無上限、0 表示禁止建立） (非必填)
"current_month_words_count_total"?: integer // 本月總字數限制 (非必填)
"current_month_used_words_count_total"?: integer // 本月已使用字數 (非必填)
"current_month_used_conversations_count_total"?: integer // 本月已使用對話數 (非必填)
"available_upload_files_size_total"?: integer // 可上傳檔案總大小（位元組） (非必填)
"used_upload_file_size_total"?: integer // 已使用上傳檔案大小（位元組） (非必填)
}
}
"organization_plan": { // 組織方案資訊
{
"id"?: string (uuid) // 方案 ID (非必填)
"plan_name"?: string // 方案名稱 (非必填)
"expired_at"?: string (date-time) // 到期時間 (非必填)
}
}
"is_trial"?: boolean // 是否為試用期。判定邏輯：組織只有一個試用方案且目前有效 (非必填)
"expiration_days"?: integer // 已過期天數。正數=已過期天數，null=尚未到期或永久方案 (非必填)
}
```
**回應範例值**
```json
{
"id": "5b01e0b9-0b0e-4079-8150-d12015576d2c",
"name": "Updated Org Name",
"created_at": "1748336288000",
"usage_statistics": {
"chatbots_count": 0,
"countable_chatbots_count": 0,
"exempt_chatbots_by_mode": {},
"allowed_chatbot_reply_modes": [],
"can_create_chatbot": true,
"create_chatbot_limit": 1,
"current_month_words_count_total": 1000000,
"current_month_used_words_count_total": 0,
"current_month_used_conversations_count_total": 0,
"available_upload_files_size_total": 104857600,
"used_upload_file_size_total": 0
},
"organization_plan": {
"id": "cac825e8-cb9b-4a16-b440-4ff6b2e73911",
"plan_name": "免費方案",
"expired_at": null
},
"is_trial": false,
"expiration_days": null
}
```
***
### 更新當前用戶詳細資訊
PUT `/api/v1/users/current/`
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| -------------- | -------------- | -- | ------------------------------------------------------------------------- |
| avatar | string (uri) | 否 | |
| originalAvatar | string (uri) | 否 | 使用者上傳的頭貼原圖（長邊已限制在 2048px 內），每次編輯都從這張重裁，避免在裁切結果上再裁而累積失真。本功能上線前的舊資料為空，不回填 |
| avatarCropBox | object | 否 | 上次裁切框在原圖上的位置與大小（x/y/width/height，選填 rotate/scale\_x/scale\_y），座標基準為被保存的原圖 |
| name | string | 是 | |
| email | string (email) | 是 | |
| company | string | 否 | |
| invitationCode | object | 否 | |
**請求結構範例**
```typescript
{
"avatar"?: string (uri) // 非必填
"originalAvatar"?: string (uri) // 使用者上傳的頭貼原圖（長邊已限制在 2048px 內），每次編輯都從這張重裁，避免在裁切結果上再裁而累積失真。本功能上線前的舊資料為空，不回填 (非必填)
"avatarCropBox"?: object // 上次裁切框在原圖上的位置與大小（x/y/width/height，選填 rotate/scale_x/scale_y），座標基準為被保存的原圖 (非必填)
"name": string
"email": string (email)
"company"?: string // 非必填
"invitationCode"?: // 可能有不同的類型 (非必填)
string // 非必填
}
```
**請求範例值**
```json
{
"avatar": "https://example.com/file.jpg",
"originalAvatar": "https://example.com/file.jpg",
"avatarCropBox": null,
"name": "範例名稱",
"email": "user@example.com",
"company": "範例字串",
"invitationCode": null
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/users/current/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
const FormData = require('form-data');
// 建立FormData對象
const formData = new FormData();
// 添加表單欄位
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
...formData.getHeaders()
}
};
axios.put("https://api.maiagent.ai/api/v1/users/current/", formData, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/users/current/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
# 建立檔案和表單資料
files = {
'file': ('example.pdf', open('example.pdf', 'rb'), 'application/pdf')
}
response = requests.put(url, files=files, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/users/current/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
],
'multipart' => [
[
'name' => 'file',
'contents' => fopen('example.pdf', 'r'),
'filename' => 'example.pdf'
]
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"avatar"?: string (uri) // 非必填
"originalAvatar"?: string (uri) // 使用者上傳的頭貼原圖（長邊已限制在 2048px 內），每次編輯都從這張重裁，避免在裁切結果上再裁而累積失真。本功能上線前的舊資料為空，不回填 (非必填)
"avatarCropBox"?: object // 上次裁切框在原圖上的位置與大小（x/y/width/height，選填 rotate/scale_x/scale_y），座標基準為被保存的原圖 (非必填)
"name": string
"email": string (email)
"authSource":
{
"id": string (uuid)
"name": string
}
"company"?: string // 非必填
"invitationCode"?: // 可能有不同的類型 (非必填)
string // 非必填
"apiKeys": [ // 取得使用者在指定組織中的 API 金鑰列表。
流程：
1. 從 request 中取得當前組織實例
2. 如果沒有組織實例（通常發生在第三方 SSO 登入時），則透過使用者的認證來源
查找該認證來源的預設組織（is_auth_source_default_organization=True）
注意：
- 第三方 SSO 登入時 request 不會包含 organization_instance
- 需要透過 auth_source 和 is_auth_source_default_organization 標記來定位組織
object
]
"permissions": object // 取得使用者在當前組織中的權限（巢狀父子結構）。
"resourcePermissions": object // 取得使用者在當前組織中的資源建立權限。
"isOwner": boolean // 判斷使用者在當前組織中是否為 Owner。
"maigptCapabilities": object // 成員在 MaiGPT 的有效內建功能能力（角色權限解析結果），供前端 show/hide。
無 member context（未綁組織）時解析結果為全開，與 resolver「缺資料不鎖死」
一致；前端隱藏僅為體驗層，權威把關在回覆路徑的 gate。
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"avatar": "https://example.com/file.jpg",
"originalAvatar": "https://example.com/file.jpg",
"avatarCropBox": null,
"name": "回應字串",
"email": "response@example.com",
"authSource": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"company": "回應字串",
"invitationCode": "回應字串",
"apiKeys": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"permissions": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"resourcePermissions": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"isOwner": false,
"maigptCapabilities": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
}
```
***
### 更新成員所屬角色
POST `/api/v1/organizations/{organizationPk}/members/{id}/update-groups/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this 成員. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------ | -------------- | -- | -- |
| groups | array\[string] | 是 | |
**請求結構範例**
```typescript
{
"groups": [
string (uuid)
]
}
```
**請求範例值**
```json
{
"groups": [
"4e368ab4-c543-48a2-bbb8-f6f5a0bf6c61",
"5f479bc5-d654-59b3-ccc9-g7g6b1cg7d72"
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000/update-groups/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"groups": [
"4e368ab4-c543-48a2-bbb8-f6f5a0bf6c61",
"5f479bc5-d654-59b3-ccc9-g7g6b1cg7d72"
]
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"groups": [
"4e368ab4-c543-48a2-bbb8-f6f5a0bf6c61",
"5f479bc5-d654-59b3-ccc9-g7g6b1cg7d72"
]
};
axios.post("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000/update-groups/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000/update-groups/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"groups": [
"4e368ab4-c543-48a2-bbb8-f6f5a0bf6c61",
"5f479bc5-d654-59b3-ccc9-g7g6b1cg7d72"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000/update-groups/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"groups": [
"4e368ab4-c543-48a2-bbb8-f6f5a0bf6c61",
"5f479bc5-d654-59b3-ccc9-g7g6b1cg7d72"
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"email": string
"isActive": boolean
"isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）
使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效
優先使用 annotation 的結果（如果有的話）避免重複查詢
"permissions": [
object
]
"groups": [
object
]
"creditQuotaRequired"?: boolean // When True, member must have an active quota to consume credits (非必填)
"activeQuota": object // Return the most recent quota summary (active first), via prefetch to avoid N+1.
"metadata": object // Organization-scoped member attributes, injected into LLM system prompt
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"email": "回應字串",
"isActive": false,
"isOwner": false,
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"creditQuotaRequired": false,
"activeQuota": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"metadata": null,
"createdAt": "回應字串"
}
```
**狀態碼: 400**
**回應結構範例**
```typescript
object
```
***
### 刪除組織
DELETE `/api/v1/organizations/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ---------------------------------- |
| `id` | ✅ | string | A UUID string identifying this 組織. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 刪除指定成員
DELETE `/api/v1/organizations/{organizationPk}/members/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this 成員. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 取得成員使用統計
GET `/api/v1/organizations/{organizationPk}/usage-statistics/members/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------------- | -- | ------- | -------------------------------------------------------------------------- |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `chatbot` | ❌ | string | 篩選特定 AI 助理 ID |
| `chatbotId` | ❌ | string | |
| `endDate` | ❌ | string | 結束日期，格式: YYYY-MM-DD |
| `includeTime` | ❌ | boolean | 是否返回只按時間聚合的時間序列資料，用於趨勢圖表（true/false）。設為 true 時，回應不包含實體資訊，只有時間欄位和統計數值，且不分頁。 |
| `memberId` | ❌ | string | |
| `page` | ❌ | integer | 頁碼 |
| `pageSize` | ❌ | integer | 每頁筆數 |
| `search` | ❌ | string | 搜尋成員 ID、名稱或 Email |
| `sortBy` | ❌ | string | 排序欄位 |
| `sortOrder` | ❌ | string | 排序方式 (asc/desc) |
| `startDate` | ✅ | string | 開始日期，格式: YYYY-MM-DD |
| `timeGranularity` | ❌ | string | 時間粒度 (hour/day/month) |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/members/?chatbot=example&chatbotId=550e8400-e29b-41d4-a716-446655440000&endDate=example&includeTime=true&memberId=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&search=example&sortBy=conversations_count&sortOrder=asc&startDate=example&timeGranularity=day" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/members/?chatbot=example&chatbotId=550e8400-e29b-41d4-a716-446655440000&endDate=example&includeTime=true&memberId=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&search=example&sortBy=conversations_count&sortOrder=asc&startDate=example&timeGranularity=day", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/members/?chatbot=example&chatbotId=550e8400-e29b-41d4-a716-446655440000&endDate=example&includeTime=true&memberId=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&search=example&sortBy=conversations_count&sortOrder=asc&startDate=example&timeGranularity=day"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/members/?chatbot=example&chatbotId=550e8400-e29b-41d4-a716-446655440000&endDate=example&includeTime=true&memberId=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&search=example&sortBy=conversations_count&sortOrder=asc&startDate=example&timeGranularity=day", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"count"?: integer // 結果數量 (非必填)
"results"?: [ // 非必填
{
"member"?: { // 非必填
{
"id"?: string (uuid) // 成員 ID (非必填)
"name"?: string // 成員名稱 (非必填)
"email"?: string // 成員電子郵件 (非必填)
}
}
"datetime"?: string (date-time) // 時間戳（僅 include_time=true 且 time_granularity=hour 時出現） (非必填)
"period"?: string (date) // 日期（僅 include_time=true 且 time_granularity=day/month 時出現） (非必填)
"input_characters_count"?: integer // 輸入字元數 (非必填)
"output_characters_count"?: integer // 輸出字元數 (非必填)
"input_token_usage"?: integer // 輸入 Token 數 (非必填)
"output_token_usage"?: integer // 輸出 Token 數 (非必填)
"messages_count"?: integer // 訊息數 (非必填)
"conversations_count"?: integer // 對話數 (非必填)
"total_characters_count"?: integer // 總字元數 (非必填)
"total_token_usage"?: integer // 總 Token 數 (非必填)
}
]
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"count": 2,
"results": [
{
"member": {
"id": "3a245511-d5e0-4e06-9dc6-1106915b9a8a",
"name": "王小明",
"email": "wang@example.com"
},
"input_characters_count": 10000,
"output_characters_count": 15000,
"input_token_usage": 2500,
"output_token_usage": 3750,
"messages_count": 100,
"conversations_count": 50,
"total_characters_count": 25000,
"total_token_usage": 6250
}
]
}
]
}
```
***
### 取得成員使用統計摘要
GET `/api/v1/organizations/{organizationPk}/usage-statistics/members/summary/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------------- | -- | ------ | ------------------------------------ |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `endDate` | ❌ | string | 結束日期，格式: YYYY-MM-DD |
| `startDate` | ✅ | string | 開始日期，格式: YYYY-MM-DD |
| `timeGranularity` | ❌ | string | 時間粒度 (hour/day/month) |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/members/summary/?endDate=example&startDate=example&timeGranularity=day" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/members/summary/?endDate=example&startDate=example&timeGranularity=day", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/members/summary/?endDate=example&startDate=example&timeGranularity=day"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/members/summary/?endDate=example&startDate=example&timeGranularity=day", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"total_input_characters"?: integer // 總輸入字元數 (非必填)
"total_output_characters"?: integer // 總輸出字元數 (非必填)
"total_characters"?: integer // 總字元數 (非必填)
"total_input_tokens"?: integer // 總輸入 Token 數 (非必填)
"total_output_tokens"?: integer // 總輸出 Token 數 (非必填)
"total_tokens"?: integer // 總 Token 數 (非必填)
"total_messages"?: integer // 總訊息數 (非必填)
"total_conversations"?: integer // 總對話數 (非必填)
"total_members"?: integer // 總成員數 (非必填)
}
```
**回應範例值**
```json
{
"total_input_characters": 456,
"total_output_characters": 456,
"total_characters": 456,
"total_input_tokens": 456,
"total_output_tokens": 456,
"total_tokens": 456,
"total_messages": 456,
"total_conversations": 456,
"total_members": 456
}
```
***
### 取得 AI 助理使用統計
GET `/api/v1/organizations/{organizationPk}/usage-statistics/chatbots/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------------- | -- | ------- | -------------------------------------------------------------------------- |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `chatbotId` | ❌ | string | |
| `endDate` | ❌ | string | 結束日期，格式: YYYY-MM-DD |
| `includeTime` | ❌ | boolean | 是否返回只按時間聚合的時間序列資料，用於趨勢圖表（true/false）。設為 true 時，回應不包含實體資訊，只有時間欄位和統計數值，且不分頁。 |
| `page` | ❌ | integer | 頁碼 |
| `pageSize` | ❌ | integer | 每頁筆數 |
| `search` | ❌ | string | 搜尋 AI 助理 ID 或名稱 |
| `sortBy` | ❌ | string | 排序欄位 |
| `sortOrder` | ❌ | string | 排序方式 (asc/desc) |
| `startDate` | ✅ | string | 開始日期，格式: YYYY-MM-DD |
| `timeGranularity` | ❌ | string | 時間粒度 (hour/day/month) |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/chatbots/?chatbotId=550e8400-e29b-41d4-a716-446655440000&endDate=example&includeTime=true&page=1&pageSize=1&search=example&sortBy=conversations_count&sortOrder=asc&startDate=example&timeGranularity=day" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/chatbots/?chatbotId=550e8400-e29b-41d4-a716-446655440000&endDate=example&includeTime=true&page=1&pageSize=1&search=example&sortBy=conversations_count&sortOrder=asc&startDate=example&timeGranularity=day", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/chatbots/?chatbotId=550e8400-e29b-41d4-a716-446655440000&endDate=example&includeTime=true&page=1&pageSize=1&search=example&sortBy=conversations_count&sortOrder=asc&startDate=example&timeGranularity=day"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/chatbots/?chatbotId=550e8400-e29b-41d4-a716-446655440000&endDate=example&includeTime=true&page=1&pageSize=1&search=example&sortBy=conversations_count&sortOrder=asc&startDate=example&timeGranularity=day", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"count"?: integer // 結果數量 (非必填)
"results"?: [ // 非必填
{
"chatbot"?: { // 非必填
{
"id"?: string (uuid) // AI 助理 ID (非必填)
"name"?: string // AI 助理名稱 (非必填)
}
}
"datetime"?: string (date-time) // 時間戳（僅 include_time=true 且 time_granularity=hour 時出現） (非必填)
"period"?: string (date) // 日期（僅 include_time=true 且 time_granularity=day/month 時出現） (非必填)
"input_characters_count"?: integer // 輸入字元數 (非必填)
"output_characters_count"?: integer // 輸出字元數 (非必填)
"input_token_usage"?: integer // 輸入 Token 數 (非必填)
"output_token_usage"?: integer // 輸出 Token 數 (非必填)
"messages_count"?: integer // 訊息數 (非必填)
"conversations_count"?: integer // 對話數 (非必填)
"total_characters_count"?: integer // 總字元數 (非必填)
"total_token_usage"?: integer // 總 Token 數 (非必填)
}
]
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"count": 2,
"results": [
{
"chatbot": {
"id": "5b646600-f6e0-4f07-aec7-0207a26c0a9b",
"name": "客服助理"
},
"input_characters_count": 10000,
"output_characters_count": 15000,
"input_token_usage": 2500,
"output_token_usage": 3750,
"messages_count": 100,
"conversations_count": 50,
"total_characters_count": 25000,
"total_token_usage": 6250
}
]
}
]
}
```
***
### 取得 AI 助理使用統計摘要
GET `/api/v1/organizations/{organizationPk}/usage-statistics/chatbots/summary/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------------- | -- | ------ | ------------------------------------ |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `endDate` | ❌ | string | 結束日期，格式: YYYY-MM-DD |
| `startDate` | ✅ | string | 開始日期，格式: YYYY-MM-DD |
| `timeGranularity` | ❌ | string | 時間粒度 (hour/day/month) |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/chatbots/summary/?endDate=example&startDate=example&timeGranularity=day" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/chatbots/summary/?endDate=example&startDate=example&timeGranularity=day", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/chatbots/summary/?endDate=example&startDate=example&timeGranularity=day"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/chatbots/summary/?endDate=example&startDate=example&timeGranularity=day", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"total_input_characters"?: integer // 總輸入字元數 (非必填)
"total_output_characters"?: integer // 總輸出字元數 (非必填)
"total_characters"?: integer // 總字元數 (非必填)
"total_input_tokens"?: integer // 總輸入 Token 數 (非必填)
"total_output_tokens"?: integer // 總輸出 Token 數 (非必填)
"total_tokens"?: integer // 總 Token 數 (非必填)
"total_messages"?: integer // 總訊息數 (非必填)
"total_conversations"?: integer // 總對話數 (非必填)
"total_chatbots"?: integer // 總 AI 助理數 (非必填)
}
```
**回應範例值**
```json
{
"total_input_characters": 456,
"total_output_characters": 456,
"total_characters": 456,
"total_input_tokens": 456,
"total_output_tokens": 456,
"total_tokens": 456,
"total_messages": 456,
"total_conversations": 456,
"total_chatbots": 456
}
```
***
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.maiagent.ai/api/api-reference/zu-zhi-he-cheng-yuan.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.