# 組織與成員
### 帳號註冊
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
}
```
***