Request Headers & Params

Authentication

All requests to the Supervised AI Testing API must be authenticated using a Bearer token. This token should be included in the Authorization header of every request.

| Header | Type | Required | Description | | :--- | :--- | :--- | :--- | | Authorization | String | Yes | The API key provided by the Supervised AI dashboard. Format: Bearer <YOUR_API_TOKEN> |

Standard Request Headers

The following headers are required for the API to process requests correctly and to ensure compatibility with standardized response formats.

| Header | Value | Description | | :--- | :--- | :--- | | Content-Type | application/json | Specifies that the request body is in JSON format. | | Accept | application/json | Informs the server that the client expects a JSON response. | | X-API-Version | string | (Optional) Specifies a target API version. Defaults to the latest stable release. | | X-Request-ID | string | (Optional) A unique UUID for tracing requests across the Supervised AI infrastructure. |

Example Header Implementation

curl -X GET "https://api.supervised.ai/v1/tests" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 7b2a-4f31-89d2"

Global Query Parameters

These parameters can be appended to most GET endpoints to control the volume and scope of the data returned.

| Parameter | Type | Default | Description | | :--- | :--- | :--- | :--- | | limit | Integer | 20 | The maximum number of records to return. Max: 100. | | offset | Integer | 0 | The number of records to skip before starting to return results. | | sort | String | created_at | The field by which to sort results (e.g., updated_at, status). | | order | String | desc | The sort order. Options: asc (ascending) or desc (descending). | | status | String | all | Filter results by test status. Options: queued, running, completed, failed. |

Endpoint-Specific Parameters

For endpoints involving specific test suites or model evaluations, the following parameters are frequently utilized:

Test Filtering

When querying the /testing-api/results endpoint, use these parameters to narrow down specific test instances.

• test_suite_id (String): Filter results belonging to a specific suite ID.
• model_version (String): Filter results generated by a specific AI model version.
• environment (String): Filter by the execution environment (e.g., staging, production).

Code Example: Requesting Paginated Test Results

GET /v1/testing-api/results?limit=10&offset=20&status=failed&order=desc HTTP/1.1
Host: api.supervised.ai
Authorization: Bearer <YOUR_API_TOKEN>
Content-Type: application/json

Error Handling via Headers

If a request fails due to header or parameter issues, the API returns a standard HTTP error code. Ensure your client logic handles the following:

• 401 Unauthorized: Missing or invalid Authorization header.
• 406 Not Acceptable: The Accept header is missing or set to a non-JSON value.
• 422 Unprocessable Entity: Valid JSON was provided, but query parameters (like limit) exceed allowed bounds.