Response Object Schemas
Overview
The testing-api follows a standardized response format to ensure consistency across the Supervised AI platform. All API responses are returned as JSON objects containing a status indicator, a descriptive message, and the primary payload.
By adhering to these schemas, client-side integrations can implement uniform error handling and data parsing logic.
Standard Success Response
A success response is returned for any request that is processed correctly by the server (typically HTTP status codes 200, 201, or 204).
Schema Definition
| Field | Type | Description |
| :--- | :--- | :--- |
| success | boolean | Always true for successful operations. |
| message | string | A brief human-readable summary of the result. |
| data | object | array | The primary resource or result requested. |
| metadata | object | (Optional) Supplemental information such as pagination or execution metrics. |
Usage Example
{
"success": true,
"message": "Test execution retrieved successfully",
"data": {
"id": "test_98765",
"status": "completed",
"accuracy": 0.98,
"latency_ms": 120
},
"metadata": {
"timestamp": "2023-10-27T10:00:00Z",
"version": "v1.2.0"
}
}
Standard Error Response
When a request fails due to client error (4xx) or server error (5xx), the API returns a structured error object. This allows developers to programmatically handle specific failure states.
Schema Definition
| Field | Type | Description |
| :--- | :--- | :--- |
| success | boolean | Always false for failed operations. |
| error | object | Container for error details. |
| error.code | string | A machine-readable string (SNAKE_CASE) identifying the error type. |
| error.message | string | A human-readable explanation of what went wrong. |
| error.details | object | (Optional) Granular details, such as validation errors per field. |
Usage Example
{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "The provided model configuration is invalid.",
"details": {
"temperature": "Value must be between 0 and 1.",
"max_tokens": "Field is required."
}
}
}
Paginated Response Schema
For endpoints that return lists of resources (e.g., test logs or dataset entries), the metadata object is populated with pagination details.
Metadata Fields
| Field | Type | Description |
| :--- | :--- | :--- |
| total_count | integer | Total number of items available across all pages. |
| page | integer | The current page number. |
| limit | integer | The number of items requested per page. |
| has_next | boolean | Indicates if a subsequent page of data exists. |
Usage Example
{
"success": true,
"message": "Datasets fetched successfully",
"data": [
{ "id": "ds_01", "name": "Production_Eval" },
{ "id": "ds_02", "name": "Edge_Cases" }
],
"metadata": {
"total_count": 45,
"page": 1,
"limit": 2,
"has_next": true
}
}
Common Error Codes
| Code | Description |
| :--- | :--- |
| AUTHENTICATION_REQUIRED | The request missing a valid API key or token. |
| RESOURCE_NOT_FOUND | The requested ID does not exist in the database. |
| RATE_LIMIT_EXCEEDED | Too many requests have been sent in a short period. |
| INTERNAL_SERVER_ERROR | An unexpected failure occurred on the platform. |
| INVALID_PAYLOAD | The JSON body is malformed or violates the schema. |