POST
/api/v1/datasets/synthesizeGenerate synthetic evaluation cases from a system prompt or document
T2.5b — wraps the @evalguard/core Synthesizer behind a server-side endpoint. Requires projectId plus at least one of systemPrompt (10-8000 chars) or documentText (10-50000 chars). Generates `count` test cases (1-200, default 20) using 1 to 7 of the 10 registered evolution strategies — reasoning, multi-context, comparative, hypothetical, edge-case, adversarial, paraphrase, concretizing, constrained, in-breadth — defaulting to reasoning + edge-case + adversarial. The LLM is always OpenAI gpt-4o-mini, called server-side with the org's BYOK OpenAI key when one is stored and the platform key otherwise (503 LLM_UNAVAILABLE if neither); every call is metered to cost_ledger and cost_entries on both the success and failure paths. Editor role, datasets:create, 5 requests/min. Returns { cases, stats, cost } — save the cases via POST /api/v1/datasets.
Authentication
Send Authorization: Bearer YOUR_API_KEY on every request. Generate API keys at /dashboard/settings/api-keys.
Request body required
Example
{
"projectId": "00000000-0000-0000-0000-000000000000",
"systemPrompt": "<Source system prompt to generate cases f>",
"documentText": "<Source document text to generate cases f>",
"count": 20,
"strategies": [
"reasoning",
"edge-case",
"adversarial"
]
}Schema
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Org's project to scope the generation to."
},
"systemPrompt": {
"type": "string",
"minLength": 10,
"maxLength": 8000,
"description": "Source system prompt to generate cases for. Mutually exclusive with documentText."
},
"documentText": {
"type": "string",
"minLength": 10,
"maxLength": 50000,
"description": "Source document text to generate cases from. Mutually exclusive with systemPrompt."
},
"count": {
"default": 20,
"type": "integer",
"minimum": 1,
"maximum": 200
},
"strategies": {
"default": [
"reasoning",
"edge-case",
"adversarial"
],
"minItems": 1,
"maxItems": 7,
"type": "array",
"items": {
"type": "string",
"enum": [
"reasoning",
"multi-context",
"comparative",
"hypothetical",
"edge-case",
"adversarial",
"paraphrase",
"concretizing",
"constrained",
"in-breadth"
]
}
}
},
"required": [
"projectId",
"count",
"strategies"
],
"additionalProperties": false
}
}
}Response
200 example
{
"success": false,
"data": {
"cases": [
{
"input": "string",
"expectedOutput": "string",
"metadata": {
"strategy": "string",
"sourceType": "system-prompt",
"chunkIndex": 0,
"qualityScore": 0
}
}
],
"stats": {
"requestedCount": 0,
"actualCount": 0,
"totalGenerated": 0,
"totalFiltered": 0,
"strategiesUsed": [
"string"
],
"durationMs": 0
}
}
}All status codes
200Generated cases + run stats
400Validation error (mutually-exclusive fields, count out of range, etc.)
401Unauthorized
403Insufficient role (editor required)
429Too Many Requests — the per-key or per-organization rate limit was exceeded. Honour the Retry-After header.
500Internal Server Error — SYNTHESIZER_FAILURE.
503LLM unavailable — server-side LLM key not configured
Code samples
cURL
curl -X POST \
https://evalguard.ai/api/v1/datasets/synthesize \
-H "Authorization: Bearer $EVALGUARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "projectId": "00000000-0000-0000-0000-000000000000", "systemPrompt": "<Source system prompt to generate cases f>", "documentText": "<Source document text to generate cases f>", "count": 20, "strategies": [ "reasoning", "edge-case", "adversarial" ] }'TypeScript
// The TypeScript SDK (@evalguard/sdk) exposes TYPED methods — runEval,
// getEval, runSecurityScan, checkFirewall, … — not a generic request().
// For an arbitrary endpoint, call it directly:
const res = await fetch("https://evalguard.ai/api/v1/datasets/synthesize", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.EVALGUARD_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"projectId": "00000000-0000-0000-0000-000000000000",
"systemPrompt": "<Source system prompt to generate cases f>",
"documentText": "<Source document text to generate cases f>",
"count": 20,
"strategies": [
"reasoning",
"edge-case",
"adversarial"
]
}),
});
console.log(res.status, await res.json());Python
# The Python SDK (pip install evalguardai) exposes TYPED methods on
# EvalGuardClient — run_eval, get_eval, … — not a generic request().
# For an arbitrary endpoint, call it directly:
import os
import requests
headers = {"Authorization": f"Bearer {os.environ['EVALGUARD_API_KEY']}"}
headers["Content-Type"] = "application/json"
response = requests.request(
"POST",
"https://evalguard.ai/api/v1/datasets/synthesize",
headers=headers,
json={
"projectId": "00000000-0000-0000-0000-000000000000",
"systemPrompt": "<Source system prompt to generate cases f>",
"documentText": "<Source document text to generate cases f>",
"count": 20,
"strategies": [
"reasoning",
"edge-case",
"adversarial"
]
},
)
print(response.status_code, response.json())Go
package main
import (
"context"
"fmt"
"net/http"
"os"
"strings"
)
func main() {
body := strings.NewReader(`{"projectId":"00000000-0000-0000-0000-000000000000","systemPrompt":"<Source system prompt to generate cases f>","documentText":"<Source document text to generate cases f>","count":20,"strategies":["reasoning","edge-case","adversarial"]}`)
req, _ := http.NewRequestWithContext(context.Background(), "POST", "https://evalguard.ai/api/v1/datasets/synthesize", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("EVALGUARD_API_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
fmt.Println(resp.Status)
}Errors
400401403429500503