API Reference

REST APIs for agents, execution, analytics, policy, and developer actions.

API Overview

AI Test Harness exposes RESTful APIs for programmatic access to all platform capabilities. All endpoints require authentication via API key.

Authentication

Include your API key in the Authorization header:

bash

curl https://api.aitestharness.com/v1/test-plans \
  -H "Authorization: Bearer ath_your_api_key_here"

Base URL

bash

Production:  https://api.aitestharness.com/v1
Staging:     https://staging-api.aitestharness.com/v1
Local:       http://localhost:8080/api/v1

Test Plans API

Create Test Plan

bash

POST /v1/test-plans

Request Body:
{
  "name": "Release v2.3.0",
  "changeSet": [
    { "file": "src/checkout/payment.ts", "impact": "high" }
  ],
  "environments": ["staging"],
  "priority": "high"
}

Response:
{
  "id": "plan_abc123",
  "status": "pending",
  "tests": [
    {
      "id": "test_xyz789",
      "name": "Payment flow validation",
      "type": "ui",
      "priority": "high"
    }
  ],
  "createdAt": "2026-03-16T10:30:00Z"
}

Get Test Plan

bash

GET /v1/test-plans/{planId}

Response:
{
  "id": "plan_abc123",
  "name": "Release v2.3.0",
  "status": "completed",
  "coverage": 87,
  "passRate": 94,
  "totalTests": 45,
  "passed": 42,
  "failed": 3
}

List Test Plans

bash

GET /v1/test-plans?status=completed&limit=10

Response:
{
  "plans": [...],
  "total": 127,
  "page": 1,
  "pageSize": 10
}

Execution API

Execute Test Plan

bash

POST /v1/executions

Request Body:
{
  "testPlanId": "plan_abc123",
  "environment": "staging",
  "parallelism": 5
}

Response:
{
  "id": "exec_def456",
  "status": "running",
  "startedAt": "2026-03-16T10:35:00Z",
  "progress": {
    "completed": 12,
    "running": 5,
    "pending": 28
  }
}

Get Execution Status

bash

GET /v1/executions/{execId}

Response:
{
  "id": "exec_def456",
  "status": "completed",
  "duration": 342,
  "results": {
    "passed": 42,
    "failed": 3,
    "skipped": 0
  },
  "failures": [...]
}

Agents API

List Agents

bash

GET /v1/agents

Response:
{
  "agents": [
    {
      "id": "agent_discovery",
      "name": "Discovery Agent",
      "status": "active",
      "lastRun": "2026-03-16T09:15:00Z"
    },
    {
      "id": "agent_planning",
      "name": "Test Planning Agent",
      "status": "active",
      "lastRun": "2026-03-16T10:30:00Z"
    }
  ]
}

Invoke Agent

bash

POST /v1/agents/{agentId}/invoke

Request Body:
{
  "task": "analyze-api-changes",
  "parameters": {
    "baseUrl": "https://api.example.com",
    "version": "v2"
  }
}

Response:
{
  "executionId": "agent_exec_ghi789",
  "status": "running"
}

Analytics API

Get Release Readiness

bash

GET /v1/analytics/release-readiness?version=v2.3.0

Response:
{
  "version": "v2.3.0",
  "score": 87,
  "confidence": "high",
  "metrics": {
    "coverage": 89,
    "passRate": 94,
    "flakyTests": 2,
    "criticalFailures": 0
  },
  "recommendation": "Ready for production deployment"
}

Get Failure Clusters

bash

GET /v1/analytics/failure-clusters?days=7

Response:
{
  "clusters": [
    {
      "id": "cluster_auth",
      "category": "Authentication",
      "count": 12,
      "rootCause": "JWT token expiration",
      "affectedTests": [...]
    }
  ]
}

Webhooks

Configure webhooks to receive real-time notifications:

bash

POST /v1/webhooks

Request Body:
{
  "url": "https://your-app.com/webhook",
  "events": ["test.completed", "test.failed", "execution.completed"],
  "secret": "your_webhook_secret"
}

Webhook Payload:
{
  "event": "test.failed",
  "timestamp": "2026-03-16T10:45:00Z",
  "data": {
    "testId": "test_xyz789",
    "executionId": "exec_def456",
    "error": "..."
  }
}

Rate Limits

Starter: 100 requests/minute
Team: 1,000 requests/minute
Enterprise: Custom limits

SDKs

Official SDKs available for:

Node.js/TypeScript
Python
Go
Java

bash

npm install @ai-test-harness/sdk

import { TestHarness } from '@ai-test-harness/sdk';

const client = new TestHarness({
  apiKey: process.env.AI_TEST_HARNESS_API_KEY
});

const plan = await client.testPlans.create({
  name: 'Release v2.3.0',
  changeSet: [...]
});

const execution = await client.executions.create({
  testPlanId: plan.id
});

await execution.wait();