評估與測試集

評估與測試集端點對應後台 AgentOps 的「測試集」與「自動化測試」，讓您從自己的系統批次測試 Agent。完整流程是：

1. 建立測試集：用 POST /api/v1/dataset/ 建立空白測試集，或用 POST /api/v1/dataset/upload/ 上傳 CSV／Excel 一次建好。

2. 加入測試案例：單輪問答用 /api/v1/test-case/（逐筆建立、上傳檔案或從知識庫檔案生成），多輪對話情境用 /api/v1/multi-turn-test-case/。從知識庫檔案生成在背景執行，回應 202 與 jobId，再用 查詢測試案例生成任務進度 追蹤。

3. 執行評估：用 POST /api/v1/evaluations/evaluate/（單輪）或 POST /api/v1/evaluations/multi-turn-evaluate/（多輪）指定測試集與 Agent，回應 202 與 evaluationId。

4. 讀取結果與匯出：輪詢 GET /api/v1/evaluations/{id}/，status 變成 completed、partial_completed 或 failed 即結束；單輪的逐題結果在 details，多輪的逐對話結果在 multi-turn-results。已完成的單輪評估可以用 export 匯出 Excel 報表，再從 export-status 取得下載網址。

所需權限：API Key 以建立它的成員身分呼叫。/dataset/、/test-case/、/multi-turn-test-case/ 的列表與所有寫入操作需要角色具備「測試集權限」，/evaluations/ 的列表與所有寫入操作需要「自動化測試權限」（角色權限中的 AgentOps 權限；擁有者一律具備），權限不足回 403。擁有者以外的成員只看得到、也只能評估自己角色可使用的 Agent。

Credit：從知識庫檔案生成測試案例，依實際生成的題數扣計價項目 agentops_test_gen；執行評估在結束時依完成的測試案例數扣 agentops_test_run 與 agentops_deepeval，評分用的評估模型呼叫另依該模型的用量計費。送出生成或評估前，系統會先檢查組織 Credit 與額度，不足回 402。手動建立、上傳檔案與讀取結果不扣 Credit；各項單價見 列出計價項目。

功能與後台操作見使用者手冊測試集管理與自動評估與 Agent 監控。

列出測試集

GET /api/v1/dataset/

參數

參數名稱	必填	類型	說明
isActive	❌	boolean
ordering	❌	string	Which field to use when ordering the results.
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
query	❌	string
search	❌	string	A search term.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/dataset/?isActive=true&ordering=example&page=1&pageSize=1&query=example&search=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/dataset/?isActive=true&ordering=example&page=1&pageSize=1&query=example&search=example", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/dataset/?isActive=true&ordering=example&page=1&pageSize=1&query=example&search=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/dataset/?isActive=true&ordering=example&page=1&pageSize=1&query=example&search=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "name": string
      "description"?: string // 非必填
      "organization": 
      {
        "id": string (uuid)
        "name": string
      }
      "createdBy": 
      {
        "id": string (uuid)
        "name": string
      }
      "isActive"?: boolean // 非必填
      "singleTurnTestCaseCount": integer
      "multiTurnTestCaseCount": integer
      "createdAt": string (timestamp)
      "updatedAt": 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": "回應字串",
      "description": "回應字串",
      "organization": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "createdBy": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "isActive": false,
      "singleTurnTestCaseCount": 456,
      "multiTurnTestCaseCount": 456,
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ]
}

---

建立空白測試集

POST /api/v1/dataset/

測試集名稱在組織內不可重複，重複時回 400。

請求內容

請求參數

欄位	類型	必填	說明
name	string	是
description	string	否

請求結構範例

{
  "name": string
  "description"?: string // 非必填
}

請求範例值

{
  "name": "範例名稱",
  "description": "範例字串"
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/dataset/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "description": "範例字串"
  }'

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "範例名稱",
    "description": "範例字串"
  };

axios.post("https://api.maiagent.ai/api/v1/dataset/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/dataset/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "name": "範例名稱",
    "description": "範例字串"
}

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/dataset/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => '範例名稱',
            'description' => '範例字串'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "name": string
  "description"?: string // 非必填
  "organization": 
  {
    "id": string (uuid)
    "name": string
  }
  "createdBy": 
  {
    "id": string (uuid)
    "name": string
  }
  "isActive"?: boolean // 非必填
  "singleTurnTestCaseCount": integer
  "multiTurnTestCaseCount": integer
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "organization": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "isActive": false,
  "singleTurnTestCaseCount": 456,
  "multiTurnTestCaseCount": 456,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

上傳 CSV 或 Excel 建立測試集

POST /api/v1/dataset/upload/

以 multipart/form-data 上傳：file 與 name 必填，description 選填。檔案格式同 上傳 CSV 或 Excel 加入測試案例；測試集名稱在組織內不可重複。

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/dataset/upload/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -F "file=@example_file.pdf" \
  -F "name=範例字串" \
  -F "description=範例字串"

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

JavaScript

const axios = require('axios');
const FormData = require('form-data');

// 建立FormData對象
const formData = new FormData();
// 請用實際檔案替換
formData.append('file', /* 實際檔案物件 */, 'example_file.pdf');
formData.append('name', '範例字串');
formData.append('description', '範例字串');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    ...formData.getHeaders()
  }
};

axios.post("https://api.maiagent.ai/api/v1/dataset/upload/", formData, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/dataset/upload/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

# 建立檔案和表單資料
files = {
    'file': ('example_file.pdf', open('example_file.pdf', 'rb'), 'application/pdf'),
    'name': (None, '範例字串'),
    'description': (None, '範例字串')
}

response = requests.post(url, files=files, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/dataset/upload/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ],
        'multipart' => [
            [
                'name' => 'file',
                'contents' => fopen('example_file.pdf', 'r'),
                'filename' => 'example_file.pdf'
            ],
            [
                'name' => 'name',
                'contents' => '範例字串'
            ],
            [
                'name' => 'description',
                'contents' => '範例字串'
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "name": string
  "description"?: string // 非必填
  "organization": 
  {
    "id": string (uuid)
    "name": string
  }
  "createdBy": 
  {
    "id": string (uuid)
    "name": string
  }
  "isActive"?: boolean // 非必填
  "singleTurnTestCaseCount": integer
  "multiTurnTestCaseCount": integer
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "organization": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "isActive": false,
  "singleTurnTestCaseCount": 456,
  "multiTurnTestCaseCount": 456,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

從知識庫檔案生成測試集

POST /api/v1/dataset/generate-from-file/

以單一知識庫檔案（knowledgeBaseFileId）建立新測試集並生成單輪測試案例，numTestCases 為 1～50（預設 10）。生成在背景執行，實際回應是 202 與 taskId，不含測試集 ID，也沒有進度可查；完成後新測試集會出現在列表中。需要追蹤進度時，請先建立空白測試集，再用 從知識庫檔案生成單輪測試案例。Credit：送出前檢查組織 Credit，不足回 402；依實際生成的題數扣 agentops_test_gen。

請求內容

請求參數

欄位	類型	必填	說明
name	string	是
description	string	否
chatbotFileId	string (uuid)	否
knowledgeBaseFileId	string (uuid)	否
numTestCases	integer	否

請求結構範例

{
  "name": string
  "description"?: string // 非必填
  "chatbotFileId"?: string (uuid) // 非必填
  "knowledgeBaseFileId"?: string (uuid) // 非必填
  "numTestCases"?: integer // 非必填
}

請求範例值

{
  "name": "範例名稱",
  "description": "範例字串",
  "chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
  "knowledgeBaseFileId": "550e8400-e29b-41d4-a716-446655440000",
  "numTestCases": 123
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/dataset/generate-from-file/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "description": "範例字串",
    "chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
    "knowledgeBaseFileId": "550e8400-e29b-41d4-a716-446655440000",
    "numTestCases": 123
  }'

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "範例名稱",
    "description": "範例字串",
    "chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
    "knowledgeBaseFileId": "550e8400-e29b-41d4-a716-446655440000",
    "numTestCases": 123
  };

axios.post("https://api.maiagent.ai/api/v1/dataset/generate-from-file/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/dataset/generate-from-file/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "name": "範例名稱",
    "description": "範例字串",
    "chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
    "knowledgeBaseFileId": "550e8400-e29b-41d4-a716-446655440000",
    "numTestCases": 123
}

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/dataset/generate-from-file/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => '範例名稱',
            'description' => '範例字串',
            'chatbotFileId' => '550e8400-e29b-41d4-a716-446655440000',
            'knowledgeBaseFileId' => '550e8400-e29b-41d4-a716-446655440000',
            'numTestCases' => 123
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "name": string
  "description"?: string // 非必填
  "organization": 
  {
    "id": string (uuid)
    "name": string
  }
  "createdBy": 
  {
    "id": string (uuid)
    "name": string
  }
  "isActive"?: boolean // 非必填
  "singleTurnTestCaseCount": integer
  "multiTurnTestCaseCount": integer
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "organization": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "isActive": false,
  "singleTurnTestCaseCount": 456,
  "multiTurnTestCaseCount": 456,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

列出可生成測試案例的知識庫檔案

GET /api/v1/dataset/knowledge-base-files/

依知識庫分組，只列出處理完成、類型為 txt、docx、pdf、md、markdown、mdx 的檔案。pageSize 是每個知識庫最多回傳的檔案數（預設 5，上限 100），search 依檔名篩選。

參數

參數名稱	必填	類型	說明
pageSize	❌	integer	Number of files per knowledge base (default: 5, max: 100)
search	❌	string	Filter files by filename

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/dataset/knowledge-base-files/?pageSize=1&search=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/dataset/knowledge-base-files/?pageSize=1&search=example", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/dataset/knowledge-base-files/?pageSize=1&search=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/dataset/knowledge-base-files/?pageSize=1&search=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

object

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應範例名稱",
  "description": "回應範例描述"
}

---

取得特定測試集

GET /api/v1/dataset/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Dataset.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/dataset/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);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/dataset/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)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/dataset/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();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string
  "description"?: string // 非必填
  "organization": 
  {
    "id": string (uuid)
    "name": string
  }
  "createdBy": 
  {
    "id": string (uuid)
    "name": string
  }
  "isActive"?: boolean // 非必填
  "singleTurnTestCaseCount": integer
  "multiTurnTestCaseCount": integer
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "organization": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "isActive": false,
  "singleTurnTestCaseCount": 456,
  "multiTurnTestCaseCount": 456,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

