REST Endpoint Reference

REST Endpoint Reference

This section provides a detailed guide to the RESTful resources available in the Supervised AI Testing API. All endpoints follow standard HTTP conventions and return responses in JSON format.

Base URL

All requests described below are relative to the following base URL:

https://api.supervised.ai/v1/testing

Authentication

All endpoints require a valid API Key passed in the request header.

| Header | Value | Description | | :--- | :--- | :--- | | Authorization | Bearer <YOUR_API_KEY> | Your Supervised AI access token. | | Content-Type | application/json | Required for all POST/PUT requests. |

System Health

Check API Status

Verifies that the API service is operational.

• URL: /health
• Method: GET
• Auth Required: No

Response (200 OK):

{
  "status": "healthy",
  "version": "1.2.0",
  "timestamp": "2023-10-27T10:00:00Z"
}

Test Management

List All Tests

Retrieves a paginated list of all test suites configured for your account.

• URL: /tests
• Method: GET
• Query Parameters:
  • limit (integer, optional): Number of records to return. Default: 20.
  • offset (integer, optional): Number of records to skip. Default: 0.

Response (200 OK):

[
  {
    "test_id": "tst-9921",
    "name": "Object Detection Validation",
    "created_at": "2023-09-15T08:30:00Z",
    "status": "active"
  }
]

Trigger New Test Run

Initiates a specific test suite against your AI model or dataset.

• URL: /tests/{test_id}/run
• Method: POST
• Payload: | Parameter | Type | Description | | :--- | :--- | :--- | | model_version | string | The version of the model to test. | | dataset_id | string | ID of the dataset to use for validation. | | callback_url | string | (Optional) URL to receive a webhook notification upon completion. |

Example Request:

curl -X POST https://api.supervised.ai/v1/testing/tests/tst-9921/run \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model_version": "v2.1.4",
    "dataset_id": "ds-445",
    "callback_url": "https://hooks.yourdomain.com/testing"
  }'

Response (202 Accepted):

{
  "job_id": "job-887221",
  "status": "queued",
  "estimated_completion_time": "300s"
}

Get Test Results

Retrieves the detailed results and metrics of a specific test run.

• URL: /results/{job_id}
• Method: GET

Response (200 OK):

{
  "job_id": "job-887221",
  "metrics": {
    "accuracy": 0.942,
    "f1_score": 0.91,
    "latency_ms": 145
  },
  "failures": [],
  "passed": true
}

Data Validation

Validate Schema

Validates a JSON object against the Supervised AI platform's internal data requirements for training/testing.

• URL: /validate
• Method: POST
• Payload: Any valid JSON object representing a data sample.

Response (200 OK):

{
  "valid": true,
  "errors": [],
  "schema_version": "2023-R4"
}

Response (400 Bad Request):

{
  "valid": false,
  "errors": [
    {
      "field": "image_url",
      "message": "Field is required"
    }
  ]
}

Error Codes

The API uses standard HTTP status codes to indicate the success or failure of an API request.

| Code | Meaning | | :--- | :--- | | 200 | OK - Request successful. | | 201 | Created - Resource created successfully. | | 400 | Bad Request - Invalid parameters or payload. | | 401 | Unauthorized - API Key is missing or invalid. | | 404 | Not Found - The requested resource does not exist. | | 500 | Internal Server Error - An unexpected error occurred on our end. |