User testing
Get a scenario
The scenario, plus the insights envelope over its latest analyzed window when the caller may have it.
Project members only. This route is deliberately outside the guest allowlist, and the envelope additionally needs workspace membership — share-link visitors can never read other visitors’ evidence.
GET
/
projects
/
{projectId}
/
user-testing
/
scenarios
/
{scenarioId}
Get a scenario
curl --request GET \
--url https://app.mcpjam.com/api/v1/projects/{projectId}/user-testing/scenarios/{scenarioId} \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.mcpjam.com/api/v1/projects/{projectId}/user-testing/scenarios/{scenarioId}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/user-testing/scenarios/{scenarioId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.mcpjam.com/api/v1/projects/{projectId}/user-testing/scenarios/{scenarioId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.mcpjam.com/api/v1/projects/{projectId}/user-testing/scenarios/{scenarioId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://app.mcpjam.com/api/v1/projects/{projectId}/user-testing/scenarios/{scenarioId}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/user-testing/scenarios/{scenarioId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "<string>",
"projectId": "<string>",
"name": "<string>",
"description": "<string>",
"mode": "<string>",
"environmentId": "<string>",
"insights": {
"schemaVersion": 1,
"scope": {
"id": "<string>",
"runId": "<string>",
"scenarioId": "<string>",
"windowStartAt": 123,
"windowEndAt": 123
},
"reasonCode": "<string>",
"retryable": true,
"error": {
"code": "<string>",
"message": "<string>"
},
"generatedAt": 123,
"updatedAt": 123,
"summary": "<string>",
"coverage": {
"analyzed": 123,
"total": 123,
"truncated": true,
"lowConfidence": true,
"gradedCount": 123,
"feedbackCount": 123
},
"findings": [
{
"id": "<string>",
"signalFingerprint": "<string>",
"title": "<string>",
"observed": "<string>",
"recommendation": "<string>",
"acceptanceCriteria": [
"<string>"
],
"affected": {
"count": 123,
"total": 123
},
"evidence": [
{
"excerpt": "<string>",
"sessionId": "<string>",
"iterationId": "<string>",
"toolName": "<string>",
"errorCode": "<string>"
}
],
"rootCause": "<string>",
"patternSlug": "<string>",
"target": {
"serverId": "<string>",
"snapshotHash": "<string>",
"toolName": "<string>",
"fieldPath": "<string>",
"currentDefinition": {
"truncated": true,
"description": "<string>",
"inputSchemaJson": "<string>",
"outputSchemaJson": "<string>"
}
}
}
],
"truncation": {
"truncated": true,
"omittedFindings": 123,
"omittedEvidence": 123,
"contractTruncated": true
},
"runHealth": {
"targets": [
{
"subjectId": "<string>",
"subjectLabel": "<string>",
"attempted": 123,
"succeeded": 123,
"failed": 123,
"rateLimited": 123
}
]
}
}
}
Authorizations
MCPJam API key (sk_…). Create one at Settings → API keys. Guest sessions cannot use the API, and API keys cannot manage other API keys.
Path Parameters
ID of the hosted project that contains the server.
Scenario ID, as returned by publishing an environment or by the project's scenario reads.
Response
The scenario.
A published scenario, enriched with findings over its latest analyzed window. NO accessVersion: the settings envelope this is read from does not carry it — the publish and rebind responses do.
Present when the caller may have it. The envelope needs workspace MEMBERSHIP while the scenario itself is visible more widely, so a lower-privilege viewer gets the scenario without this field rather than a 403.
Show child attributes
Show child attributes
Was this page helpful?
⌘I
Get a scenario
curl --request GET \
--url https://app.mcpjam.com/api/v1/projects/{projectId}/user-testing/scenarios/{scenarioId} \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.mcpjam.com/api/v1/projects/{projectId}/user-testing/scenarios/{scenarioId}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/user-testing/scenarios/{scenarioId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.mcpjam.com/api/v1/projects/{projectId}/user-testing/scenarios/{scenarioId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.mcpjam.com/api/v1/projects/{projectId}/user-testing/scenarios/{scenarioId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://app.mcpjam.com/api/v1/projects/{projectId}/user-testing/scenarios/{scenarioId}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/user-testing/scenarios/{scenarioId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "<string>",
"projectId": "<string>",
"name": "<string>",
"description": "<string>",
"mode": "<string>",
"environmentId": "<string>",
"insights": {
"schemaVersion": 1,
"scope": {
"id": "<string>",
"runId": "<string>",
"scenarioId": "<string>",
"windowStartAt": 123,
"windowEndAt": 123
},
"reasonCode": "<string>",
"retryable": true,
"error": {
"code": "<string>",
"message": "<string>"
},
"generatedAt": 123,
"updatedAt": 123,
"summary": "<string>",
"coverage": {
"analyzed": 123,
"total": 123,
"truncated": true,
"lowConfidence": true,
"gradedCount": 123,
"feedbackCount": 123
},
"findings": [
{
"id": "<string>",
"signalFingerprint": "<string>",
"title": "<string>",
"observed": "<string>",
"recommendation": "<string>",
"acceptanceCriteria": [
"<string>"
],
"affected": {
"count": 123,
"total": 123
},
"evidence": [
{
"excerpt": "<string>",
"sessionId": "<string>",
"iterationId": "<string>",
"toolName": "<string>",
"errorCode": "<string>"
}
],
"rootCause": "<string>",
"patternSlug": "<string>",
"target": {
"serverId": "<string>",
"snapshotHash": "<string>",
"toolName": "<string>",
"fieldPath": "<string>",
"currentDefinition": {
"truncated": true,
"description": "<string>",
"inputSchemaJson": "<string>",
"outputSchemaJson": "<string>"
}
}
}
],
"truncation": {
"truncated": true,
"omittedFindings": 123,
"omittedEvidence": 123,
"contractTruncated": true
},
"runHealth": {
"targets": [
{
"subjectId": "<string>",
"subjectLabel": "<string>",
"attempted": 123,
"succeeded": 123,
"failed": 123,
"rateLimited": 123
}
]
}
}
}