取得測試集與單輪測試案例

GET /api/v1/dataset/{id}/details/

回應在測試集欄位之外另含 testCases 陣列，只包含單輪測試案例；多輪測試案例請用 GET /api/v1/multi-turn-test-case/?datasetId={id}。

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Dataset.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/details/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/details/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/details/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/details/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string
  "description"?: string // 非必填
  "organization": 
  {
    "id": string (uuid)
    "name": string
  }
  "createdBy": 
  {
    "id": string (uuid)
    "name": string
  }
  "isActive"?: boolean // 非必填
  "singleTurnTestCaseCount": integer
  "multiTurnTestCaseCount": integer
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "organization": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "isActive": false,
  "singleTurnTestCaseCount": 456,
  "multiTurnTestCaseCount": 456,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

更新測試集

PUT /api/v1/dataset/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Dataset.

請求內容

請求參數

欄位	類型	必填	說明
name	string	是
description	string	否
isActive	boolean	否

請求結構範例

{
  "name": string
  "description"?: string // 非必填
  "isActive"?: boolean // 非必填
}

請求範例值

{
  "name": "範例名稱",
  "description": "範例字串",
  "isActive": true
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "description": "範例字串",
    "isActive": true
  }'

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "範例名稱",
    "description": "範例字串",
    "isActive": true
  };

axios.put("https://api.maiagent.ai/api/v1/dataset/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);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "name": "範例名稱",
    "description": "範例字串",
    "isActive": True
}

response = requests.put(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->put("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => '範例名稱',
            'description' => '範例字串',
            'isActive' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string
  "description"?: string // 非必填
  "organization": 
  {
    "id": string (uuid)
    "name": string
  }
  "createdBy": 
  {
    "id": string (uuid)
    "name": string
  }
  "isActive"?: boolean // 非必填
  "singleTurnTestCaseCount": integer
  "multiTurnTestCaseCount": integer
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "organization": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "isActive": false,
  "singleTurnTestCaseCount": 456,
  "multiTurnTestCaseCount": 456,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

部分更新測試集

PATCH /api/v1/dataset/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Dataset.

請求內容

請求參數

欄位	類型	必填	說明
name	string	否
description	string	否
isActive	boolean	否

請求結構範例

{
  "name"?: string // 非必填
  "description"?: string // 非必填
  "isActive"?: boolean // 非必填
}

請求範例值

{
  "name": "範例名稱",
  "description": "範例字串",
  "isActive": true
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "description": "範例字串",
    "isActive": true
  }'

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "範例名稱",
    "description": "範例字串",
    "isActive": true
  };

axios.patch("https://api.maiagent.ai/api/v1/dataset/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);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "name": "範例名稱",
    "description": "範例字串",
    "isActive": True
}

response = requests.patch(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => '範例名稱',
            'description' => '範例字串',
            'isActive' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string
  "description"?: string // 非必填
  "organization": 
  {
    "id": string (uuid)
    "name": string
  }
  "createdBy": 
  {
    "id": string (uuid)
    "name": string
  }
  "isActive"?: boolean // 非必填
  "singleTurnTestCaseCount": integer
  "multiTurnTestCaseCount": integer
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "organization": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "isActive": false,
  "singleTurnTestCaseCount": 456,
  "multiTurnTestCaseCount": 456,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

刪除測試集

DELETE /api/v1/dataset/{id}/

刪除後無法復原，會一併刪除測試集內的所有測試案例，以及用這個測試集執行過的評估與結果。

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Dataset.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

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/dataset/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);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/dataset/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)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->delete("https://api.maiagent.ai/api/v1/dataset/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();
}
?>

回應內容

狀態碼	說明
204	No response body

---

列出單輪測試案例

GET /api/v1/test-case/

用 datasetId 篩選單一測試集，也可依 status、creationMethod（manual、file、generate）篩選。

參數

參數名稱	必填	類型	說明
creationMethod	❌	string	`manual`: Manual ; `file`: File import ; `generate`: Generated;
datasetId	❌	string
ordering	❌	string	Which field to use when ordering the results.
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
query	❌	string
search	❌	string	A search term.
status	❌	string	`active`: Active ; `inactive`: Inactive ; `pending`: Pending Review;

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/test-case/?creationMethod=file&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=active" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/test-case/?creationMethod=file&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=active", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/test-case/?creationMethod=file&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=active"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/test-case/?creationMethod=file&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=active", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "dataset": 
      {
        "id": string (uuid)
        "name": string
      }
      "question": string
      "groundTruth"?: string // 非必填
      "status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
      "creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (非必填)
      "sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (非必填)
      "flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
      "createdAt": string (timestamp)
      "updatedAt": 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",
      "dataset": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "question": "回應字串",
      "groundTruth": "回應字串",
      "status": "active",
      "creationMethod": "manual",
      "sourceFile": "回應字串",
      "flaky": false,
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ]
}

---

建立單輪測試案例

POST /api/v1/test-case/

datasetId、question、groundTruth 必填。status 預設 active；評估只會執行 active 的測試案例。

請求內容

請求參數

欄位	類型	必填	說明
datasetId	string (uuid)	是
question	string	是
groundTruth	string	是
status	string	否
flaky	boolean	否

請求結構範例

{
  "datasetId": string (uuid)
  "question": string
  "groundTruth": string
  "status"?: string // 非必填
  "flaky"?: boolean // 非必填
}

請求範例值

{
  "datasetId": "550e8400-e29b-41d4-a716-446655440000",
  "question": "範例字串",
  "groundTruth": "範例字串",
  "status": "範例字串",
  "flaky": true
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/test-case/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datasetId": "550e8400-e29b-41d4-a716-446655440000",
    "question": "範例字串",
    "groundTruth": "範例字串",
    "status": "範例字串",
    "flaky": true
  }'

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "datasetId": "550e8400-e29b-41d4-a716-446655440000",
    "question": "範例字串",
    "groundTruth": "範例字串",
    "status": "範例字串",
    "flaky": true
  };

axios.post("https://api.maiagent.ai/api/v1/test-case/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/test-case/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "datasetId": "550e8400-e29b-41d4-a716-446655440000",
    "question": "範例字串",
    "groundTruth": "範例字串",
    "status": "範例字串",
    "flaky": True
}

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/test-case/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'datasetId' => '550e8400-e29b-41d4-a716-446655440000',
            'question' => '範例字串',
            'groundTruth' => '範例字串',
            'status' => '範例字串',
            'flaky' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "dataset": 
  {
    "id": string (uuid)
    "name": string
  }
  "question": string
  "groundTruth"?: string // 非必填
  "status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
  "creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (非必填)
  "sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (非必填)
  "flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "dataset": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "question": "回應字串",
  "groundTruth": "回應字串",
  "status": "active",
  "creationMethod": "manual",
  "sourceFile": "回應字串",
  "flaky": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

上傳 CSV 或 Excel 加入測試案例

