Skip to content

API Reference

The Preclinical API enables programmatic access to test execution and results.

Base URL

Most endpoints are under /api/v1. Some operational endpoints (/start-run, /cancel-run) are at the root.

http://localhost:3000

Note

Port 3000 is the default when running via Docker Compose. If running the server directly in development (npm run dev), the default port is 8000.

Authentication

The self-hosted version has no authentication by default. All endpoints are open.

Endpoints

Tests

Method Endpoint Description
POST /start-run Start a new test
GET /api/v1/tests List all tests
GET /api/v1/tests/{id} Get test status and summary
POST /cancel-run Cancel an in-progress test

Scenario Runs

Method Endpoint Description
GET /api/v1/scenario-runs List scenario runs for a test
GET /api/v1/scenario-runs/{id} Get detailed scenario with transcript

Scenarios

Method Endpoint Description
GET /api/v1/scenarios List scenarios
GET /api/v1/scenarios/{id} Get scenario details
PATCH /api/v1/scenarios/{id} Update a scenario
DELETE /api/v1/scenarios/{id} Delete a scenario
POST /api/v1/scenarios/generate Generate scenario from clinical text
POST /api/v1/scenarios/generate-batch Generate scenarios from document

Agents

Method Endpoint Description
GET /api/v1/agents List all agents
POST /api/v1/agents Create a new agent
GET /api/v1/agents/{id} Get agent details
PATCH /api/v1/agents/{id} Update an agent
DELETE /api/v1/agents/{id} Delete an agent

Other

Method Endpoint Description
GET /health Health check
GET /events?run_id=xxx SSE stream for real-time updates

Response Format

All responses are JSON. Successful responses return the requested data directly:

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "completed",
  "pass_rate": 85.0
}

Error Responses

{
  "error": "Agent not found"
}

HTTP Status Codes

Status Description
200 Success
201 Created
204 No Content (successful deletion)
400 Bad Request
404 Not Found
500 Server Error

Pagination

The GET /api/v1/tests and GET /api/v1/scenario-runs endpoints support limit and offset query parameters.

curl "http://localhost:3000/api/v1/tests?limit=20&offset=20"

Quick Start Example

# Start a test
RESPONSE=$(curl -s -X POST http://localhost:3000/start-run \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "your-agent-uuid"}')

TEST_ID=$(echo $RESPONSE | jq -r '.id')

# Poll for completion
while true; do
  STATUS=$(curl -s "http://localhost:3000/api/v1/tests/$TEST_ID" | jq -r '.status')

  echo "Status: $STATUS"

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    break
  fi

  sleep 5
done

# Get scenario run details
curl -s "http://localhost:3000/api/v1/scenario-runs?test_run_id=$TEST_ID" | jq