Response Objects

Response Structure

All responses returned by the Testing API follow a standardized JSON envelope. This consistency allows consumers to implement uniform error handling and data parsing logic across all endpoints within the Supervised AI platform.

Base Envelope

Every response contains the following top-level fields:

| Field | Type | Description | | :--- | :--- | :--- | | success | boolean | Indicates if the operation was successful. | | status_code | integer | The HTTP status code (e.g., 200, 400, 500). | | message | string | A human-readable summary of the response or error. | | data | object \| array \| null | The actual payload of the response. | | metadata | object | Contextual information such as timestamps and request IDs. | | errors | array | A list of error objects (present only if success is false). |

Standard Data Object

The data object varies depending on the endpoint but typically follows these patterns:

Single Resource Response

When retrieving a specific test case, model evaluation, or configuration.

{
  "success": true,
  "status_code": 200,
  "message": "Resource retrieved successfully",
  "data": {
    "id": "test_98765",
    "name": "Validation_Set_Alpha",
    "status": "completed",
    "results": {
      "accuracy": 0.94,
      "f1_score": 0.92
    }
  },
  "metadata": {
    "timestamp": "2023-10-27T10:00:00Z",
    "version": "v1.0.4"
  }
}

Collection Response (Lists)

When querying multiple items, the data field contains an array, and the metadata field includes pagination details.

{
  "success": true,
  "status_code": 200,
  "data": [
    { "id": "test_1", "status": "passed" },
    { "id": "test_2", "status": "failed" }
  ],
  "metadata": {
    "pagination": {
      "total_count": 150,
      "page": 1,
      "limit": 20,
      "has_next": true
    },
    "request_id": "req_550e8400-e29b"
  }
}

Error Handling

When success is false, the data field will be null, and the errors array will be populated. This structure is designed to help developers debug integration issues or display validation errors to end-users.

Error Object Schema

| Field | Type | Description | | :--- | :--- | :--- | | code | string | A machine-readable error constant (e.g., VALIDATION_ERROR). | | field | string | (Optional) The specific input field that caused the error. | | message | string | A detailed description of what went wrong. |

Example Error Response

{
  "success": false,
  "status_code": 422,
  "message": "Request validation failed",
  "data": null,
  "errors": [
    {
      "code": "MISSING_REQUIRED_FIELD",
      "field": "model_id",
      "message": "The model_id field is required to initiate a test."
    },
    {
      "code": "INVALID_FORMAT",
      "field": "confidence_threshold",
      "message": "Value must be a float between 0 and 1."
    }
  ],
  "metadata": {
    "timestamp": "2023-10-27T10:05:12Z",
    "trace_id": "err_bc12345"
  }
}

HTTP Status Codes

The API utilizes standard HTTP status codes to communicate the result of an API request:

• 200 OK: The request was successful.
• 201 Created: A new resource (e.g., a test suite) was successfully created.
• 400 Bad Request: The request was invalid (e.g., malformed JSON).
• 401 Unauthorized: Authentication credentials are missing or invalid.
• 403 Forbidden: You do not have permission to access the resource.
• 404 Not Found: The requested resource does not exist.
• 422 Unprocessable Entity: Used for validation errors.
• 500 Internal Server Error: An unexpected error occurred on the Supervised AI platform.