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"
  }
}