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. |