組織與成員

帳號註冊

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)

請求結構範例

{
  "email": string (email)
  "password1": string
  "password2": string
  "name": string
  "company": string
  "referralCode"?: string // 非必填
  "authSource"?:  // 非必填
  {
    "id": string (uuid)
  }
}

請求範例值

{
  "email": "[email protected]",
  "password1": "範例字串",
  "password2": "範例字串",
  "name": "範例名稱",
  "company": "範例字串",
  "referralCode": "範例字串",
  "authSource": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

程式碼範例

# 呼叫 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": "[email protected]",
    "password1": "範例字串",
    "password2": "範例字串",
    "name": "範例名稱",
    "company": "範例字串",
    "referralCode": "範例字串",
    "authSource": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

回應內容

狀態碼: 201

回應結構範例

{
  "detail": string
}

回應範例值

{
  "detail": "回應字串"
}

更換密碼

POST /api/auth/password/change/

請求內容

請求參數

欄位
類型
必填
說明

oldPassword

string

newPassword1

string

newPassword2

string

請求結構範例

{
  "oldPassword": string
  "newPassword1": string
  "newPassword2": string
}

請求範例值

{
  "oldPassword": "範例字串",
  "newPassword1": "範例字串",
  "newPassword2": "範例字串"
}

程式碼範例

# 呼叫 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 並核對請求資料。

回應內容

狀態碼: 200

回應結構範例

{
  "detail": string
}

回應範例值

{
  "detail": "回應字串"
}

建立新組織

POST /api/organizations/

請求內容

請求參數

欄位
類型
必填
說明

name

string

compactLogo

string (uri)

fullLogo

string (uri)

請求結構範例

{
  "name": string
  "compactLogo"?: string (uri) // 非必填
  "fullLogo"?: string (uri) // 非必填
}

請求範例值

{
  "name": "範例名稱",
  "compactLogo": "https://example.com/file.jpg",
  "fullLogo": "https://example.com/file.jpg"
}

程式碼範例

# 呼叫 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": "範例名稱",
    "compactLogo": "https://example.com/file.jpg",
    "fullLogo": "https://example.com/file.jpg"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "name": string
  "createdAt": string (timestamp)
  "compactLogo"?: string (uri) // 非必填
  "fullLogo"?: string (uri) // 非必填
  "usageStatistics": object
  "organizationPlan": object
  "maigptInboxId": string (uuid)
  "canUseCustomElasticsearch": boolean // Allow this organization to configure custom Elasticsearch endpoints for knowledge bases.
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "createdAt": "回應字串",
  "compactLogo": "https://example.com/file.jpg",
  "fullLogo": "https://example.com/file.jpg",
  "usageStatistics": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "organizationPlan": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "maigptInboxId": "550e8400-e29b-41d4-a716-446655440000",
  "canUseCustomElasticsearch": false
}

新增成員至指定組織

POST /api/organizations/{organizationPk}/members/

參數

參數名稱
必填
類型
說明

organizationPk

string

A UUID string identifying this 組織 ID

請求內容

請求參數

欄位
類型
必填
說明

email

string (email)

organization

string (uuid)

請求結構範例

{
  "email": string (email)
  "organization"?: string (uuid) // 非必填
}

請求範例值

{
  "organization": "613c86f7-a45f-4e29-b255-29caff89de32",
  "is_owner": false
}

程式碼範例

# 呼叫 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 並核對請求資料。

回應內容

狀態碼: 201

回應結構範例

{
  "organization": string (uuid) // 組織 ID
  "is_owner": boolean // 是否為組織擁有者
}

回應範例值

{
  "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)

程式碼範例

# 呼叫 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 並核對請求資料。

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "name": string
      "createdAt": string (timestamp)
    }
  ]
}

回應範例值

{
  "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": "回應字串"
    }
  ]
}

取得特定組織資訊

GET /api/organizations/{id}/

參數

參數名稱
必填
類型
說明

id

string

A UUID string identifying this 組織.

程式碼範例

# 呼叫 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 並核對請求資料。

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string
  "createdAt": string (timestamp)
  "compactLogo"?: string (uri) // 非必填
  "fullLogo"?: string (uri) // 非必填
  "usageStatistics": object
  "organizationPlan": object
  "maigptInboxId": string (uuid)
  "canUseCustomElasticsearch": boolean // Allow this organization to configure custom Elasticsearch endpoints for knowledge bases.
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "createdAt": "回應字串",
  "compactLogo": "https://example.com/file.jpg",
  "fullLogo": "https://example.com/file.jpg",
  "usageStatistics": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "organizationPlan": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "maigptInboxId": "550e8400-e29b-41d4-a716-446655440000",
  "canUseCustomElasticsearch": false
}

