HTTP API Reference

Complete reference for all Sentinel REST endpoints — suites, cases, runs, baselines, red team, prompts, scenarios, and reports.

All endpoints are under /sentinel and return JSON. Authentication and tenant resolution depend on your Forge middleware configuration.

Suites

`POST /sentinel/suites`

Create a suite.

Request

{
  "name": "string (required)",
  "description": "string",
  "system_prompt": "string",
  "model": "string (default: engine default)",
  "temperature": 0,
  "persona_ref": "string (optional)",
  "metadata": {}
}

Response 201 Created — Suite object with generated id.

`GET /sentinel/suites`

List suites for the current app.

Query parameters

Param	Type	Description
`limit`	int	Max results (default: 20)
`offset`	int	Pagination offset

Response 200 OK — array of Suite objects.

`GET /sentinel/suites/:id`

Get a suite by ID.

`PUT /sentinel/suites/:id`

Update a suite.

`DELETE /sentinel/suites/:id`

Delete a suite and all associated cases, runs, and baselines.

Cases

`POST /sentinel/suites/:suiteId/cases`

Create a test case in a suite.

Request

{
  "name": "string (required)",
  "input": "string (required)",
  "expected": "string",
  "scenario_type": "standard",
  "scorers": [{"name": "contains", "config": {"substring": "hello"}}],
  "tags": ["tag1"],
  "context": {},
  "metadata": {}
}

`GET /sentinel/suites/:suiteId/cases`

List cases for a suite.

`POST /sentinel/suites/:suiteId/cases/import`

Bulk import cases from JSON, CSV, or JSONL format.

Request — raw file body with Content-Type header indicating format.

`PUT /sentinel/cases/:id`

Update a case.

`DELETE /sentinel/cases/:id`

Delete a case.

Runs

`POST /sentinel/suites/:suiteId/run`

Execute an evaluation run.

Request

{
  "model": "string (optional override)",
  "temperature": 0,
  "target_tenant_id": "string (optional)"
}

Response 201 Created — Run object with state: "running".

`GET /sentinel/runs`

List runs with optional filters.

Param	Type	Description
`suite_id`	string	Filter by suite
`state`	string	Filter by state
`limit`	int	Max results
`offset`	int	Pagination offset

`GET /sentinel/runs/:id`

Get a specific run.

`GET /sentinel/runs/:id/results`

List all results for a run.

`GET /sentinel/runs/:id/stats`

Get aggregate statistics for a run.

Response 200 OK

{
  "total_cases": 50,
  "passed": 45,
  "failed": 3,
  "errored": 2,
  "pass_rate": 0.9,
  "avg_score": 0.87,
  "avg_latency_ms": 1200,
  "total_tokens": 50000,
  "total_cost": 2.50,
  "dimension_scores": {"skill": 0.92, "trait": 0.88}
}

Baselines

`POST /sentinel/baselines/:suiteId`

Save a baseline from a run.

`GET /sentinel/baselines/:suiteId`

Get the latest baseline for a suite.

`GET /sentinel/baselines/:suiteId/baselines`

List all baselines for a suite.

Red Team

`POST /sentinel/redteam/:suiteId/generate`

Generate adversarial test cases for a suite.

`POST /sentinel/redteam/:suiteId/run`

Run adversarial evaluation against the suite's target.

Prompt Versions

`POST /sentinel/prompts/:suiteId`

Create a new prompt version.

Request

{
  "system_prompt": "string (required)",
  "changelog": "string"
}

`GET /sentinel/prompts/:suiteId`

List all prompt versions for a suite.

`PUT /sentinel/prompts/:suiteId/current`

Set the current active prompt version.

Scenarios

`POST /sentinel/scenarios/:suiteId/generate`

Auto-generate test cases for a specific evaluation dimension.

Request

{
  "scenario_type": "skill_challenge",
  "count": 10
}

`GET /sentinel/scenarios/:suiteId`

List generated scenarios.

Reports

`GET /sentinel/reports/:runId/report`

Generate a report for a run.

Param	Type	Description
`format`	string	`terminal`, `json`, `html`, or `ci`

`GET /sentinel/reports/:runId/report/export`

Export a report in the specified format.

Error format

All error responses use a consistent JSON envelope:

{
  "error": "human-readable message",
  "code": "ERROR_CODE"
}

HTTP status	`code`	Cause
`400`	`BAD_REQUEST`	Missing required field, empty input, invalid state
`404`	`NOT_FOUND`	Suite, case, run, or baseline not found
`409`	`CONFLICT`	Suite with same name already exists
`500`	`INTERNAL_ERROR`	Store or target failure

HTTP API Reference

On this page