Request Parameters

Request Headers

All requests to the testing-api must include standard HTTP headers to ensure proper authentication and data handling.

| Header | Type | Required | Description | | :--- | :--- | :--- | :--- | | Authorization | string | Yes | Standard Bearer token authentication. Format: Bearer <YOUR_API_KEY>. | | Content-Type | string | Yes | Must be set to application/json. | | X-Platform-Version | string | No | Specifies the version of the Supervised AI platform to target. Defaults to latest. |

Query Parameters

Query parameters are primarily used for GET requests to filter, sort, and paginate through test results, model logs, or datasets.

Pagination and Sorting

| Parameter | Type | Default | Description | | :--- | :--- | :--- | :--- | | limit | integer | 20 | The number of records to return per page. Max value: 100. | | offset | integer | 0 | The number of records to skip before starting to return results. | | sort_by | string | created_at | The field used to sort the results (e.g., status, updated_at). | | order | string | desc | The sort order. Options: asc or desc. |

Filtering

| Parameter | Type | Description | | :--- | :--- | :--- | | status | string | Filter tests by status. Valid values: pending, running, completed, failed. | | model_id | uuid | Filter results associated with a specific AI model identifier. | | test_type | string | Filter by the specific test suite type (e.g., accuracy, latency, drift). |

Request Body Parameters

For POST, PUT, and PATCH requests, the API expects a JSON-formatted body. Below are the common parameters used across the platform's testing endpoints.

Test Execution Object

When initiating a new test run, the following parameters are required in the request body:

| Parameter | Type | Required | Description | | :--- | :--- | :--- | :--- | | test_suite_id | string | Yes | The unique identifier for the pre-defined test suite. | | target_model_uri | string | Yes | The endpoint or internal path of the model being tested. | | parameters | object | No | A key-value map of configuration overrides for the test (e.g., {"threshold": 0.85}). | | notify_webhook | string | No | A URL to receive a POST request upon test completion. |

Dataset Configuration

Used when uploading or assigning a dataset to a specific testing cycle:

| Parameter | Type | Required | Description | | :--- | :--- | :--- | :--- | | dataset_id | string | Yes | Reference to a dataset hosted on the Supervised AI platform. | | split | string | No | The specific data split to use. Options: train, validation, test. |

Examples

Example Request Body (Initiating a Test)

POST /v1/tests/run
Content-Type: application/json
Authorization: Bearer pb_392849203

{
  "test_suite_id": "suite_nlp_validation_v2",
  "target_model_uri": "models/sentiment-analysis-beta",
  "parameters": {
    "confidence_threshold": 0.75,
    "batch_size": 32
  },
  "notify_webhook": "https://hooks.internal-app.com/test-results"
}

Example Query String (Filtering Results)

GET /v1/results?status=completed&limit=10&sort_by=latency&order=asc