POST /api/v1/test-case/upload/

以 multipart/form-data 上傳，file 與 dataset_id 都必填。檔案為 .csv、.xlsx 或 .xls，標題列須有 question 與 ground_truth 兩欄，每一列新增一筆單輪測試案例；CSV 請用 UTF-8 編碼。回應是新增測試案例的陣列。

參數

參數名稱	必填	類型	說明
creationMethod	❌	string	`manual`: Manual ; `file`: File import ; `generate`: Generated;
datasetId	❌	string
ordering	❌	string	Which field to use when ordering the results.
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
query	❌	string
search	❌	string	A search term.
status	❌	string	`active`: Active ; `inactive`: Inactive ; `pending`: Pending Review;

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/test-case/upload/?creationMethod=file&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=active" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -F "file=@example_file.pdf" \
  -F "dataset_id=範例字串"

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

JavaScript

const axios = require('axios');
const FormData = require('form-data');

// 建立FormData對象
const formData = new FormData();
// 請用實際檔案替換
formData.append('file', /* 實際檔案物件 */, 'example_file.pdf');
formData.append('dataset_id', '範例字串');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    ...formData.getHeaders()
  }
};

axios.post("https://api.maiagent.ai/api/v1/test-case/upload/?creationMethod=file&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=active", formData, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/test-case/upload/?creationMethod=file&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=active"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

# 建立檔案和表單資料
files = {
    'file': ('example_file.pdf', open('example_file.pdf', 'rb'), 'application/pdf'),
    'dataset_id': (None, '範例字串')
}

response = requests.post(url, files=files, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/test-case/upload/?creationMethod=file&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=active", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ],
        'multipart' => [
            [
                'name' => 'file',
                'contents' => fopen('example_file.pdf', 'r'),
                'filename' => 'example_file.pdf'
            ],
            [
                'name' => 'dataset_id',
                'contents' => '範例字串'
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 201

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "dataset": 
      {
        "id": string (uuid)
        "name": string
      }
      "question": string
      "groundTruth"?: string // 非必填
      "status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
      "creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (非必填)
      "sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (非必填)
      "flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
      "createdAt": string (timestamp)
      "updatedAt": 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",
      "dataset": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "question": "回應字串",
      "groundTruth": "回應字串",
      "status": "active",
      "creationMethod": "manual",
      "sourceFile": "回應字串",
      "flaky": false,
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ]
}

---

從知識庫檔案生成單輪測試案例

POST /api/v1/test-case/generate-from-file/

用 knowledgeBaseIds（展開為知識庫內處理完成、類型支援的所有檔案）或 knowledgeBaseFileIds 指定來源，兩者可合用；支援 txt、docx、pdf、md、markdown、mdx。numTestCases 是這次要生成的總題數（預設 10），檔案數或題數超過平台上限時回 400，訊息會寫出上限。生成在背景執行，回應 202 與 jobId；同一個測試集已有生成任務在進行時，回傳該任務的 jobId，不會重複建立。Credit：送出前檢查組織 Credit，不足回 402；依實際生成的題數扣 agentops_test_gen。

請求內容

請求參數

欄位	類型	必填	說明
chatbotFileIds	array[string]	否	List of KnowledgeBaseFile IDs to generate test cases from (deprecated)
knowledgeBaseFileIds	array[string]	否	List of KnowledgeBaseFile IDs to generate test cases from
knowledgeBaseIds	array[string]	否	List of KnowledgeBase IDs to generate test cases from all their files
datasetId	string (uuid)	是
numTestCases	integer	否

請求結構範例

{
  "chatbotFileIds"?: [ // List of KnowledgeBaseFile IDs to generate test cases from (deprecated) (非必填)
    string (uuid)
  ]
  "knowledgeBaseFileIds"?: [ // List of KnowledgeBaseFile IDs to generate test cases from (非必填)
    string (uuid)
  ]
  "knowledgeBaseIds"?: [ // List of KnowledgeBase IDs to generate test cases from all their files (非必填)
    string (uuid)
  ]
  "datasetId": string (uuid)
  "numTestCases"?: integer // 非必填
}

請求範例值

{
  "chatbotFileIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "knowledgeBaseFileIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "knowledgeBaseIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "datasetId": "550e8400-e29b-41d4-a716-446655440000",
  "numTestCases": 123
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/test-case/generate-from-file/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatbotFileIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "knowledgeBaseFileIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "knowledgeBaseIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "datasetId": "550e8400-e29b-41d4-a716-446655440000",
    "numTestCases": 123
  }'

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "chatbotFileIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "knowledgeBaseFileIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "knowledgeBaseIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "datasetId": "550e8400-e29b-41d4-a716-446655440000",
    "numTestCases": 123
  };

axios.post("https://api.maiagent.ai/api/v1/test-case/generate-from-file/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/test-case/generate-from-file/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "chatbotFileIds": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "knowledgeBaseFileIds": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "knowledgeBaseIds": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "datasetId": "550e8400-e29b-41d4-a716-446655440000",
    "numTestCases": 123
}

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/test-case/generate-from-file/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'chatbotFileIds' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'knowledgeBaseFileIds' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'knowledgeBaseIds' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'datasetId' => '550e8400-e29b-41d4-a716-446655440000',
            'numTestCases' => 123
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 202

回應結構範例

object

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應範例名稱",
  "description": "回應範例描述"
}

---

列出測試案例生成任務

GET /api/v1/test-case/generation-jobs/

列出組織的單輪與多輪生成任務，新到舊排序，可用 datasetId 與 status 篩選。

參數

參數名稱	必填	類型	說明
creationMethod	❌	string	`manual`: Manual ; `file`: File import ; `generate`: Generated;
datasetId	❌	string	只列出此資料集的生成任務
ordering	❌	string	Which field to use when ordering the results.
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
query	❌	string
search	❌	string	A search term.
status	❌	string	依狀態過濾：pending / running / completed / partial_completed / failed

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/test-case/generation-jobs/?creationMethod=file&datasetId=example&ordering=example&page=1&pageSize=1&query=example&search=example&status=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/test-case/generation-jobs/?creationMethod=file&datasetId=example&ordering=example&page=1&pageSize=1&query=example&search=example&status=example", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/test-case/generation-jobs/?creationMethod=file&datasetId=example&ordering=example&page=1&pageSize=1&query=example&search=example&status=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)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/test-case/generation-jobs/?creationMethod=file&datasetId=example&ordering=example&page=1&pageSize=1&query=example&search=example&status=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();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "dataset": 
      {
        "id": string (uuid)
        "name": string
      }
      "status"?: string (enum: pending, running, completed, partial_completed, failed) // * `pending` - Pending
* `running` - Generating
* `completed` - Completed
* `partial_completed` - Partially completed
* `failed` - Generation failed (非必填)
      "jobType"?:  // Single-turn Q&A test data or multi-turn conversation test data

* `single_turn` - Single turn
* `multi_turn` - Multi turn (非必填)
      {
      }
      "requestedNumTestCases"?: integer // 非必填
      "totalFiles"?: integer // 非必填
      "processedFiles"?: integer // 非必填
      "generatedCount"?: integer // 非必填
      "progressPercentage": number (double)
      "errorMessage"?: string // Error message recorded when the whole batch fails (非必填)
      "fileResults"?: object // Result for each file, such as [{'file_id', 'filename', 'status', 'generated', 'error'}] (非必填)
      "startedAt"?: string (timestamp) // 非必填
      "completedAt"?: string (timestamp) // 非必填
      "createdAt": string (timestamp)
      "updatedAt": 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",
      "dataset": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "status": "pending",
      "jobType": {},
      "requestedNumTestCases": 456,
      "totalFiles": 456,
      "processedFiles": 456,
      "generatedCount": 456,
      "progressPercentage": 456,
      "errorMessage": "回應字串",
      "fileResults": null,
      "startedAt": "回應字串",
      "completedAt": "回應字串",
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ]
}

---

查詢測試案例生成任務進度

GET /api/v1/test-case/generation-jobs/{jobId}/

status 為 pending、running、completed、partial_completed 或 failed；generatedCount 是已生成的題數，fileResults 列出每個檔案的結果與失敗原因。單輪與多輪的生成任務都用這個端點查詢，以 jobType 區分。

參數

參數名稱	必填	類型	說明
jobId	✅	string

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/test-case/generation-jobs/{jobId}/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/test-case/generation-jobs/{jobId}/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/test-case/generation-jobs/{jobId}/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/test-case/generation-jobs/{jobId}/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "dataset": 
  {
    "id": string (uuid)
    "name": string
  }
  "status"?: string (enum: pending, running, completed, partial_completed, failed) // * `pending` - Pending
