Response Schema Overview

Consistency and Structure

All endpoints in the Supervised AI Testing API adhere to a standardized JSON response format. This consistency ensures that client-side integrations can implement a single handling logic for parsing data, managing pagination, and catching errors.

Base Response Envelope

Every response returned by the API is wrapped in a standard envelope. This structure allows developers to verify the status of a request before deep-parsing the payload.

{
  "success": true,
  "status_code": 200,
  "message": "Request processed successfully",
  "data": {},
  "meta": {}
}

Root-Level Fields

| Field | Type | Description | | :--- | :--- | :--- | | success | Boolean | Indicates if the operation was successful. | | status_code | Integer | The HTTP status code of the response. | | message | String | A human-readable summary of the result or error. | | data | Object | Array | The primary payload of the response. Can be null if no data is returned. | | meta | Object | Supplemental information, such as pagination or rate limit status. |

Success Responses

When a request is successful (typically 2xx range), the data field contains the requested resources.

Single Resource

For requests fetching a specific item (e.g., GET /models/:id), data is returned as a single object.

{
  "success": true,
  "status_code": 200,
  "data": {
    "id": "model_9982",
    "name": "Supervised-BERT-v2",
    "status": "active"
  }
}

Collection of Resources

For list endpoints (e.g., GET /test-suites), data is returned as an array. These responses typically include a meta object for pagination.

{
  "success": true,
  "status_code": 200,
  "data": [
    { "id": "ts_1", "name": "Regression Suite" },
    { "id": "ts_2", "name": "Smoke Test" }
  ],
  "meta": {
    "pagination": {
      "total_items": 150,
      "current_page": 1,
      "per_page": 20,
      "total_pages": 8
    }
  }
}

Error Responses

In the event of a failure (4xx or 5xx range), the success field is set to false. The data field is usually null, and additional context is provided in the error object (if available) or the message string.

Error Object Structure

{
  "success": false,
  "status_code": 400,
  "message": "Validation Failed",
  "errors": [
    {
      "field": "test_id",
      "issue": "Field is required"
    }
  ]
}

Common Status Codes

• 400 Bad Request: The request was unacceptable, often due to missing a required parameter.
• 401 Unauthorized: No valid API key provided.
• 403 Forbidden: The API key does not have permissions to perform the request.
• 404 Not Found: The requested resource doesn't exist.
• 429 Too Many Requests: Hit the rate limit.
• 500 Internal Server Error: Something went wrong on the Supervised AI platform.

Data Types & Formatting

To ensure compatibility across different SDKs and languages, the API follows these formatting conventions:

• Dates: All timestamps are returned in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) in UTC.
• IDs: Unique identifiers are generally returned as strings (e.g., UUIDs or prefixed strings).
• Enums: Statuses and types are returned as lowercase strings (e.g., "pending", "completed", "failed").