API Contract
Public API specification and response schemas
Stable contract
OpenAPI available
Stability Commitment
Fields documented here are stable. Breaking changes will be versioned and announced. See docs/openapi.json for machine-readable schema.
1. Standard Error Envelope
All API errors return this JSON shape:
{
"error": {
"code": "UNAUTHORIZED",
"message": "Unauthorized",
"details": null,
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
}Error Codes
UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, CONFLICT, INTERNAL_ERROR, SERVICE_UNAVAILABLE, QUOTA_EXCEEDED, NO_ORG_MEMBERSHIPHTTP Status Mapping
UNAUTHORIZED → 401FORBIDDEN → 403NOT_FOUND → 404VALIDATION_ERROR → 400RATE_LIMITED → 4292. MCP Response Shape
GET /api/mcp/tools (anonymous)
{
"mcpVersion": "1",
"tools": [
{
"name": "string",
"description": "string",
"inputSchema": { "type": "object", "properties": { ... } },
"version": "string (optional)",
"longRunning": "boolean (optional)"
}
]
}POST /api/mcp/call (authenticated)
Success (200)
{
"ok": true,
"content": [
{ "type": "json", "json": { /* tool-specific result */ } },
{ "type": "text", "text": "..." }
]
}Error (4xx/5xx)
{
"ok": false,
"error": {
"code": "string",
"message": "string",
"requestId": "uuid"
}
}3. Quality Score Response Shape
GET /api/quality?evaluationId=&action=latest
When score exists (200)
{
"id": 1,
"evaluationRunId": 1,
"evaluationId": 1,
"organizationId": 1,
"score": 85,
"total": 10,
"traceCoverageRate": "1.0",
"provenanceCoverageRate": "0.9",
"breakdown": {},
"flags": [],
"evidenceLevel": "strong",
"scoringVersion": "v1",
"model": null,
"createdAt": "2024-01-15T12:00:00.000Z",
"baselineScore": 80,
"regressionDelta": 5,
"regressionDetected": false,
"baselineMissing": false
}When no scores yet (200)
{
"score": null,
"message": "No quality scores computed yet"
}POST /api/quality (recompute)
{
"success": true,
"runId": 1,
"score": 92,
"breakdown": {},
"flags": [],
"evidenceLevel": "strong",
"scoringVersion": "v1",
"scoringSpecHash": "sha256-hex"
}4. Runs Import
POST /api/evaluations/[id]/runs/import - Import local run results for an existing evaluation.
Headers: Idempotency-Key (optional) — prevents duplicate runs on CI retry
Request Body
{
"environment": "dev",
"importClientVersion": "1.5.0",
"results": [
{ "testCaseId": 1, "status": "passed", "output": "...", "latencyMs": 100 }
]
}Policy: All-or-nothing. Invalid test cases reject the entire request.
Response (201 or 200 on idempotent replay)
{
"runId": 1,
"score": 85,
"flags": [],
"dashboardUrl": "https://.../evaluations/42/runs/1"
}5. Report Payload Schema
POST /api/reports (create report) - Generate signed shareable reports
Request
{ evaluationId, evaluationRunId, expiresInDays?, policyName? }Response (201)
{
"shareToken": "hex",
"shareUrl": "https://.../r/{shareToken}",
"apiUrl": "https://.../api/r/{shareToken}",
"expiresAt": "2024-02-15T00:00:00.000Z"
}Versioning
Error envelope: Stable since v1
Report payload:
version: "2.0"; signatureAlgorithm: "hmac-sha256-v1"Quality:
scoringVersion: "v1"; scoringSpecHash for audit