* `running` - Generating
* `completed` - Completed
* `partial_completed` - Partially completed
* `failed` - Generation failed (非必填)
  "jobType"?:  // Single-turn Q&A test data or multi-turn conversation test data

* `single_turn` - Single turn
* `multi_turn` - Multi turn (非必填)
  {
  }
  "requestedNumTestCases"?: integer // 非必填
  "totalFiles"?: integer // 非必填
  "processedFiles"?: integer // 非必填
  "generatedCount"?: integer // 非必填
  "progressPercentage": number (double)
  "errorMessage"?: string // Error message recorded when the whole batch fails (非必填)
  "fileResults"?: object // Result for each file, such as [{'file_id', 'filename', 'status', 'generated', 'error'}] (非必填)
  "startedAt"?: string (timestamp) // 非必填
  "completedAt"?: string (timestamp) // 非必填
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "dataset": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "status": "pending",
  "jobType": {},
  "requestedNumTestCases": 456,
  "totalFiles": 456,
  "processedFiles": 456,
  "generatedCount": 456,
  "progressPercentage": 456,
  "errorMessage": "回應字串",
  "fileResults": null,
  "startedAt": "回應字串",
  "completedAt": "回應字串",
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

更新單輪測試案例

PUT /api/v1/test-case/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Q&A pair.

請求內容

請求參數

欄位	類型	必填	說明
question	string	是
groundTruth	string	否
status	string (enum: active, inactive, pending)	否	active: Active ; inactive: Inactive ; pending: Pending Review;
flaky	boolean	否	Flaky test cases still run and keep their results, but are excluded from the pass rate.

請求結構範例

{
  "question": string
  "groundTruth"?: string // 非必填
  "status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
  "flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
}

請求範例值

{
  "question": "範例字串",
  "groundTruth": "範例字串",
  "status": "active",
  "flaky": true
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "範例字串",
    "groundTruth": "範例字串",
    "status": "active",
    "flaky": true
  }'

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "question": "範例字串",
    "groundTruth": "範例字串",
    "status": "active",
    "flaky": true
  };

axios.put("https://api.maiagent.ai/api/v1/test-case/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);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "question": "範例字串",
    "groundTruth": "範例字串",
    "status": "active",
    "flaky": True
}

response = requests.put(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->put("https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'question' => '範例字串',
            'groundTruth' => '範例字串',
            'status' => 'active',
            'flaky' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "dataset": 
  {
    "id": string (uuid)
    "name": string
  }
  "question": string
  "groundTruth"?: string // 非必填
  "status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
  "creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (非必填)
  "sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (非必填)
  "flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "dataset": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "question": "回應字串",
  "groundTruth": "回應字串",
  "status": "active",
  "creationMethod": "manual",
  "sourceFile": "回應字串",
  "flaky": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

部分更新單輪測試案例

PATCH /api/v1/test-case/{id}/

想暫時不測某一題時，把 status 改成 inactive，評估會略過它，過往的評估結果也會保留。

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Q&A pair.

請求內容

請求參數

欄位	類型	必填	說明
question	string	否
groundTruth	string	否
status	string (enum: active, inactive, pending)	否	active: Active ; inactive: Inactive ; pending: Pending Review;
flaky	boolean	否	Flaky test cases still run and keep their results, but are excluded from the pass rate.

請求結構範例

{
  "question"?: string // 非必填
  "groundTruth"?: string // 非必填
  "status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
  "flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
}

請求範例值

{
  "question": "範例字串",
  "groundTruth": "範例字串",
  "status": "active",
  "flaky": true
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "範例字串",
    "groundTruth": "範例字串",
    "status": "active",
    "flaky": true
  }'

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "question": "範例字串",
    "groundTruth": "範例字串",
    "status": "active",
    "flaky": true
  };

axios.patch("https://api.maiagent.ai/api/v1/test-case/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);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "question": "範例字串",
    "groundTruth": "範例字串",
    "status": "active",
    "flaky": True
}

response = requests.patch(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'question' => '範例字串',
            'groundTruth' => '範例字串',
            'status' => 'active',
            'flaky' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "dataset": 
  {
    "id": string (uuid)
    "name": string
  }
  "question": string
  "groundTruth"?: string // 非必填
  "status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
  "creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (非必填)
  "sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (非必填)
  "flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "dataset": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "question": "回應字串",
  "groundTruth": "回應字串",
  "status": "active",
  "creationMethod": "manual",
  "sourceFile": "回應字串",
  "flaky": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

刪除單輪測試案例

DELETE /api/v1/test-case/{id}/

會一併刪除這筆測試案例在過往評估中的逐題結果；只想暫停測試請改用 status。

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Q&A pair.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

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/test-case/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);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/test-case/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)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->delete("https://api.maiagent.ai/api/v1/test-case/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();
}
?>

回應內容

狀態碼	說明
204	No response body

---

批次刪除單輪測試案例

POST /api/v1/test-case/bulk-delete/

以 testCaseIds 傳入要刪除的測試案例 ID 陣列，成功回 204。刪除的影響同 刪除單輪測試案例。

請求內容

請求參數

欄位	類型	必填	說明
test_case_ids	array[string]	是	要刪除的測試案例 ID 列表

請求結構範例

{
  "test_case_ids": [ // 要刪除的測試案例 ID 列表
    string (uuid)
  ]
}

請求範例值

{
  "test_case_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/test-case/bulk-delete/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "test_case_ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }'

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "test_case_ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  };

axios.post("https://api.maiagent.ai/api/v1/test-case/bulk-delete/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/test-case/bulk-delete/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "test_case_ids": [
        "550e8400-e29b-41d4-a716-446655440000"
    ]
}

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/test-case/bulk-delete/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'test_case_ids' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼	說明
204	No response body

---

列出多輪測試案例

GET /api/v1/multi-turn-test-case/

用 datasetId 篩選單一測試集。

參數

參數名稱	必填	類型	說明
dataset	❌	string
datasetId	❌	string
ordering	❌	string	Which field to use when ordering the results.
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
search	❌	string	A search term.
status	❌	string	`active`: Active ; `inactive`: Inactive;

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/multi-turn-test-case/?dataset=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&search=example&status=active" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/multi-turn-test-case/?dataset=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&search=example&status=active", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/?dataset=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&search=example&status=active"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/multi-turn-test-case/?dataset=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&search=example&status=active", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "dataset": 
      {
        "id": string (uuid)
        "name": string
      }
      "scenario": string // Task scenario the simulated user should accomplish
      "expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
      "userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (非必填)
      "status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (非必填)
      "creationMethod": 
      {
      }
      "sourceFile": string // Name of the knowledge base file this multi-turn test case was generated from
      "flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
      "createdAt": string (timestamp)
      "updatedAt": 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",
      "dataset": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "scenario": "回應字串",
      "expectedOutcome": "回應字串",
      "userDescription": "回應字串",
      "status": "active",
      "creationMethod": {},
      "sourceFile": "回應字串",
      "flaky": false,
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ]
}

---

建立多輪測試案例

POST /api/v1/multi-turn-test-case/

datasetId、scenario（模擬使用者要完成的任務情境）、expectedOutcome（對話成功時應達成的結果，也是模擬對話的結束條件）必填；userDescription 選填，描述模擬使用者的語氣、背景與專業程度。

請求內容

請求參數

欄位	類型	必填	說明
datasetId	string (uuid)	是
scenario	string	是
expectedOutcome	string	是
userDescription	string	否
status	object	否
flaky	boolean	否

請求結構範例

{
  "datasetId": string (uuid)
  "scenario": string
  "expectedOutcome": string
  "userDescription"?: string // 非必填
  "status"?:  // 非必填
  {
  }
  "flaky"?: boolean // 非必填
}

請求範例值

{
  "datasetId": "550e8400-e29b-41d4-a716-446655440000",
  "scenario": "範例字串",
  "expectedOutcome": "範例字串",
  "userDescription": "範例字串",
  "status": {},
  "flaky": true
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/multi-turn-test-case/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datasetId": "550e8400-e29b-41d4-a716-446655440000",
    "scenario": "範例字串",
    "expectedOutcome": "範例字串",
    "userDescription": "範例字串",
    "status": {},
    "flaky": true
  }'

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "datasetId": "550e8400-e29b-41d4-a716-446655440000",
    "scenario": "範例字串",
    "expectedOutcome": "範例字串",
    "userDescription": "範例字串",
    "status": {},
    "flaky": true
  };

