Standard Response Format

Overview

To ensure consistent integration across the Supervised AI platform, the Testing API utilizes a unified response envelope. This standardized structure allows client applications to predictably parse results, handle errors, and provide feedback to users regardless of the specific endpoint being queried.

The Response Envelope

Every response returned by the API follows this baseline JSON schema:

{
  "success": boolean,
  "message": string,
  "data": object | array | null,
  "error": {
    "code": string,
    "details": any
  } | null,
  "meta": object | null
}

Field Definitions

| Field | Type | Description | | :--- | :--- | :--- | | success | boolean | Indicates whether the operation was completed successfully. Use this as the primary gate for your logic. | | message | string | A human-readable summary of the response. This is suitable for logging or direct display in UI notifications. | | data | object / array | The primary payload of the request. If the request returns no data (e.g., a DELETE operation), this will be null. | | error | object | Detailed error information. This field is populated only when success is false. | | meta | object | Optional metadata, such as pagination details (total counts, page size) or processing timestamps. |

Usage Examples

Successful Data Retrieval

When a request is processed successfully, the success flag is set to true, and the error field remains null.

{
  "success": true,
  "message": "Test results retrieved successfully.",
  "data": {
    "test_id": "api-9923",
    "status": "passed",
    "latency_ms": 124
  },
  "error": null,
  "meta": {
    "request_id": "req_88219"
  }
}

Handling Errors

If a request fails due to validation, authentication, or server-side issues, success will be false. The error object provides a machine-readable code for programmatic handling.

{
  "success": false,
  "message": "Validation failed for the provided payload.",
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "details": {
      "field": "test_id",
      "issue": "Field is required"
    }
  },
  "meta": null
}

Best Practices for Consumers

1. Check success First: Always verify the success boolean before attempting to access the data property.
2. Graceful Error Mapping: Use the error.code field to map API errors to localized strings or specific UI states within your application.
3. Null Safety: Ensure your parsers handle data as null for operations that do not return a body, or for cases where the requested resource is not found.
4. Logging: Always log the meta.request_id (if available) when reporting issues to Supervised AI support to expedite troubleshooting.