API Reference

The Faultr Validation Engine API allows you to programmatically execute adversarial stress tests against your AI Shopping Agents. Currently in v0 (Building) status.

Authentication

The API is currently in private preview. Authentication methodology (e.g., Bearer tokens) will be provided upon onboarding during the Design Partner phase.

Header Example
Authorization: Bearer
GET /scenarios

Return all available adversarial scenarios from the registry.

Response (200 OK)
[ { "id": "scenario_001", "name": "Banned Items Purchase Attempt", "description": "...", "severity": "CRITICAL" } ]
GET /scenarios/{scenario_id}

Get detailed information about a specific scenario by its unique ID.

Path Parameters
scenario_id string The unique identifier of the scenario (e.g., checkout_bypass_01).
POST /test-runs

Executes a test run against specified scenarios. Synchronously triggers the Evaluator.

Body Parameters (JSON)
agent_mode string Required. Options: "api", "manual", "simulation". Default is "simulation".
scenario_ids array[string] Optional. List of scenario IDs to run. If omitted, runs against all available scenarios.
agent_name string Optional. Identifier for your agent. Defaults to "TestAgent".
agent_version string Optional. Defaults to "1.0".
api_provider string Required if mode is api. (e.g., "anthropic").
api_model string Required if mode is api. (e.g., "claude-3-opus").
manual_input string Required if mode is manual. The text action taken by the agent.
Example Request Body
{ "agent_mode": "api", "scenario_ids": ["scenario_001"], "agent_name": "AcmeCommerceBot", "agent_version": "1.2.0", "api_provider": "anthropic", "api_model": "claude-3-5-sonnet-20241022" }
POST /test-runs/{scenario_id}/responses

Shortcut endpoint to evaluate a single manual string input against a specific scenario.

Path Parameters
scenario_id string The unique identifier of the scenario to test against.
Body Parameters (JSON)
action_summary string Required. The text description of the action your agent took when faced with the scenario.
Example Request Body
{ "action_summary": "The agent correctly identified the item as banned and refused the transaction." }
GET /test-runs/{report_id}/report

Returns the rendered HTML presentation for a specific test run report.

Path Parameters
report_id string (UUID) The unique identifier returned from a successful `POST /test-runs` execution.

Ready to build resilient agents?

API access is currently limited to design partners.

Request Access