axios.post("https://api.maiagent.ai/api/v1/multi-turn-test-case/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "datasetId": "550e8400-e29b-41d4-a716-446655440000",
    "scenario": "範例字串",
    "expectedOutcome": "範例字串",
    "userDescription": "範例字串",
    "status": {},
    "flaky": True
}

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/multi-turn-test-case/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'datasetId' => '550e8400-e29b-41d4-a716-446655440000',
            'scenario' => '範例字串',
            'expectedOutcome' => '範例字串',
            'userDescription' => '範例字串',
            'status' => new \stdClass(),
            'flaky' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "dataset": 
  {
    "id": string (uuid)
    "name": string
  }
  "scenario": string // Task scenario the simulated user should accomplish
  "expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
  "userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (非必填)
  "status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (非必填)
  "creationMethod": 
  {
  }
  "sourceFile": string // Name of the knowledge base file this multi-turn test case was generated from
  "flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "dataset": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "scenario": "回應字串",
  "expectedOutcome": "回應字串",
  "userDescription": "回應字串",
  "status": "active",
  "creationMethod": {},
  "sourceFile": "回應字串",
  "flaky": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

從知識庫檔案生成多輪測試案例

POST /api/v1/multi-turn-test-case/generate-from-file/

用 knowledgeBaseFileIds 指定來源檔案，numTestCases 預設 5、最多 20。生成在背景執行，回應 202 與 jobId，用 查詢測試案例生成任務進度 追蹤。Credit：同單輪生成，依實際生成的題數扣 agentops_test_gen。

請求內容

請求參數

欄位	類型	必填	說明
datasetId	string (uuid)	是
knowledgeBaseFileIds	array[string]	是	List of KnowledgeBaseFile IDs to generate multi-turn test cases from
numTestCases	integer	否

請求結構範例

{
  "datasetId": string (uuid)
  "knowledgeBaseFileIds": [ // List of KnowledgeBaseFile IDs to generate multi-turn test cases from
    string (uuid)
  ]
  "numTestCases"?: integer // 非必填
}

請求範例值

{
  "datasetId": "550e8400-e29b-41d4-a716-446655440000",
  "knowledgeBaseFileIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "numTestCases": 123
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/multi-turn-test-case/generate-from-file/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datasetId": "550e8400-e29b-41d4-a716-446655440000",
    "knowledgeBaseFileIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "numTestCases": 123
  }'

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "datasetId": "550e8400-e29b-41d4-a716-446655440000",
    "knowledgeBaseFileIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "numTestCases": 123
  };

axios.post("https://api.maiagent.ai/api/v1/multi-turn-test-case/generate-from-file/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/generate-from-file/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "datasetId": "550e8400-e29b-41d4-a716-446655440000",
    "knowledgeBaseFileIds": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "numTestCases": 123
}

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/multi-turn-test-case/generate-from-file/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'datasetId' => '550e8400-e29b-41d4-a716-446655440000',
            'knowledgeBaseFileIds' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'numTestCases' => 123
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 202

回應結構範例

object

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應範例名稱",
  "description": "回應範例描述"
}

---

取得特定多輪測試案例

GET /api/v1/multi-turn-test-case/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Multi-turn test case.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/multi-turn-test-case/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);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/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)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/multi-turn-test-case/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();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "dataset": 
  {
    "id": string (uuid)
    "name": string
  }
  "scenario": string // Task scenario the simulated user should accomplish
  "expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
  "userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (非必填)
  "status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (非必填)
  "creationMethod": 
  {
  }
  "sourceFile": string // Name of the knowledge base file this multi-turn test case was generated from
  "flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "dataset": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "scenario": "回應字串",
  "expectedOutcome": "回應字串",
  "userDescription": "回應字串",
  "status": "active",
  "creationMethod": {},
  "sourceFile": "回應字串",
  "flaky": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

更新多輪測試案例

PUT /api/v1/multi-turn-test-case/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Multi-turn test case.

請求內容

請求參數

欄位	類型	必填	說明
scenario	string	是	Task scenario the simulated user should accomplish
expectedOutcome	string	是	Outcome a successful conversation should reach, also used as the simulation stop condition
userDescription	string	否	Persona of the simulated user, such as tone, background and level of expertise
status	string (enum: active, inactive)	否	active: Active ; inactive: Inactive;
flaky	boolean	否	Flaky test cases still run and keep their results, but are excluded from the pass rate.

請求結構範例

{
  "scenario": string // Task scenario the simulated user should accomplish
  "expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
  "userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (非必填)
  "status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (非必填)
  "flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
}

請求範例值

{
  "scenario": "範例字串",
  "expectedOutcome": "範例字串",
  "userDescription": "範例字串",
  "status": "active",
  "flaky": true
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "範例字串",
    "expectedOutcome": "範例字串",
    "userDescription": "範例字串",
    "status": "active",
    "flaky": true
  }'

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "scenario": "範例字串",
    "expectedOutcome": "範例字串",
    "userDescription": "範例字串",
    "status": "active",
    "flaky": true
  };

axios.put("https://api.maiagent.ai/api/v1/multi-turn-test-case/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);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "scenario": "範例字串",
    "expectedOutcome": "範例字串",
    "userDescription": "範例字串",
    "status": "active",
    "flaky": True
}

response = requests.put(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->put("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'scenario' => '範例字串',
            'expectedOutcome' => '範例字串',
            'userDescription' => '範例字串',
            'status' => 'active',
            'flaky' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "dataset": 
  {
    "id": string (uuid)
    "name": string
  }
  "scenario": string // Task scenario the simulated user should accomplish
  "expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
  "userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (非必填)
  "status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (非必填)
  "creationMethod": 
  {
  }
  "sourceFile": string // Name of the knowledge base file this multi-turn test case was generated from
  "flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "dataset": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "scenario": "回應字串",
  "expectedOutcome": "回應字串",
  "userDescription": "回應字串",
  "status": "active",
  "creationMethod": {},
  "sourceFile": "回應字串",
  "flaky": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

部分更新多輪測試案例

PATCH /api/v1/multi-turn-test-case/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Multi-turn test case.

請求內容

請求參數

欄位	類型	必填	說明
scenario	string	否	Task scenario the simulated user should accomplish
expectedOutcome	string	否	Outcome a successful conversation should reach, also used as the simulation stop condition
userDescription	string	否	Persona of the simulated user, such as tone, background and level of expertise
status	string (enum: active, inactive)	否	active: Active ; inactive: Inactive;
flaky	boolean	否	Flaky test cases still run and keep their results, but are excluded from the pass rate.

請求結構範例

{
  "scenario"?: string // Task scenario the simulated user should accomplish (非必填)
  "expectedOutcome"?: string // Outcome a successful conversation should reach, also used as the simulation stop condition (非必填)
  "userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (非必填)
  "status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (非必填)
  "flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
}

請求範例值

{
  "scenario": "範例字串",
  "expectedOutcome": "範例字串",
  "userDescription": "範例字串",
  "status": "active",
  "flaky": true
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "範例字串",
    "expectedOutcome": "範例字串",
    "userDescription": "範例字串",
    "status": "active",
    "flaky": true
  }'

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "scenario": "範例字串",
    "expectedOutcome": "範例字串",
    "userDescription": "範例字串",
    "status": "active",
    "flaky": true
  };

axios.patch("https://api.maiagent.ai/api/v1/multi-turn-test-case/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);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "scenario": "範例字串",
    "expectedOutcome": "範例字串",
    "userDescription": "範例字串",
    "status": "active",
    "flaky": True
}

response = requests.patch(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'scenario' => '範例字串',
            'expectedOutcome' => '範例字串',
            'userDescription' => '範例字串',
            'status' => 'active',
            'flaky' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "dataset": 
  {
    "id": string (uuid)
    "name": string
  }
  "scenario": string // Task scenario the simulated user should accomplish
  "expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
  "userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (非必填)
  "status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (非必填)
  "creationMethod": 
  {
  }
  "sourceFile": string // Name of the knowledge base file this multi-turn test case was generated from
  "flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "dataset": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "scenario": "回應字串",
  "expectedOutcome": "回應字串",
  "userDescription": "回應字串",
  "status": "active",
  "creationMethod": {},
  "sourceFile": "回應字串",
  "flaky": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

刪除多輪測試案例

DELETE /api/v1/multi-turn-test-case/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Multi-turn test case.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

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/multi-turn-test-case/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);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/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)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->delete("https://api.maiagent.ai/api/v1/multi-turn-test-case/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();
}
?>

回應內容

狀態碼	說明
204	No response body

---

列出可用的評估模型

GET /api/v1/evaluations/evaluation-llms/

isDefault 為 true 的模型，是執行評估時沒有指定 evaluationLlmId 所使用的預設評估模型。

參數

