# Touchstone API Upgrade Proposal
**Date:** 2026-01-14
**Status:** Draft
**Purpose:** Document proposed enhancements to the Touchstone API to better support MCP integration and developer workflows.
---
## Background
During the design of TS-MCP (Use Case 1: Conversational FHIR Testing Assistant), we identified several limitations in the current Touchstone API that impact developer experience and automation capabilities.
This document captures proposed enhancements for discussion with the AEGIS Touchstone team.
---
## Current Limitations
| Gap | Current Behavior | Impact |
|-----|------------------|--------|
| No list test setups endpoint | Users must know Test Setup names from UI | Cannot browse available setups programmatically |
| No dynamic endpoint specification | Test systems must be pre-configured in UI | Cannot specify FHIR server URL at runtime |
| No test script search | Must browse UI to find tests | Cannot discover relevant tests programmatically |
| Polling-only status | Must poll every 4+ seconds | Inefficient; no real-time updates |
---
## Proposed Enhancements
### 1. List Test Setups Endpoint
**Endpoint:** `GET /api/testSetups`
**Purpose:** Retrieve available Test Setups for the authenticated user/organization.
**Response:**
```json
{
"testSetups": [
{
"id": "setup-123",
"name": "Patient-CRUD",
"description": "Patient resource CRUD operations",
"testSystem": "My-Dev-Server",
"testScriptCount": 12,
"lastExecuted": "2026-01-10T15:30:00Z"
}
]
}
```
**Value:** Enables programmatic discovery of available test configurations.
---
### 2. Dynamic Test System Specification
**Enhancement:** Allow passing FHIR server URL at execution time.
**Current:** `POST /api/testExecution`
```json
{
"testSetup": "SetupName"
}
```
**Proposed:** `POST /api/testExecution`
```json
{
"testSetup": "SetupName",
"targetEndpoint": "https://my-fhir-server.com/fhir"
}
```
Ideally, if `trargetEndpoint` is not yet found as a TestSytem, we create it (populating Org Name from the authenticated user's profile).
- We may need to return a prompt for some of the TestSystem info required.
- Need the proxy URL returned
**Value:** Enables testing against dynamic environments (dev, staging, PR previews) without pre-configuration.
---
### 3. Test Script Search Endpoint
**Endpoint:** `GET /api/testScripts?q=<search>&ig=<implementation-guide>`
**Purpose:** Search available test scripts by keyword or implementation guide.
**Response:**
```json
{
"testScripts": [
{
"id": "script-456",
"name": "Patient-read",
"description": "Test Patient read operation",
"implementationGuide": "US Core 6.1",
"resourceTypes": ["Patient"]
}
]
}
```
**Value:** Enables AI assistants to discover and recommend relevant tests.
---
### 4. Webhook Notifications
**Enhancement:** Register webhook URL for execution status updates.
**Endpoint:** `POST /api/webhooks`
```json
{
"url": "https://my-server.com/touchstone-callback",
"events": ["execution.completed", "execution.failed"]
}
```
**Callback Payload:**
```json
{
"event": "execution.completed",
"executionId": "12345",
"status": "Passed",
"summary": { "total": 50, "passed": 50, "failed": 0 }
}
```
**Value:** Eliminates polling; enables real-time CI/CD integration.
---
### 5. Batch Execution
**Enhancement:** Launch multiple Test Setups in a single request.
**Endpoint:** `POST /api/testExecution/batch`
```json
{
"testSetups": ["Patient-CRUD", "Observation-CRUD", "Encounter-CRUD"]
}
```
**Response:**
```json
{
"executions": [
{ "testSetup": "Patient-CRUD", "executionId": "123" },
{ "testSetup": "Observation-CRUD", "executionId": "124" },
{ "testSetup": "Encounter-CRUD", "executionId": "125" }
]
}
```
**Value:** Reduces API calls for comprehensive test runs.
---
## Priority Ranking
| Priority | Enhancement | Rationale |
|----------|-------------|-----------|
| **High** | List Test Setups | Fundamental for usability |
| **High** | Test Script Search | Enables intelligent test discovery |
| **Medium** | Dynamic Endpoint | Valuable for CI/CD workflows |
| **Medium** | Webhook Notifications | Improves efficiency |
| **Low** | Batch Execution | Convenience optimization |
---
## Next Steps
1. Review proposal with AEGIS Touchstone team
2. Prioritize based on feasibility and demand
3. Define detailed API specifications for approved enhancements
4. Plan implementation timeline
---
## Notes
*This document will be expanded based on discussions with the Touchstone team and feedback from the developer community.*
