Response Anatomy

Overview

The Supervised AI Testing API follows a consistent JSON response structure for all endpoints. This predictable format allows developers to implement robust error handling and data parsing logic across their applications.

Every response contains a top-level boolean success indicator, followed by either the requested data or an error object.

Success Response Structure

When a request is processed successfully, the API returns a 2xx HTTP status code. The response body includes the requested payload wrapped in a data object.

{
  "success": true,
  "message": "Resource retrieved successfully",
  "data": {
    "id": "test_726b21",
    "status": "completed",
    "result": 0.982,
    "timestamp": "2023-10-27T10:00:00Z"
  },
  "meta": {
    "request_id": "req_882341"
  }
}

Fields

| Field | Type | Description | | :--- | :--- | :--- | | success | Boolean | Always true for successful operations. | | message | String | A human-readable summary of the operation outcome. | | data | Object/Array | The primary payload. This can be a single object or a list of items. | | meta | Object | Optional. Contains additional context like pagination or request tracking IDs. |

Error Response Structure

If a request fails due to client error (4xx) or server error (5xx), the API returns a structured error object. This ensures that the client can programmatically determine the cause of the failure.

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The 'model_id' field is required.",
    "details": [
      {
        "field": "model_id",
        "issue": "missing"
      }
    ]
  },
  "meta": {
    "request_id": "req_991022"
  }
}

Fields

| Field | Type | Description | | :--- | :--- | :--- | | success | Boolean | Always false for failed operations. | | error.code | String | A machine-readable string identifying the error type (e.g., UNAUTHORIZED, NOT_FOUND). | | error.message | String | A descriptive message explaining why the error occurred. | | error.details | Array | Optional. An array of objects providing granular info (e.g., specific field validation errors). |

Pagination (Collection Anatomy)

For endpoints that return lists of resources, the data field contains an array, and the meta object is used to provide pagination details.

{
  "success": true,
  "data": [
    { "id": "job_1" },
    { "id": "job_2" }
  ],
  "meta": {
    "total_count": 150,
    "page": 1,
    "limit": 20,
    "has_next": true
  }
}

Metadata Details

• total_count: The total number of records available in the system.
• page: The current page index requested.
• limit: The number of items returned per page.
• has_next: A boolean indicating if another page of data is available.

Standard HTTP Status Codes

The Testing API uses standard HTTP semantics to communicate the status of requests:

• 200 OK: Request succeeded.
• 201 Created: Resource successfully created.
• 400 Bad Request: The request was invalid (check error.details).
• 401 Unauthorized: API key is missing or invalid.
• 403 Forbidden: Authenticated but lacks permission for the resource.
• 404 Not Found: The requested resource does not exist.
• 429 Too Many Requests: Rate limit exceeded.
• 500 Internal Server Error: An unexpected error occurred on our end.