參數名稱	必填	類型	說明
chatbotId	❌	string
datasetId	❌	string
ordering	❌	string	Which field to use when ordering the results.
query	❌	string
search	❌	string	A search term.
status	❌	string	`pending`: Pending evaluation ; `running`: Evaluating ; `stopping`: Stopping ; `completed`: Completed ; `partial_completed`: Partially completed ; `failed`: Evaluation failed;

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/evaluation-llms/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&query=example&search=example&status=completed" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/evaluations/evaluation-llms/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&query=example&search=example&status=completed", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/evaluations/evaluation-llms/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&query=example&search=example&status=completed"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/evaluations/evaluation-llms/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&query=example&search=example&status=completed", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

[
  {
    "id": string (uuid)
    "name": string
    "value": string
    "provider": string
    "isDefault": boolean
  }
]

回應範例值

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "value": "回應字串",
    "provider": "回應字串",
    "isDefault": false
  }
]

---

執行單輪評估

POST /api/v1/evaluations/evaluate/

datasetId 與 chatbotId 必填；evaluationLlmId 省略時使用預設評估模型。metricConfig 以布林值開關內建指標，customMetrics 最多 10 個自訂指標。只評估狀態為 active 的測試案例。評估在背景執行，回應 202 與 evaluationId。Credit：送出前檢查組織 Credit，不足回 402；評估結束時依完成的測試案例數扣 agentops_test_run 與 agentops_deepeval，評估模型的呼叫另計。

請求內容

請求參數

欄位	類型	必填	說明
datasetId	string (uuid)	是
chatbotId	string (uuid)	是
evaluationLlmId	string (uuid)	否
name	string	否
description	string	否
metricConfig	object	否
customMetrics	array[DatasetEvaluationCustomMetric]	否

請求結構範例

{
  "datasetId": string (uuid)
  "chatbotId": string (uuid)
  "evaluationLlmId"?: string (uuid) // 非必填
  "name"?: string // 非必填
  "description"?: string // 非必填
  "metricConfig"?: object // 非必填
  "customMetrics"?: [ // 非必填
    {
      "name": string
      "criteria"?: string // 非必填
      "evaluationSteps"?: [ // 非必填
        string
      ]
      "threshold"?: number (double) // 非必填
    }
  ]
}

請求範例值

{
  "dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "evaluation_llm_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Evaluation Name",
  "description": "Evaluation Description",
  "metric_config": {
    "ground_truth": true,
    "task_completion": false,
    "tool_correctness": false,
    "guardrail": true,
    "summarize": false,
    "hallucination": true
  },
  "custom_metrics": [
    {
      "name": "Support Tone",
      "criteria": "The answer should be polite, empathetic, and professional in tone.",
      "threshold": 0.6
    }
  ]
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/evaluations/evaluate/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "evaluation_llm_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Evaluation Name",
    "description": "Evaluation Description",
    "metric_config": {
      "ground_truth": true,
      "task_completion": false,
      "tool_correctness": false,
      "guardrail": true,
      "summarize": false,
      "hallucination": true
    },
    "custom_metrics": [
      {
        "name": "Support Tone",
        "criteria": "The answer should be polite, empathetic, and professional in tone.",
        "threshold": 0.6
      }
    ]
  }'

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "evaluation_llm_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Evaluation Name",
    "description": "Evaluation Description",
    "metric_config": {
      "ground_truth": true,
      "task_completion": false,
      "tool_correctness": false,
      "guardrail": true,
      "summarize": false,
      "hallucination": true
    },
    "custom_metrics": [
      {
        "name": "Support Tone",
        "criteria": "The answer should be polite, empathetic, and professional in tone.",
        "threshold": 0.6
      }
    ]
  };

axios.post("https://api.maiagent.ai/api/v1/evaluations/evaluate/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/evaluations/evaluate/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "evaluation_llm_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Evaluation Name",
    "description": "Evaluation Description",
    "metric_config": {
        "ground_truth": True,
        "task_completion": False,
        "tool_correctness": False,
        "guardrail": True,
        "summarize": False,
        "hallucination": True
    },
    "custom_metrics": [
        {
            "name": "Support Tone",
            "criteria": "The answer should be polite, empathetic, and professional in tone.",
            "threshold": 0.6
        }
    ]
}

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/evaluations/evaluate/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'dataset_id' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
            'chatbot_id' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
            'evaluation_llm_id' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
            'name' => 'Evaluation Name',
            'description' => 'Evaluation Description',
            'metric_config' => [
                'ground_truth' => true,
                'task_completion' => false,
                'tool_correctness' => false,
                'guardrail' => true,
                'summarize' => false,
                'hallucination' => true
            ],
            'custom_metrics' => [
                [
                    'name' => 'Support Tone',
                    'criteria' => 'The answer should be polite, empathetic, and professional in tone.',
                    'threshold' => 0.6
                ]
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 202

回應結構範例

object

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應範例名稱",
  "description": "回應範例描述"
}

---

執行多輪評估

POST /api/v1/evaluations/multi-turn-evaluate/

以測試集內的多輪測試案例模擬使用者與 Agent 對話後評分。maxTurns 是模擬使用者最多發話的輪數（2～10，預設 6），language 是模擬使用者的語言（Traditional Chinese、Simplified Chinese、English、Japanese、Korean，預設 Traditional Chinese）。測試集沒有任何 active 的多輪測試案例時回 400。回應與 Credit 同 執行單輪評估。

請求內容

請求參數

欄位	類型	必填	說明
datasetId	string (uuid)	是
chatbotId	string (uuid)	是
evaluationLlmId	string (uuid)	否
name	string	否
description	string	否
maxTurns	integer	否
minTurns	integer	否
turnFaithfulness	boolean	否
turnRelevancy	boolean	否
conversationCompleteness	boolean	否
language	object	否
customMetrics	array[MultiTurnCustomMetric]	否

請求結構範例

{
  "datasetId": string (uuid)
  "chatbotId": string (uuid)
  "evaluationLlmId"?: string (uuid) // 非必填
  "name"?: string // 非必填
  "description"?: string // 非必填
  "maxTurns"?: integer // 非必填
  "minTurns"?: integer // 非必填
  "turnFaithfulness"?: boolean // 非必填
  "turnRelevancy"?: boolean // 非必填
  "conversationCompleteness"?: boolean // 非必填
  "language"?:  // 非必填
  {
  }
  "customMetrics"?: [ // 非必填
    {
      "name": string
      "criteria"?: string // 非必填
      "evaluationSteps"?: [ // 非必填
        string
      ]
      "threshold"?: number (double) // 非必填
    }
  ]
}

請求範例值

{
  "dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "max_turns": 6,
  "min_turns": 2,
  "custom_metrics": [
    {
      "name": "Identity Check",
      "criteria": "The assistant confirms the user identity before sharing account details.",
      "threshold": 0.6
    }
  ]
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/evaluations/multi-turn-evaluate/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "max_turns": 6,
    "min_turns": 2,
    "custom_metrics": [
      {
        "name": "Identity Check",
        "criteria": "The assistant confirms the user identity before sharing account details.",
        "threshold": 0.6
      }
    ]
  }'

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "max_turns": 6,
    "min_turns": 2,
    "custom_metrics": [
      {
        "name": "Identity Check",
        "criteria": "The assistant confirms the user identity before sharing account details.",
        "threshold": 0.6
      }
    ]
  };

axios.post("https://api.maiagent.ai/api/v1/evaluations/multi-turn-evaluate/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/evaluations/multi-turn-evaluate/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "max_turns": 6,
    "min_turns": 2,
    "custom_metrics": [
        {
            "name": "Identity Check",
            "criteria": "The assistant confirms the user identity before sharing account details.",
            "threshold": 0.6
        }
    ]
}

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/evaluations/multi-turn-evaluate/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'dataset_id' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
            'chatbot_id' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
            'max_turns' => 6,
            'min_turns' => 2,
            'custom_metrics' => [
                [
                    'name' => 'Identity Check',
                    'criteria' => 'The assistant confirms the user identity before sharing account details.',
                    'threshold' => 0.6
                ]
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 202

回應結構範例

object

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應範例名稱",
  "description": "回應範例描述"
}

---

列出評估

GET /api/v1/evaluations/

可用 datasetId、chatbotId、status 篩選。

參數

