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 between 0.0 and 1.0 representing 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:

1. Dates: All timestamps are returned in UTC and follow the YYYY-MM-DDTHH:mm:ssZ format.
2. Decimals: Confidence scores and performance metrics are returned as floats with up to 6 decimal places.
3. Strings: All identifiers (IDs) are case-sensitive.
4. Nulls: Fields that are not applicable to a specific request are returned as null rather than being omitted, ensuring consistent object shapes for frontend parsers.