POST
/api/v1/experimentsCreate experiment
Creates an experiment row with status `pending`. This call does not run it, and no worker or route in this repo advances that status — the row is inert until something else is built to consume it. Requires `projectId`, `name` (1-200), `source`, `models[]` (1-10) and `scorers[]` (1-50). The case set depends on `source`: `manual` needs `cases[]` (up to 10,000, inputs up to 100k chars); `csv` needs `csvContent` (up to 5 MiB, parsed server-side); `traces` needs `traceIds[]` (up to 10,000, resolved within the project); `dataset` needs `datasetId` and reads the dataset's LIVE cases, optionally narrowed by `split`; `dataset_version` needs both `datasetId` and `datasetVersionId` and reads the frozen version's cases. A datasetId outside the project's org answers 403/404 without acting as an existence oracle. Optional `groupId` labels a family of experiments. Returns 201 `{id, name, status, models, scorers, datasetCount, source, message}`. Requires the `editor` role and `evals:create`; 10 req/min. NOT idempotent — the `Idempotency-Key` header is not honoured, and a retry creates a second experiment.
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",
"name": "string",
"source": "manual",
"models": [
"string"
],
"scorers": [
"string"
],
"cases": [
{
"input": "string",
"expectedOutput": "string"
}
],
"csvContent": "string",
"traceIds": [
"string"
],
"datasetId": "00000000-0000-0000-0000-000000000000",
"datasetVersionId": "00000000-0000-0000-0000-000000000000",
"split": "string",
"groupId": "string"
}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)$"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"source": {
"type": "string",
"enum": [
"manual",
"csv",
"traces",
"dataset",
"dataset_version"
]
},
"models": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"maxLength": 200
}
},
"scorers": {
"minItems": 1,
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"maxLength": 120
}
},
"cases": {
"maxItems": 10000,
"type": "array",
"items": {
"type": "object",
"properties": {
"input": {
"type": "string",
"maxLength": 100000
},
"expectedOutput": {
"type": "string",
"maxLength": 100000
}
},
"required": [
"input"
],
"additionalProperties": false
}
},
"csvContent": {
"type": "string",
"maxLength": 5242880
},
"traceIds": {
"maxItems": 10000,
"type": "array",
"items": {
"type": "string",
"maxLength": 200
}
},
"datasetId": {
"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)$"
},
"datasetVersionId": {
"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)$"
},
"split": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[\\w.-]+$"
},
"groupId": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"projectId",
"name",
"source",
"models",
"scorers"
],
"additionalProperties": false
}
}
}Response
200 example
{
"success": true
}All status codes
200Experiment created.
201Created.
400(no description)
401(no description)
403Forbidden — insufficient role for this operation.
404Not Found — NOT_FOUND.
409Conflict — CONFLICT.
429(no description)
500Internal Server Error — DB_ERROR.
Code samples
cURL
curl -X POST \
https://evalguard.ai/api/v1/experiments \
-H "Authorization: Bearer $EVALGUARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "projectId": "00000000-0000-0000-0000-000000000000", "name": "string", "source": "manual", "models": [ "string" ], "scorers": [ "string" ], "cases": [ { "input": "string", "expectedOutput": "string" } ], "csvContent": "string", "traceIds": [ "string" ], "datasetId": "00000000-0000-0000-0000-000000000000", "datasetVersionId": "00000000-0000-0000-0000-000000000000", "split": "string", "groupId": "string" }'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/experiments", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.EVALGUARD_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"projectId": "00000000-0000-0000-0000-000000000000",
"name": "string",
"source": "manual",
"models": [
"string"
],
"scorers": [
"string"
],
"cases": [
{
"input": "string",
"expectedOutput": "string"
}
],
"csvContent": "string",
"traceIds": [
"string"
],
"datasetId": "00000000-0000-0000-0000-000000000000",
"datasetVersionId": "00000000-0000-0000-0000-000000000000",
"split": "string",
"groupId": "string"
}),
});
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/experiments",
headers=headers,
json={
"projectId": "00000000-0000-0000-0000-000000000000",
"name": "string",
"source": "manual",
"models": [
"string"
],
"scorers": [
"string"
],
"cases": [
{
"input": "string",
"expectedOutput": "string"
}
],
"csvContent": "string",
"traceIds": [
"string"
],
"datasetId": "00000000-0000-0000-0000-000000000000",
"datasetVersionId": "00000000-0000-0000-0000-000000000000",
"split": "string",
"groupId": "string"
},
)
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","name":"string","source":"manual","models":["string"],"scorers":["string"],"cases":[{"input":"string","expectedOutput":"string"}],"csvContent":"string","traceIds":["string"],"datasetId":"00000000-0000-0000-0000-000000000000","datasetVersionId":"00000000-0000-0000-0000-000000000000","split":"string","groupId":"string"}`)
req, _ := http.NewRequestWithContext(context.Background(), "POST", "https://evalguard.ai/api/v1/experiments", 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
400401403404409429500