取得當前用戶詳細資訊

GET /api/users/current/

程式碼範例

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/users/current/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

回應內容

狀態碼: 200

回應結構範例

{
  "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 // 取得使用者在當前組織中的權限(巢狀父子結構)。
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "avatar": "https://example.com/file.jpg",
  "name": "回應字串",
  "email": "[email protected]",
  "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": "回應範例描述"
  }
}

取得當前用戶權限

GET /api/permissions/

程式碼範例

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/permissions/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

回應內容

狀態碼: 200

回應結構範例

[
  {
    "id": string (uuid)
    "name": string
    "value": string
    "description"?: string // 非必填
    "children": [ // 取得子權限列表
      object
    ]
  }
]

回應範例值

[
  {
    "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

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

程式碼範例

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/members/?page=1&pageSize=1&pagination=example&query=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

回應內容

狀態碼: 200

回應結構範例

{
  "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)
    }
  ]
}

回應範例值

{
  "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

程式碼範例

# 呼叫 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 並核對請求資料。

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string
  "email": string
  "isOwner": boolean // 檢查成員是否為組織擁有者(透過 OWNER Group)

使用快取避免同一 request 內的重複查詢
快取生命週期:在 member instance 存在期間有效

優先使用 annotation 的結果(如果有的話)避免重複查詢
  "permissions": [
    object
  ]
  "groups": [
    object
  ]
  "createdAt": string (timestamp)
}

回應範例值

{
  "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

程式碼範例

# 呼叫 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 並核對請求資料。

回應內容

狀態碼: 200

回應結構範例

string (binary)

回應範例值

"回應字串"

取得特定成員詳細資訊

GET /api/organizations/{organizationPk}/members/export-template/

參數

參數名稱
必填
類型
說明

organizationPk

string

A UUID string identifying this 組織 ID

程式碼範例

# 呼叫 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 並核對請求資料。

回應內容

狀態碼: 200

回應結構範例

string (binary)

回應範例值

"回應字串"

更新組織資訊

PUT /api/organizations/{id}/

參數

參數名稱
必填
類型
說明

id

string

A UUID string identifying this 組織.

請求內容

請求參數

欄位
類型
必填
說明

name

string

compactLogo

string (uri)

fullLogo

string (uri)

請求結構範例

{
  "name": string
  "compactLogo"?: string (uri) // 非必填
  "fullLogo"?: string (uri) // 非必填
}

請求範例值

{
  "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
  }
}

程式碼範例

# 呼叫 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
    }
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

回應內容

狀態碼: 200

回應結構範例

{
  "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) // 到期時間 (非必填)
  }
  }
}

回應範例值

{
  "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
  }
}

更新當前用戶詳細資訊

PUT /api/users/current/

請求內容

請求參數

欄位
類型
必填
說明

avatar

string (uri)

name

string

email

string (email)

company

string

invitationCode

string

請求結構範例

{
  "avatar"?: string (uri) // 非必填
  "name": string
  "email": string (email)
  "company"?: string // 非必填
  "invitationCode"?: string // 非必填
}

請求範例值

{
  "avatar": "https://example.com/file.jpg",
  "name": "範例名稱",
  "email": "[email protected]",
  "company": "範例字串",
  "invitationCode": "範例字串"
}

程式碼範例

# 呼叫 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": "[email protected]",
    "company": "範例字串",
    "invitationCode": "範例字串"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

回應內容

狀態碼: 200

回應結構範例

{
  "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 // 取得使用者在當前組織中的權限(巢狀父子結構)。
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "avatar": "https://example.com/file.jpg",
  "name": "回應字串",
  "email": "[email protected]",
  "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": "回應範例描述"
  }
}

刪除指定成員

DELETE /api/organizations/{organizationPk}/members/{id}/

參數

參數名稱
必填
類型
說明

id

string

A UUID string identifying this 成員.

organizationPk

string

A UUID string identifying this 組織 ID

程式碼範例

# 呼叫 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 並核對請求資料。

回應內容

狀態碼
說明

204

No response body


Last updated

Was this helpful?