Documentation

REST Endpoints

Complete reference for all SimuTest REST API endpoints.

Base URL

All API requests are made to the following base URL. Include your API key in the Authorization header as a Bearer token.

https://api.simutest.dev/v1

Use st_live_ keys for production and st_test_ keys for sandbox environments. See Authentication for details.

Tests

The tests resource is the primary entry point for running SimuTest sessions. Create a test to start AI user simulations against any URL.

Method	Endpoint	Description
POST	/tests	Create and start a new test
GET	/tests	List all tests (paginated)
GET	/tests/{id}	Get test status and results
GET	/tests/{id}/sessions	List all sessions for a test
GET	/tests/{id}/sessions/{sid}	Get individual session details
GET	/tests/{id}/report	Get generated report
DELETE	/tests/{id}	Cancel a running test

Sessions

Individual session endpoints provide access to thinking traces, recordings, and screenshots for a specific AI user session.

Method	Endpoint	Description
GET	/sessions/{id}	Get full session with thinking traces
GET	/sessions/{id}/trace	Get only thinking trace
GET	/sessions/{id}/recording	Get session recording
GET	/sessions/{id}/screenshots	Get screenshots

Personas

Manage persona packs and custom personas. Persona packs are curated collections of user archetypes. You can also create custom personas for specialized testing scenarios.

Method	Endpoint	Description
GET	/personas/packs	List persona packs
GET	/personas/packs/{id}	Get pack details
POST	/personas	Create custom persona
GET	/personas	List custom personas

Reports

Generate and retrieve detailed UX analysis reports for completed tests. Reports include aggregate scores, thinking trace highlights, and ranked issue lists.

Method	Endpoint	Description
POST	/tests/{id}/reports	Generate report for a test
GET	/reports/{id}	Get report
GET	/reports	List reports

Comparisons

Create A/B comparisons between two tests or variants. Comparisons provide statistical analysis to determine which variant performs better across all scoring criteria.

Method	Endpoint	Description
POST	/comparisons	Create A/B comparison
GET	/comparisons/{id}	Get comparison results

Example Request

The following example creates a new test with 200 sessions, targeting a checkout flow with diverse auto-generated personas across both desktop and mobile viewports.

Create a test:

curl -X POST https://api.simutest.dev/v1/tests \
  -H "Authorization: Bearer st_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "task": "Find and purchase the premium plan",
    "sessions": 200,
    "model": "claude-sonnet",
    "personas": { "source": "auto-diverse" },
    "criteria": ["task_completion", "cta_findability"],
    "viewport": ["desktop", "mobile"]
  }'

Response:

{
  "id": "test_abc123",
  "status": "running",
  "url": "https://example.com",
  "task": "Find and purchase the premium plan",
  "sessions_total": 200,
  "sessions_completed": 0,
  "created_at": "2025-01-15T10:00:00Z",
  "estimated_completion": "2025-01-15T10:25:00Z",
  "stream_url": "wss://stream.simutest.dev/tests/test_abc123",
  "report_url": null
}

The stream_url field provides a WebSocket endpoint for real-time session events. See WebSocket Streaming for details.

On this page