API Documentation

Comprehensive guide to integrating with our API endpoints

Getting Started

Learn how to authenticate and make your first API request

View Guide

How It Works

Step-by-step guide to integrating the library in your application

Learn More

API Reference

Detailed information about API endpoints and response formats

Explore Endpoints

FAQ

Common questions about using our API and troubleshooting

View FAQs

Authentication

API Key Authentication

All API requests require authentication using your API key. You can find your API key in the dashboard.

// Example: Including your API key in the header
fetch('https://api.example.com/tests', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
})

Note: Never share your API key publicly or include it in client-side code.

How It Works

Quick Integration Guide

1. Create Instance

Configure your AI model providers with API keys:

// Configure API providers and custom endpoints
const config = configureModels({
  openai: { 
    apiKey: process.env.OPENAI_API_KEY
  },
  anthropic: { 
    apiKey: process.env.ANTHROPIC_KEY
  }
  // More models available here...
});

2. Build Tests

Define test cases with expected responses and requirements:

const colorTest = defineAiTest("color-question", {
  cases: {
    prompt: "What color is Big Bird?",
    match: "yellow" 
  },
  maxPrice: 0.01,   // Max cost per one million tokens
  minAccuracy: 0.90,  // Minimum of 90% accuracy
  maxLatency: 500,  // Max response time (ms)
  priority: "accuracy",  // Prioritize accuracy over time & cost
  retries: 3  // Model sample size
});

3. Run Tests

Use our API for persistent storage of test results:

// Create storage instance using API keys
const storage = createStorage({
  type: 'api',
  apiKey: process.env.RADAR_API_KEY,
  endpoint: '/api/tests'
});

// Run tests against all models
await runAiTests(
  [colorTest, mathTests], 
  storage
);

4. Use in Production

Get optimal models on initialization for immediate use:

// On app initialization:
// Get all best models at once
const models = initializeModels({
  apiKey: process.env.RADAR_API_KEY,
  tests: ["color-question", "math"]
});

// In production - no await needed
const colorModel = models.get("color-question");
// { primary: "gpt-4o-mini", 
//   secondary: "claude-3.5-haiku" }

// Use the optimal model directly
const response = getAIResponse(
  "What color is Big Bird?",
  colorModel.primary
);

Key Benefits

Test reliability across 25+ AI model providers
Auto-select optimal models based on your priorities (cost, accuracy, latency)
Persistent storage of test results through our API
Cached model selection for immediate production use
Automatic fallback to secondary models
CI/CD integration via GitHub Actions

API Endpoints

GET/api/tests

Retrieve all tests or filtered tests based on query parameters.

Query Parameters

Parameter	Type	Description
accountId	string	Filter tests by account ID
testName	string	Filter tests by name (case-insensitive partial match)
status	string	Filter tests by status (e.g., "running", "passed", "failed")

Response

// Success (200 OK)
[
  {
    "id": "string",
    "accountId": "string",
    "testName": "string",
    "bestModel": "string" | null,
    "accuracy": number | null,
    "cost": number | null,
    "latency": number | null,
    "lastRun": "string" | null,
    "status": "string" | null,
    "secondBestModel": "string" | null,
    "topPriority": "string" | null,
    "secondPriority": "string" | null,
    "createdAt": "string",
    "updatedAt": "string"
  }
]

// Error (500 Internal Server Error)
{
  "error": "Failed to retrieve tests",
  "details": "Error message"
}

POST/api/tests

Create a new test.

Request Body

{
  "accountId": "string", // Required
  "testName": "string",  // Required
  "bestModel": "string" | null,
  "accuracy": number | null,
  "cost": number | null,
  "latency": number | null,
  "status": "string" | null,
  "secondBestModel": "string" | null,
  "topPriority": "string" | null,
  "secondPriority": "string" | null,
  "accuracyThreshold": number | null,
  "costThreshold": number | null,
  "latencyThreshold": number | null
}

Response

