Response Anatomy
Overview
The Supervised AI Testing API follows a consistent JSON response structure for all endpoints. This predictable format allows developers to implement robust error handling and data parsing logic across their applications.
Every response contains a top-level boolean success indicator, followed by either the requested data or an error object.
Success Response Structure
When a request is processed successfully, the API returns a 2xx HTTP status code. The response body includes the requested payload wrapped in a data object.
{
"success": true,
"message": "Resource retrieved successfully",
"data": {
"id": "test_726b21",
"status": "completed",
"result": 0.982,
"timestamp": "2023-10-27T10:00:00Z"
},
"meta": {
"request_id": "req_882341"
}
}
Fields
| Field | Type | Description |
| :--- | :--- | :--- |
| success | Boolean | Always true for successful operations. |
| message | String | A human-readable summary of the operation outcome. |
| data | Object/Array | The primary payload. This can be a single object or a list of items. |
| meta | Object | Optional. Contains additional context like pagination or request tracking IDs. |
Error Response Structure
If a request fails due to client error (4xx) or server error (5xx), the API returns a structured error object. This ensures that the client can programmatically determine the cause of the failure.
{
"success": false,
"error": {
"code": "INVALID_PARAMETER",
"message": "The 'model_id' field is required.",
"details": [
{
"field": "model_id",
"issue": "missing"
}
]
},
"meta": {
"request_id": "req_991022"
}
}
Fields
| Field | Type | Description |
| :--- | :--- | :--- |
| success | Boolean | Always false for failed operations. |
| error.code | String | A machine-readable string identifying the error type (e.g., UNAUTHORIZED, NOT_FOUND). |
| error.message | String | A descriptive message explaining why the error occurred. |
| error.details | Array | Optional. An array of objects providing granular info (e.g., specific field validation errors). |
Pagination (Collection Anatomy)
For endpoints that return lists of resources, the data field contains an array, and the meta object is used to provide pagination details.
{
"success": true,
"data": [
{ "id": "job_1" },
{ "id": "job_2" }
],
"meta": {
"total_count": 150,
"page": 1,
"limit": 20,
"has_next": true
}
}
Metadata Details
total_count: The total number of records available in the system.page: The current page index requested.limit: The number of items returned per page.has_next: A boolean indicating if another page of data is available.
Standard HTTP Status Codes
The Testing API uses standard HTTP semantics to communicate the status of requests:
200 OK: Request succeeded.201 Created: Resource successfully created.400 Bad Request: The request was invalid (checkerror.details).401 Unauthorized: API key is missing or invalid.403 Forbidden: Authenticated but lacks permission for the resource.404 Not Found: The requested resource does not exist.429 Too Many Requests: Rate limit exceeded.500 Internal Server Error: An unexpected error occurred on our end.