Metadata Standards
Request Headers
All requests to the Supervised AI testing API must include standard headers to ensure proper routing, authentication, and versioning.
| Header | Required | Description |
| :--- | :--- | :--- |
| Authorization | Yes | Bearer token for authenticating with the Supervised AI platform (Bearer <token>). |
| Content-Type | Yes | Must be set to application/json. |
| X-Platform-Version | No | Specifies the target platform version. Defaults to latest. |
| X-Request-ID | No | A unique string to track the request through the system. If not provided, the API generates one. |
GET /v1/tests HTTP/1.1
Host: api.supervised.ai
Authorization: Bearer YOUR_API_KEY
X-Request-ID: 7b9e1234-5678-90ab-cdef-1234567890ab
Content-Type: application/json
Pagination
To handle large datasets effectively, the API utilizes a standardized pagination model for all list-based endpoints.
Query Parameters
| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| page | integer | 1 | The page number to retrieve. |
| limit | integer | 20 | The number of items per page (Max: 100). |
Pagination Metadata Object
Responses containing lists are wrapped in an envelope that includes a meta object to assist with client-side navigation.
{
"data": [...],
"meta": {
"pagination": {
"total_items": 150,
"total_pages": 8,
"current_page": 1,
"limit": 20,
"has_next": true,
"has_previous": false
}
}
}
Platform-Specific Metadata
Every API response includes a meta block at the root level. This object contains contextual information about the execution environment and the request lifecycle within the Supervised AI platform.
Standard Metadata Fields
request_id: The unique identifier for the transaction (useful for support and debugging).timestamp: The ISO 8601 UTC timestamp of when the request was processed.version: The current API version serving the request.deprecated: A boolean flag indicating if the endpoint version is slated for removal.
Example Response Structure
{
"data": {
"id": "test_9a8b7c",
"status": "completed",
"result": "pass"
},
"meta": {
"request_id": "req_88223344",
"timestamp": "2023-10-27T10:00:00Z",
"version": "v1.2.0",
"deprecated": false
}
}
Error Metadata
In the event of an internal or validation error, the metadata object is expanded to include specific error codes and debugging hints.
error_code: A machine-readable string identifying the error category.trace_id: An internal identifier used to locate logs in the Supervised AI telemetry system.
{
"error": {
"message": "Invalid test parameters provided.",
"details": "Field 'model_id' is required."
},
"meta": {
"request_id": "req_error_123",
"error_code": "VALIDATION_FAILED",
"trace_id": "trace_0099887766"
}
}