// Success (201 Created)
{
  "id": "string",
  "accountId": "string",
  "testName": "string",
  "bestModel": "string" | null,
  "accuracy": number | null,
  "cost": number | null,
  "latency": number | null,
  "lastRun": "string" | null,
  "status": "string" | null,
  "secondBestModel": "string" | null,
  "topPriority": "string" | null,
  "secondPriority": "string" | null,
  "createdAt": "string",
  "updatedAt": "string"
}

// Error (400 Bad Request)
{
  "error": "Missing required fields: accountId, testName"
}

// Error (500 Internal Server Error)
{
  "error": "Failed to create test",
  "details": "Error message"
}

GET/api/tests/[id]

Retrieve a specific test by ID.

Path Parameters

Parameter	Type	Description
id	string	The ID of the test to retrieve

Response

// Success (200 OK)
{
  "id": "string",
  "accountId": "string",
  "testName": "string",
  "bestModel": "string" | null,
  "accuracy": number | null,
  "cost": number | null,
  "latency": number | null,
  "lastRun": "string" | null,
  "status": "string" | null,
  "secondBestModel": "string" | null,
  "topPriority": "string" | null,
  "secondPriority": "string" | null,
  "createdAt": "string",
  "updatedAt": "string",
  "history": [
    {
      "id": "string",
      "testId": "string",
      "accountId": "string",
      "testName": "string",
      "bestModel": "string" | null,
      "accuracy": number | null,
      "cost": number | null,
      "latency": number | null,
      "runDate": "string",
      "status": "string" | null,
      "secondBestModel": "string" | null,
      "topPriority": "string" | null,
      "secondPriority": "string" | null
    }
  ]
}

// Error (404 Not Found)
{
  "error": "Test not found"
}

// Error (500 Internal Server Error)
{
  "error": "Failed to retrieve test",
  "details": "Error message"
}

PUT/api/tests/[id]

Update a specific test by ID.

Path Parameters

Parameter	Type	Description
id	string	The ID of the test to update

Request Body

{
  "testName": "string",
  "bestModel": "string" | null,
  "accuracy": number | null,
  "cost": number | null,
  "latency": number | null,
  "lastRun": "string" | null,
  "status": "string" | null,
  "secondBestModel": "string" | null,
  "topPriority": "string" | null,
  "secondPriority": "string" | null,
  "accuracyThreshold": number | null,
  "costThreshold": number | null,
  "latencyThreshold": number | null
}

Response

// Success (200 OK)
{
  "id": "string",
  "accountId": "string",
  "testName": "string",
  "bestModel": "string" | null,
  "accuracy": number | null,
  "cost": number | null,
  "latency": number | null,
  "lastRun": "string" | null,
  "status": "string" | null,
  "secondBestModel": "string" | null,
  "topPriority": "string" | null,
  "secondPriority": "string" | null,
  "createdAt": "string",
  "updatedAt": "string"
}

// Error (404 Not Found)
{
  "error": "Test not found"
}

// Error (500 Internal Server Error)
{
  "error": "Failed to update test",
  "details": "Error message"
}

DELETE/api/tests/[id]

Delete a specific test by ID.

Path Parameters

Parameter	Type	Description
id	string	The ID of the test to delete

Response

// Success (200 OK)
{
  "message": "Test deleted successfully"
}

// Error (404 Not Found)
{
  "error": "Test not found"
}

// Error (500 Internal Server Error)
{
  "error": "Failed to delete test",
  "details": "Error message"
}

Frequently Asked Questions

How do I handle errors?

API errors follow a standard format with an error message and details field. Always check the HTTP status code and handle errors appropriately in your application.

What are the rate limits?

Rate limits depend on your plan. Free tier accounts are limited to 100 requests per minute. Check your plan details for specific limits.

How is logging handled?

All API requests and errors are logged for diagnostic purposes. We keep logs for 30 days. Sensitive information like API keys is never logged.

How do I upgrade my API plan?

You can upgrade your plan from the dashboard under the "Account" section. Changes take effect immediately.

Need Help?

Can't find what you're looking for? Our support team is here to help.

Contact Support Report an Issue