Response Schema Definitions
Response Schema Overview
The testing-api utilizes a standardized JSON structure for all API responses. This consistency ensures that consumers can implement uniform parsing logic for success states, error handling, and metadata processing across the Supervised AI platform.
All responses follow a predictable wrapper format containing three top-level keys: status, data, and meta.
The Base Response Object
Every response returned by the API adheres to the following root schema:
| Field | Type | Description |
| :--- | :--- | :--- |
| status | string | The result of the request. Common values: success, error, partial_success. |
| data | object | array | The primary payload of the response. Structure varies by endpoint. |
| meta | object | Contextual information about the request (e.g., timestamps, model versions). |
| error | object | (Optional) Present only when status is not success. |
Example Structure
{
"status": "success",
"data": {
"id": "test_9a8b7c",
"prediction": "positive",
"confidence": 0.982
},
"meta": {
"timestamp": "2023-10-27T10:00:00Z",
"api_version": "v1.2.0",
"latency_ms": 145
}
}
Data Object Definitions
The data object is the core payload. In the context of the testing API, it typically contains model inference results or test execution details.
Prediction Payload
When querying testing endpoints for AI inference, the data block includes:
id(string): A unique identifier for the specific test transaction.prediction(mixed): The output of the model. This may be a string (classification), a number (regression), or a boolean.confidence(float): A value between0.0and1.0representing the model's certainty.labels(array): An array of strings representing the categories identified by the model.
Metadata (meta) Definitions
The meta object provides telemetry and audit information critical for debugging and monitoring performance within the Supervised AI ecosystem.
| Field | Type | Description |
| :--- | :--- | :--- |
| timestamp | ISO-8601 String | The exact time the response was generated. |
| model_version | string | The specific version of the AI model used for the request. |
| request_id | UUID | A unique trace ID to correlate logs across services. |
| processing_time | float | The time taken by the internal engine to process the data (in seconds). |
Error Schema Definitions
When a request fails (Status Codes 4xx or 5xx), the data field may be null or omitted, and an error object is provided.
Error Object Fields
code(string): A machine-readable error constant (e.g.,UNAUTHORIZED_ACCESS,MODEL_TIMEOUT).message(string): A human-readable description of the error.details(array): An optional list of specific validation failures or sub-errors.
Example Error Response
{
"status": "error",
"error": {
"code": "VALIDATION_FAILED",
"message": "The provided input format is not supported.",
"details": [
{
"field": "image_url",
"issue": "URL is unreachable or private."
}
]
},
"meta": {
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2023-10-27T10:05:00Z"
}
}
Standard Type Constraints
To ensure interoperability, the following constraints are applied to the schema:
- Dates: All timestamps are returned in UTC and follow the
YYYY-MM-DDTHH:mm:ssZformat. - Decimals: Confidence scores and performance metrics are returned as floats with up to 6 decimal places.
- Strings: All identifiers (IDs) are case-sensitive.
- Nulls: Fields that are not applicable to a specific request are returned as
nullrather than being omitted, ensuring consistent object shapes for frontend parsers.