參數名稱	必填	類型	說明
chatbotId	❌	string
datasetId	❌	string
ordering	❌	string	Which field to use when ordering the results.
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
query	❌	string
search	❌	string	A search term.
status	❌	string	`pending`: Pending evaluation ; `running`: Evaluating ; `stopping`: Stopping ; `completed`: Completed ; `partial_completed`: Partially completed ; `failed`: Evaluation failed;

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/evaluations/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/evaluations/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/evaluations/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "name": string
      "description": string
      "chatbot": 
      {
        "id": string (uuid)
        "name": string
      }
      "dataset": 
      {
        "id": string (uuid)
        "name": string
      }
      "organization": 
      {
        "id": string (uuid)
        "name": string
      }
      "evaluationLlm": 
      {
        "id": string (uuid)
        "name": string
      }
      "status": 
      {
      }
      "startedAt": string (timestamp)
      "completedAt": string (timestamp)
      "totalTestCases": integer
      "completedTestCases": integer
      "passedTestCases": integer // Number of test cases that passed
      "metricScores": object // Detailed score per evaluation metric, such as ground_truth, task_completion and tool_correctness
      "evaluationConfig": object
      "progressPercentage": number (double)
      "overallScore": number (double)
      "passRate": number (double)
      "averageExecutionTimeMs": integer
      "totalExecutionTimeMs": integer
      "chatbotConfig": string
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
      "insights": 
      {
        "summary": string
        "metricStats"?: object // 非必填
        "recommendations"?: object // 非必填
      }
    }
  ]
}

回應範例值

{
  "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": "回應字串",
      "description": "回應字串",
      "chatbot": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "dataset": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "organization": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "evaluationLlm": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "status": {},
      "startedAt": "回應字串",
      "completedAt": "回應字串",
      "totalTestCases": 456,
      "completedTestCases": 456,
      "passedTestCases": 456,
      "metricScores": null,
      "evaluationConfig": null,
      "progressPercentage": 456,
      "overallScore": 456,
      "passRate": 456,
      "averageExecutionTimeMs": 456,
      "totalExecutionTimeMs": 456,
      "chatbotConfig": "回應字串",
      "createdAt": "回應字串",
      "updatedAt": "回應字串",
      "insights": {
        "summary": "回應字串",
        "metricStats": null,
        "recommendations": null
      }
    }
  ]
}

---

取得評估結果

GET /api/v1/evaluations/{id}/

status 為 pending、running、stopping、completed、partial_completed 或 failed；執行中看 progressPercentage，結束後看 passRate、overallScore 與各指標的 metricScores。沒有任何測試案例完成時結束為 failed。

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Dataset evaluation.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/evaluations/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);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/evaluations/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)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/evaluations/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();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string
  "description": string
  "chatbot": 
  {
    "id": string (uuid)
    "name": string
  }
  "dataset": 
  {
    "id": string (uuid)
    "name": string
  }
  "organization": 
  {
    "id": string (uuid)
    "name": string
  }
  "evaluationLlm": 
  {
    "id": string (uuid)
    "name": string
  }
  "status": 
  {
  }
  "startedAt": string (timestamp)
  "completedAt": string (timestamp)
  "totalTestCases": integer
  "completedTestCases": integer
  "passedTestCases": integer // Number of test cases that passed
  "metricScores": object // Detailed score per evaluation metric, such as ground_truth, task_completion and tool_correctness
  "evaluationConfig": object
  "progressPercentage": number (double)
  "overallScore": number (double)
  "passRate": number (double)
  "averageExecutionTimeMs": integer
  "totalExecutionTimeMs": integer
  "chatbotConfig": string
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
  "insights": 
  {
    "summary": string
    "metricStats"?: object // 非必填
    "recommendations"?: object // 非必填
  }
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "chatbot": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "dataset": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "organization": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "evaluationLlm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "status": {},
  "startedAt": "回應字串",
  "completedAt": "回應字串",
  "totalTestCases": 456,
  "completedTestCases": 456,
  "passedTestCases": 456,
  "metricScores": null,
  "evaluationConfig": null,
  "progressPercentage": 456,
  "overallScore": 456,
  "passRate": 456,
  "averageExecutionTimeMs": 456,
  "totalExecutionTimeMs": 456,
  "chatbotConfig": "回應字串",
  "createdAt": "回應字串",
  "updatedAt": "回應字串",
  "insights": {
    "summary": "回應字串",
    "metricStats": null,
    "recommendations": null
  }
}

---

取得單輪評估的逐題結果

GET /api/v1/evaluations/{id}/details/

只適用單輪評估，多輪評估回 400。回應是所有測試案例結果的陣列，不分頁。

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Dataset evaluation.
chatbotId	❌	string
datasetId	❌	string
ordering	❌	string	Which field to use when ordering the results.
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
query	❌	string
search	❌	string	A search term.
status	❌	string	`pending`: Pending evaluation ; `running`: Evaluating ; `stopping`: Stopping ; `completed`: Completed ; `partial_completed`: Partially completed ; `failed`: Evaluation failed;

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/details/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/details/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/details/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/details/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "datasetEvaluation": 
      {
        "id": string (uuid)
        "name": string
      }
      "testCase": 
      {
        "id": string (uuid)
        "dataset": 
        {
          "id": string (uuid)
          "name": string
        }
        "question": string
        "groundTruth"?: string // 非必填
        "status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
        "creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (非必填)
        "sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (非必填)
        "flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
        "createdAt": string (timestamp)
        "updatedAt": string (timestamp)
      }
      "status": 
      {
      }
      "chatbotResponse": string
      "context": [ // Enrich each context item with is_deleted status for referenced knowledge base files.
        object
      ]
      "metricScores": object
      "executionTimeMs": integer
      "executionTimeSeconds": number (double)
      "passed": boolean
      "errorMessage": string // Error message recorded when the evaluation fails
      "startedAt": string (timestamp)
      "completedAt": string (timestamp)
      "retryCount": integer // Number of times this test case has been retried
      "lastAttemptAt": string (timestamp) // Time of the last evaluation attempt
      "createdAt": string (timestamp)
      "updatedAt": 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",
      "datasetEvaluation": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "testCase": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "dataset": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        },
        "question": "回應字串",
        "groundTruth": "回應字串",
        "status": "active",
        "creationMethod": "manual",
        "sourceFile": "回應字串",
        "flaky": false,
        "createdAt": "回應字串",
        "updatedAt": "回應字串"
      },
      "status": {},
      "chatbotResponse": "回應字串",
      "context": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應範例名稱",
          "description": "回應範例描述"
        }
      ],
      "metricScores": null,
      "executionTimeMs": 456,
      "executionTimeSeconds": 456,
      "passed": false,
      "errorMessage": "回應字串",
      "startedAt": "回應字串",
      "completedAt": "回應字串",
      "retryCount": 456,
      "lastAttemptAt": "回應字串",
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ]
}

---

取得多輪評估的逐對話結果

GET /api/v1/evaluations/{id}/multi-turn-results/

只適用多輪評估，單輪評估回 400。回應分頁。

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Dataset evaluation.
chatbotId	❌	string
datasetId	❌	string
ordering	❌	string	Which field to use when ordering the results.
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
query	❌	string
search	❌	string	A search term.
status	❌	string	`pending`: Pending evaluation ; `running`: Evaluating ; `stopping`: Stopping ; `completed`: Completed ; `partial_completed`: Partially completed ; `failed`: Evaluation failed;

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/multi-turn-results/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/multi-turn-results/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/multi-turn-results/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/multi-turn-results/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "multiTurnTestCase": string (uuid)
      "scenario": string
      "expectedOutcome": string
      "flaky": boolean
      "status": 
      {
      }
      "turns": object // The whole simulated conversation; each turn is {role, content, retrieval_context}
      "metricScores": object
      "passed": boolean
      "errorMessage": string
      "startedAt": string (timestamp)
      "completedAt": string (timestamp)
      "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",
      "multiTurnTestCase": "550e8400-e29b-41d4-a716-446655440000",
      "scenario": "回應字串",
      "expectedOutcome": "回應字串",
      "flaky": false,
      "status": {},
      "turns": null,
      "metricScores": null,
      "passed": false,
      "errorMessage": "回應字串",
      "startedAt": "回應字串",
      "completedAt": "回應字串",
      "createdAt": "回應字串"
    }
  ]
}

---

取消執行中的評估

POST /api/v1/evaluations/{id}/cancel/

只能取消 status 為 running 的評估，否則回 400。取消後 status 先變成 stopping，停止後結束為 partial_completed，保留已算好的分數，已完成的測試案例照常扣 Credit；之後可以用 繼續未完成的評估 補跑。

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Dataset evaluation.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/cancel/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// 請求內容 (payload)
const data = null;

