Standard Response Schema
Overview
The testing-api follows a consistent JSON response format for all endpoints. This standardization allows consumers to implement a uniform error-handling and data-parsing logic across their applications.
Every response consists of a root object containing the status of the request, the primary payload, and descriptive metadata.
Base Response Structure
All API responses adhere to the following schema:
{
"success": boolean,
"message": "string",
"data": object | array | null,
"metadata": {
"timestamp": "ISO-8601 string",
"request_id": "uuid",
"version": "string"
},
"errors": array | null
}
Field Definitions
| Field | Type | Description |
| :--- | :--- | :--- |
| success | Boolean | Indicates if the operation was completed successfully. |
| message | String | A human-readable summary of the response or error. |
| data | Object/Array | The primary payload of the response. Returns null if an error occurs. |
| metadata | Object | Operational data including timestamps and request tracking IDs. |
| errors | Array | A list of specific error objects (e.g., validation messages). Returns null on success. |
Success Response
When an operation is successful, the success field is set to true, and the requested information is nested within the data object.
Example: Retrieving a Test Configuration
{
"success": true,
"message": "Configuration retrieved successfully",
"data": {
"test_id": "test_9921",
"model_name": "supervised-ai-v2",
"parameters": {
"temperature": 0.7,
"max_tokens": 512
}
},
"metadata": {
"timestamp": "2023-10-27T10:00:00Z",
"request_id": "req-7b2a9",
"version": "1.0.4"
},
"errors": null
}
Error Response
In the event of a failure (client-side or server-side), the success field is set to false. The errors array provides granular details to help developers debug the issue.
Example: Validation Failure
{
"success": false,
"message": "Validation failed for the requested resource.",
"data": null,
"metadata": {
"timestamp": "2023-10-27T10:05:00Z",
"request_id": "req-8c3b1",
"version": "1.0.4"
},
"errors": [
{
"field": "test_id",
"issue": "Field is required",
"code": "MISSING_PARAM"
},
{
"field": "model_name",
"issue": "Model 'unsupported-ai' does not exist",
"code": "INVALID_VALUE"
}
]
}
Error Object Fields
While the errors array is internal to the specific failure context, it generally includes:
- field: The specific input field that caused the error.
- issue: A descriptive string of why the field failed validation.
- code: A machine-readable string for programmatic handling.
Metadata Objects
The metadata field is included in every response to assist with logging and latency tracking.
| Key | Description |
| :--- | :--- |
| timestamp | The UTC time at which the response was generated. |
| request_id | A unique identifier for the request, essential for debugging with the Supervised AI support team. |
| version | The current version of the API processing the request. |
| latency_ms | (Optional) The time in milliseconds taken by the platform to process the request. |