# 組織與成員
### 帳號註冊
POST `/api/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/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/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/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/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
{
"detail": string
}
```
**回應範例值**
```json
{
"detail": "回應字串"
}
```
***
### 帳號註冊
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
{
"detail": string
}
```
**回應範例值**
```json
{
"detail": "回應字串"
}
```
***
### 更換密碼
POST `/api/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/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/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/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/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/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/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/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/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/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/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.
"isTrial": boolean // 是否為試用期。判定邏輯：組織只有一個試用方案且目前有效
"expirationDays": integer // 已過期天數。正數=已過期天數，null=尚未到期或永久方案
"showTrialBanner": boolean // 控制前端是否顯示試用/免費方案橫幅
}
```
**回應範例值**
```json
{
"id": "5b01e0b9-0b0e-4079-8150-d12015576d2c",
"name": "My Organization",
"createdAt": "1748336288000",
"compactLogo": null,
"fullLogo": null,
"usageStatistics": {
"chatbotsCount": 0,
"canCreateChatbot": true,
"hasCreateChatbotLimit": true,
"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/`
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------- | --------------- | -- | -------------------- |
| 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.
"isTrial": boolean // 是否為試用期。判定邏輯：組織只有一個試用方案且目前有效
"expirationDays": integer // 已過期天數。正數=已過期天數，null=尚未到期或永久方案
"showTrialBanner": boolean // 控制前端是否顯示試用/免費方案橫幅
}
```
**回應範例值**
```json
{
"id": "5b01e0b9-0b0e-4079-8150-d12015576d2c",
"name": "My Organization",
"createdAt": "1748336288000",
"compactLogo": null,
"fullLogo": null,
"usageStatistics": {
"chatbotsCount": 0,
"canCreateChatbot": true,
"hasCreateChatbotLimit": true,
"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/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/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/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/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/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
}
```
***
### 新增成員至指定組織
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/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/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/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/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/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)
}
]
}
```
**回應範例值**
```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": "回應字串"
}
]
}
```
***
### 取得組織列表
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)
}
]
}
```
**回應範例值**
```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": "回應字串"
}
]
}
```
***
### 取得特定組織資訊
GET `/api/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/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/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/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/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.
"isTrial": boolean // 是否為試用期。判定邏輯：組織只有一個試用方案且目前有效
"expirationDays": integer // 已過期天數。正數=已過期天數，null=尚未到期或永久方案
"showTrialBanner": boolean // 控制前端是否顯示試用/免費方案橫幅
}
```
**回應範例值**
```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,
"isTrial": false,
"expirationDays": 456,
"showTrialBanner": false
}
```
***
### 取得特定組織資訊
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.
"isTrial": boolean // 是否為試用期。判定邏輯：組織只有一個試用方案且目前有效
"expirationDays": integer // 已過期天數。正數=已過期天數，null=尚未到期或永久方案
"showTrialBanner": boolean // 控制前端是否顯示試用/免費方案橫幅
}
```
**回應範例值**
```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,
"isTrial": false,
"expirationDays": 456,
"showTrialBanner": false
}
```
***
### 取得當前用戶詳細資訊
GET `/api/users/current/`
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/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/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/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/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) // 非必填
"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 // 取得使用者在當前組織中的資源建立權限。
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"avatar": "https://example.com/file.jpg",
"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": "回應範例描述"
}
}
```
***
### 取得當前用戶詳細資訊
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) // 非必填
"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 // 取得使用者在當前組織中的資源建立權限。
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"avatar": "https://example.com/file.jpg",
"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": "回應範例描述"
}
}
```
***
### 取得當前用戶權限
GET `/api/permissions/`
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/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/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/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/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/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/organizations/{organizationPk}/members/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `group` | ❌ | string | |
| `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 | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/members/?group=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=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/organizations/550e8400-e29b-41d4-a716-446655440000/members/?group=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=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/organizations/550e8400-e29b-41d4-a716-446655440000/members/?group=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=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/organizations/550e8400-e29b-41d4-a716-446655440000/members/?group=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=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
"isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）
使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效
優先使用 annotation 的結果（如果有的話）避免重複查詢
"permissions": [
object
]
"groups": [
object
]
"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": "回應字串",
"isOwner": false,
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"createdAt": "回應字串"
}
]
}
```
***
### 取得指定組織的成員列表
GET `/api/v1/organizations/{organizationPk}/members/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `group` | ❌ | string | |
| `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 | |
#### 程式碼範例
{% 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&page=1&pageSize=1&pagination=example&query=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&page=1&pageSize=1&pagination=example&query=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&page=1&pageSize=1&pagination=example&query=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&page=1&pageSize=1&pagination=example&query=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
"isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）
使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效
優先使用 annotation 的結果（如果有的話）避免重複查詢
"permissions": [
object
]
"groups": [
object
]
"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": "回應字串",
"isOwner": false,
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"createdAt": "回應字串"
}
]
}
```
***
### 取得特定成員詳細資訊
GET `/api/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/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/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/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/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
"isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）
使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效
優先使用 annotation 的結果（如果有的話）避免重複查詢
"permissions": [
object
]
"groups": [
object
]
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"email": "回應字串",
"isOwner": false,
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"createdAt": "回應字串"
}
```
***
### 取得特定成員詳細資訊
GET `/api/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/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/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/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/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/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/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/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/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/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/{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
"isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）
使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效
優先使用 annotation 的結果（如果有的話）避免重複查詢
"permissions": [
object
]
"groups": [
object
]
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"email": "回應字串",
"isOwner": false,
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"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
"回應字串"
```
***
### 更新組織資訊
PUT `/api/organizations/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ---------------------------------- |
| `id` | ✅ | string | A UUID string identifying this 組織. |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ----------------- | ------------ | -- | -------------------------------------- |
| name | string | 是 | |
| compactLogo | string (uri) | 否 | |
| fullLogo | string (uri) | 否 | |
| themePrimaryColor | string | 否 | UI 主題色，用於按鈕、連結等元素的顏色（HEX 格式，如 #0960bd） |
**請求結構範例**
```typescript
{
"name": string
"compactLogo"?: string (uri) // 非必填
"fullLogo"?: string (uri) // 非必填
"themePrimaryColor"?: string // UI 主題色，用於按鈕、連結等元素的顏色（HEX 格式，如 #0960bd） (非必填)
}
```
**請求範例值**
```json
{
"id": "5b01e0b9-0b0e-4079-8150-d12015576d2c",
"name": "Updated Org Name",
"created_at": "1748336288000",
"usage_statistics": {
"chatbots_count": 0,
"can_create_chatbot": true,
"has_create_chatbot_limit": true,
"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/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,
"can_create_chatbot": true,
"has_create_chatbot_limit": true,
"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,
"can_create_chatbot": true,
"has_create_chatbot_limit": true,
"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/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/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,
"can_create_chatbot": true,
"has_create_chatbot_limit": true,
"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/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,
"can_create_chatbot": true,
"has_create_chatbot_limit": true,
"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 // 聊天機器人數量 (非必填)
"can_create_chatbot"?: boolean // 是否可以建立聊天機器人 (非必填)
"has_create_chatbot_limit"?: boolean // 是否有建立聊天機器人的限制 (非必填)
"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,
"can_create_chatbot": true,
"has_create_chatbot_limit": true,
"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/organizations/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ---------------------------------- |
| `id` | ✅ | string | A UUID string identifying this 組織. |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ----------------- | ------------ | -- | -------------------------------------- |
| name | string | 是 | |
| compactLogo | string (uri) | 否 | |
| fullLogo | string (uri) | 否 | |
| themePrimaryColor | string | 否 | UI 主題色，用於按鈕、連結等元素的顏色（HEX 格式，如 #0960bd） |
**請求結構範例**
```typescript
{
"name": string
"compactLogo"?: string (uri) // 非必填
"fullLogo"?: string (uri) // 非必填
"themePrimaryColor"?: string // UI 主題色，用於按鈕、連結等元素的顏色（HEX 格式，如 #0960bd） (非必填)
}
```
**請求範例值**
```json
{
"id": "5b01e0b9-0b0e-4079-8150-d12015576d2c",
"name": "Updated Org Name",
"created_at": "1748336288000",
"usage_statistics": {
"chatbots_count": 0,
"can_create_chatbot": true,
"has_create_chatbot_limit": true,
"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,
"can_create_chatbot": true,
"has_create_chatbot_limit": true,
"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,
"can_create_chatbot": true,
"has_create_chatbot_limit": true,
"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,
"can_create_chatbot": true,
"has_create_chatbot_limit": true,
"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,
"can_create_chatbot": true,
"has_create_chatbot_limit": true,
"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 // 聊天機器人數量 (非必填)
"can_create_chatbot"?: boolean // 是否可以建立聊天機器人 (非必填)
"has_create_chatbot_limit"?: boolean // 是否有建立聊天機器人的限制 (非必填)
"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,
"can_create_chatbot": true,
"has_create_chatbot_limit": true,
"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/users/current/`
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| -------------- | -------------- | -- | -- |
| avatar | string (uri) | 否 | |
| name | string | 是 | |
| email | string (email) | 是 | |
| company | string | 否 | |
| invitationCode | string | 否 | |
**請求結構範例**
```typescript
{
"avatar"?: string (uri) // 非必填
"name": string
"email": string (email)
"company"?: string // 非必填
"invitationCode"?: string // 非必填
}
```
**請求範例值**
```json
{
"avatar": "https://example.com/file.jpg",
"name": "範例名稱",
"email": "user@example.com",
"company": "範例字串",
"invitationCode": "範例字串"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/users/current/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"avatar": "https://example.com/file.jpg",
"name": "範例名稱",
"email": "user@example.com",
"company": "範例字串",
"invitationCode": "範例字串"
}'
# 請確認在執行前替換 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 = {
"avatar": "https://example.com/file.jpg",
"name": "範例名稱",
"email": "user@example.com",
"company": "範例字串",
"invitationCode": "範例字串"
};
axios.put("https://api.maiagent.ai/api/users/current/", 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/users/current/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"avatar": "https://example.com/file.jpg",
"name": "範例名稱",
"email": "user@example.com",
"company": "範例字串",
"invitationCode": "範例字串"
}
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/users/current/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"avatar": "https://example.com/file.jpg",
"name": "範例名稱",
"email": "user@example.com",
"company": "範例字串",
"invitationCode": "範例字串"
}
]);
$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) // 非必填
"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 // 取得使用者在當前組織中的資源建立權限。
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"avatar": "https://example.com/file.jpg",
"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": "回應範例描述"
}
}
```
***
### 更新當前用戶詳細資訊
PUT `/api/v1/users/current/`
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| -------------- | -------------- | -- | -- |
| avatar | string (uri) | 否 | |
| name | string | 是 | |
| email | string (email) | 是 | |
| company | string | 否 | |
| invitationCode | string | 否 | |
**請求結構範例**
```typescript
{
"avatar"?: string (uri) // 非必填
"name": string
"email": string (email)
"company"?: string // 非必填
"invitationCode"?: string // 非必填
}
```
**請求範例值**
```json
{
"avatar": "https://example.com/file.jpg",
"name": "範例名稱",
"email": "user@example.com",
"company": "範例字串",
"invitationCode": "範例字串"
}
```
#### 程式碼範例
{% 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" \
-H "Content-Type: application/json" \
-d '{
"avatar": "https://example.com/file.jpg",
"name": "範例名稱",
"email": "user@example.com",
"company": "範例字串",
"invitationCode": "範例字串"
}'
# 請確認在執行前替換 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 = {
"avatar": "https://example.com/file.jpg",
"name": "範例名稱",
"email": "user@example.com",
"company": "範例字串",
"invitationCode": "範例字串"
};
axios.put("https://api.maiagent.ai/api/v1/users/current/", 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/users/current/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"avatar": "https://example.com/file.jpg",
"name": "範例名稱",
"email": "user@example.com",
"company": "範例字串",
"invitationCode": "範例字串"
}
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/users/current/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"avatar": "https://example.com/file.jpg",
"name": "範例名稱",
"email": "user@example.com",
"company": "範例字串",
"invitationCode": "範例字串"
}
]);
$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) // 非必填
"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 // 取得使用者在當前組織中的資源建立權限。
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"avatar": "https://example.com/file.jpg",
"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": "回應範例描述"
}
}
```
***
### 更新成員所屬角色
POST `/api/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/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/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/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/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
"isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）
使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效
優先使用 annotation 的結果（如果有的話）避免重複查詢
"permissions": [
object
]
"groups": [
object
]
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"email": "回應字串",
"isOwner": false,
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"createdAt": "回應字串"
}
```
**狀態碼: 400**
**回應結構範例**
```typescript
object
```
***
### 更新成員所屬角色
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
"isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）
使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效
優先使用 annotation 的結果（如果有的話）避免重複查詢
"permissions": [
object
]
"groups": [
object
]
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"email": "回應字串",
"isOwner": false,
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"createdAt": "回應字串"
}
```
**狀態碼: 400**
**回應結構範例**
```typescript
object
```
***
### 刪除指定成員
DELETE `/api/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/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/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/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/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 |
***
### 刪除指定成員
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/organizations/{organizationPk}/usage-statistics/members/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------------- | -- | ------- | -------------------------------------------------------------------------- |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `chatbot` | ❌ | string | 篩選特定 AI 助理 ID |
| `endDate` | ❌ | string | 結束日期，格式: YYYY-MM-DD |
| `includeTime` | ❌ | boolean | 是否返回只按時間聚合的時間序列資料，用於趨勢圖表（true/false）。設為 true 時，回應不包含實體資訊，只有時間欄位和統計數值，且不分頁。 |
| `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/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/members/?chatbot=example&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/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/members/?chatbot=example&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/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/members/?chatbot=example&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/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/members/?chatbot=example&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"?: [ // 非必填
{
"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/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------------- | -- | ------- | -------------------------------------------------------------------------- |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `chatbot` | ❌ | string | 篩選特定 AI 助理 ID |
| `endDate` | ❌ | string | 結束日期，格式: YYYY-MM-DD |
| `includeTime` | ❌ | boolean | 是否返回只按時間聚合的時間序列資料，用於趨勢圖表（true/false）。設為 true 時，回應不包含實體資訊，只有時間欄位和統計數值，且不分頁。 |
| `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&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/members/?chatbot=example&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/members/?chatbot=example&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/members/?chatbot=example&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"?: [ // 非必填
{
"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/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/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/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/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/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
}
```
***
### 取得成員使用統計摘要
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/organizations/{organizationPk}/usage-statistics/chatbots/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------------- | -- | ------- | -------------------------------------------------------------------------- |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `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/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/chatbots/?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/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/chatbots/?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/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/chatbots/?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/organizations/550e8400-e29b-41d4-a716-446655440000/usage-statistics/chatbots/?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/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------------- | -- | ------- | -------------------------------------------------------------------------- |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `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/?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/?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/?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/?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/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/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/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/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/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
}
```
***
### 取得 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: 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.maiagent.ai/api/api-reference/zu-zhi-he-cheng-yuan.md?ask=
```
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.