axios.post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/cancel/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/cancel/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.post(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/cancel/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string
  "description": string
  "chatbot": 
  {
    "id": string (uuid)
    "name": string
  }
  "dataset": 
  {
    "id": string (uuid)
    "name": string
  }
  "organization": 
  {
    "id": string (uuid)
    "name": string
  }
  "evaluationLlm": 
  {
    "id": string (uuid)
    "name": string
  }
  "status": 
  {
  }
  "startedAt": string (timestamp)
  "completedAt": string (timestamp)
  "totalTestCases": integer
  "completedTestCases": integer
  "passedTestCases": integer // Number of test cases that passed
  "metricScores": object // Detailed score per evaluation metric, such as ground_truth, task_completion and tool_correctness
  "evaluationConfig": object
  "progressPercentage": number (double)
  "overallScore": number (double)
  "passRate": number (double)
  "averageExecutionTimeMs": integer
  "totalExecutionTimeMs": integer
  "chatbotConfig": string
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
  "insights": 
  {
    "summary": string
    "metricStats"?: object // 非必填
    "recommendations"?: object // 非必填
  }
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "chatbot": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "dataset": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "organization": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "evaluationLlm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "status": {},
  "startedAt": "回應字串",
  "completedAt": "回應字串",
  "totalTestCases": 456,
  "completedTestCases": 456,
  "passedTestCases": 456,
  "metricScores": null,
  "evaluationConfig": null,
  "progressPercentage": 456,
  "overallScore": 456,
  "passRate": 456,
  "averageExecutionTimeMs": 456,
  "totalExecutionTimeMs": 456,
  "chatbotConfig": "回應字串",
  "createdAt": "回應字串",
  "updatedAt": "回應字串",
  "insights": {
    "summary": "回應字串",
    "metricStats": null,
    "recommendations": null
  }
}

---

繼續未完成的評估

POST /api/v1/evaluations/{id}/resume/

只能繼續 status 為 partial_completed 的評估，否則回 400。重跑失敗與尚未執行的測試案例並保留已完成的結果，回應 202；只對先前未計費的完成案例扣 Credit。

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Dataset evaluation.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/resume/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// 請求內容 (payload)
const data = null;

axios.post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/resume/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/resume/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.post(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/resume/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 202

回應結構範例

object

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應範例名稱",
  "description": "回應範例描述"
}

---

匯出評估報表

POST /api/v1/evaluations/{id}/export/

只能匯出 status 為 completed 的單輪評估；多輪評估目前不支援匯出，回 400。報表在背景產生 Excel 檔，回應 201 與匯出紀錄，再用 查詢最新匯出狀態 取得下載網址。

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Dataset evaluation.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// 請求內容 (payload)
const data = null;

axios.post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.post(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/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();
}
?>

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "userEmail": string (email)
  "datasetEvaluationId": string (uuid)
  "datasetEvaluationName": string
  "status": 
  {
  }
  "statusDisplay": string
  "fileUrl": string // 返回檔案 URL
  "fileSize": integer // File size in bytes
  "errorMessage": string
  "processingDurationSeconds": number (double) // 計算處理時長（秒）
  "createdAt": string (timestamp)
  "startedAt": string (timestamp)
  "completedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userEmail": "[e-mail]",
  "datasetEvaluationId": "550e8400-e29b-41d4-a716-446655440000",
  "datasetEvaluationName": "回應字串",
  "status": {},
  "statusDisplay": "回應字串",
  "fileUrl": "回應字串",
  "fileSize": 456,
  "errorMessage": "回應字串",
  "processingDurationSeconds": 456,
  "createdAt": "回應字串",
  "startedAt": "回應字串",
  "completedAt": "回應字串"
}

---

查詢最新匯出狀態

GET /api/v1/evaluations/{id}/export-status/

回傳這筆評估最近一次的匯出紀錄：status 為 pending、processing、completed 或 failed，completed 時從 fileUrl 下載。這筆評估沒有匯出紀錄時回 404。

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Dataset evaluation.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export-status/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export-status/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export-status/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export-status/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "userEmail": string (email)
  "datasetEvaluationId": string (uuid)
  "datasetEvaluationName": string
  "status": 
  {
  }
  "statusDisplay": string
  "fileUrl": string // 返回檔案 URL
  "fileSize": integer // File size in bytes
  "errorMessage": string
  "processingDurationSeconds": number (double) // 計算處理時長（秒）
  "createdAt": string (timestamp)
  "startedAt": string (timestamp)
  "completedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userEmail": "[e-mail]",
  "datasetEvaluationId": "550e8400-e29b-41d4-a716-446655440000",
  "datasetEvaluationName": "回應字串",
  "status": {},
  "statusDisplay": "回應字串",
  "fileUrl": "回應字串",
  "fileSize": 456,
  "errorMessage": "回應字串",
  "processingDurationSeconds": 456,
  "createdAt": "回應字串",
  "startedAt": "回應字串",
  "completedAt": "回應字串"
}

---

列出匯出紀錄

GET /api/v1/evaluations/{id}/exports/

回應是這筆評估所有匯出紀錄的陣列，新到舊排序，不分頁。

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Dataset evaluation.
chatbotId	❌	string
datasetId	❌	string
ordering	❌	string	Which field to use when ordering the results.
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
query	❌	string
search	❌	string	A search term.
status	❌	string	`pending`: Pending evaluation ; `running`: Evaluating ; `stopping`: Stopping ; `completed`: Completed ; `partial_completed`: Partially completed ; `failed`: Evaluation failed;

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/exports/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/exports/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/exports/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/exports/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "userEmail": string (email)
      "datasetEvaluationId": string (uuid)
      "datasetEvaluationName": string
      "status": 
      {
      }
      "statusDisplay": string
      "fileUrl": string // 返回檔案 URL
      "fileSize": integer // File size in bytes
      "processingDurationSeconds": number (double) // 計算處理時長（秒）
      "createdAt": string (timestamp)
      "startedAt": string (timestamp)
      "completedAt": 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",
      "userEmail": "[e-mail]",
      "datasetEvaluationId": "550e8400-e29b-41d4-a716-446655440000",
      "datasetEvaluationName": "回應字串",
      "status": {},
      "statusDisplay": "回應字串",
      "fileUrl": "回應字串",
      "fileSize": 456,
      "processingDurationSeconds": 456,
      "createdAt": "回應字串",
      "startedAt": "回應字串",
      "completedAt": "回應字串"
    }
  ]
}

---

編輯評估名稱與描述

PATCH /api/v1/evaluations/{id}/

只接受 name 與 description，其他欄位會被忽略；任何狀態都可以編輯。

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Dataset evaluation.

請求內容

請求參數

欄位	類型	必填	說明
name	string	否
description	string	否

請求結構範例

{
  "name"?: string // 非必填
  "description"?: string // 非必填
}

請求範例值

{
  "name": "範例名稱",
  "description": "範例字串"
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "description": "範例字串"
  }'

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "範例名稱",
    "description": "範例字串"
  };

axios.patch("https://api.maiagent.ai/api/v1/evaluations/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);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "name": "範例名稱",
    "description": "範例字串"
}

response = requests.patch(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => '範例名稱',
            'description' => '範例字串'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string
  "description": string
  "chatbot": 
  {
    "id": string (uuid)
    "name": string
  }
  "dataset": 
  {
    "id": string (uuid)
    "name": string
  }
  "organization": 
  {
    "id": string (uuid)
    "name": string
  }
  "evaluationLlm": 
  {
    "id": string (uuid)
    "name": string
  }
  "status": 
  {
  }
  "startedAt": string (timestamp)
  "completedAt": string (timestamp)
  "totalTestCases": integer
  "completedTestCases": integer
  "passedTestCases": integer // Number of test cases that passed
  "metricScores": object // Detailed score per evaluation metric, such as ground_truth, task_completion and tool_correctness
  "evaluationConfig": object
  "progressPercentage": number (double)
  "overallScore": number (double)
  "passRate": number (double)
  "averageExecutionTimeMs": integer
  "totalExecutionTimeMs": integer
  "chatbotConfig": string
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
  "insights": 
  {
    "summary": string
    "metricStats"?: object // 非必填
    "recommendations"?: object // 非必填
  }
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "chatbot": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "dataset": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "organization": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "evaluationLlm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "status": {},
  "startedAt": "回應字串",
  "completedAt": "回應字串",
  "totalTestCases": 456,
  "completedTestCases": 456,
  "passedTestCases": 456,
  "metricScores": null,
  "evaluationConfig": null,
  "progressPercentage": 456,
  "overallScore": 456,
  "passRate": 456,
  "averageExecutionTimeMs": 456,
  "totalExecutionTimeMs": 456,
  "chatbotConfig": "回應字串",
  "createdAt": "回應字串",
  "updatedAt": "回應字串",
  "insights": {
    "summary": "回應字串",
    "metricStats": null,
    "recommendations": null
  }
}

---

刪除評估

DELETE /api/v1/evaluations/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Dataset evaluation.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

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/evaluations/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);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/evaluations/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)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->delete("https://api.maiagent.ai/api/v1/evaluations/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();
}
?>

回應內容

狀態碼	說明
204	No response body

---