> ## Documentation Index > Fetch the complete documentation index at: https://mcpjam-claude-peaceful-lamport-qktsqz.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Get a journey run > The full record, including per-session `attempts` and `targetSummaries`. Read `canceled` before reporting a failure: a stopped run carries `status: "failed"`. ## OpenAPI ````yaml /reference/openapi.json get /projects/{projectId}/journey-runs/{runId} openapi: 3.1.0 info: title: MCPJam API version: 1.0.0-preview description: >- Programmatic access to MCP servers saved in your MCPJam projects — live diagnostics (validate, inspect, export) and operations: call tools, render prompts, run eval suites asynchronously and poll their results, and import OAuth tokens. **The API is in preview**: the surface may change while we finish the design. Error `code` values are stable; error `message` strings are not. Write clients that ignore unknown response fields. contact: name: MCPJam url: https://github.com/MCPJam/inspector/issues servers: - url: https://app.mcpjam.com/api/v1 description: Hosted MCPJam security: - bearerAuth: [] tags: - name: Agent browsers description: >- Isolated cloud browser sessions for coding agents. Requires authenticated project membership and a configured desktop runtime. - name: Clients description: >- Clients — the named, reusable configurations that define how MCPJam connects to and talks to your MCP servers. The original `/hosts` paths remain as deprecated, ID-only compatibility aliases with their original DTOs and their original (tokenless) write contracts; every alias response carries `Deprecation: true`. New integrations should use `/clients`. - name: Environments description: >- Project environments: named, live-editable execution bundles (one host, an optional standalone server group, optionally pinned skills and plugin versions) that eval suites and journeys run against. Distinct from Sandbox images, which are Computer base images. Reads require project membership; every write requires project admin. - name: Plugins description: >- Agent Plugins imported into a project — read-only inventory and version detail. - name: Skills description: >- Cloud Skills: authored SKILL.md files stored in a project. Read-only here. Environments pin skills by id (`skillSelection.skillIds`) and eval runs pin them with `--compose-skill`, so this surface exists to give an unattended caller those ids; authoring is an app flow behind a beta gate. - name: Sandbox images description: >- Custom Computer images: a digest-pinned Dockerfile built into an immutable image your project's computers boot from. - name: Server diagnostics description: Connect-level health checks against a saved MCP server. - name: Primitives description: 'The server''s MCP primitives: tools, prompts, and resources.' - name: Export description: Full-server snapshots for diffing and CI. - name: Execution description: 'Run the server''s primitives: call tools, render prompts.' - name: Eval runs description: >- Asynchronous eval suite runs: create with 202, poll status, iterations, and traces. - name: Conformance runs description: >- Ingest MCP spec-conformance results from the SDK/CLI into project-owned history. Distinct from Eval runs (authored LLM cases) and from directory readiness. - name: Server connections description: >- Connect an MCP server URL to a project, authorizing in a browser when the server requires it. - name: OAuth description: 'Bring-your-own OAuth: import externally obtained tokens for a server.' - name: Scenarios description: >- Read-only access to the scenarios published from a project: listing, settings, attached servers, and share links. - name: Catalog description: >- Discover the resources the other routes operate on: your account, projects, servers, eval suites, and chat sessions. - name: Tunnels description: >- Relay tunnels that expose local MCP servers through a public URL, registered as first-class project servers (the `mcpjam cloud tunnel` CLI flow). - name: Agent description: >- Headless agent turns over the public API: send a message history, the server runs one assistant turn with project-scoped workspace tools (eval reads + suite creation) on a pinned hosted model, and returns the reply plus created-resource references. - name: Swarms description: >- Personas, journeys and swarm containers — the authoring half of Swarms — plus the model-backed generation that drafts them. - name: Swarm runs description: >- Launching journeys and reading what they produced. Launching SPENDS — see the per-operation notes. - name: Swarm insights description: >- What a swarm run revealed. The scorecard and findings are deterministic and free; requesting wave insights runs models and draws on your shared daily ledger. - name: User testing description: >- Publishing an environment for real visitors, and controlling who can reach it. Several of these NARROW access and take effect immediately. - name: Directory readiness description: >- Grade a saved server against a publisher's listing requirements: Anthropic's connector directory or OpenAI's plugin directory. Reported as lane status and coverage, never as a numeric score, and excluded from `pooledConformanceScore`. Deterministic grading is free; model-backed experience observations are an explicit opt-in whose model cost is on MCPJam — no credits are consumed — and they can never decide a verdict. - name: Registry description: >- Search the scraped MCP directories (Claude, ChatGPT, and any future source), list curated/org registry cards, and install them into a project. Install writes a `servers` row and provenance — it does not open a live session. There is no catalog-uninstall route: delete the project server instead. Directory reads require a bearer (including minted guest tokens) but do not materialize a user. Card/connection reads and all writes are authed-non-guest. paths: /projects/{projectId}/journey-runs/{runId}: parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/runId' get: tags: - Swarm runs summary: Get a journey run description: >- The full record, including per-session `attempts` and `targetSummaries`. Read `canceled` before reporting a failure: a stopped run carries `status: "failed"`. operationId: getJourneyRun responses: '200': description: The run. content: application/json: schema: $ref: '#/components/schemas/JourneyRun' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: parameters: projectId: name: projectId in: path required: true description: ID of the hosted project that contains the server. schema: type: string runId: name: runId in: path required: true description: Eval run ID, as returned by `POST /eval-runs`. schema: type: string schemas: JourneyRun: type: object required: - id - projectId - journeyId - status - canceled - stale - summary - targets - createdAt properties: id: type: string projectId: type: string journeyId: type: string waveId: type: string description: >- The batch this run was launched with. Sibling runs of one co-launched wave share it; a solo relaunch is a wave of one. Absent on a run launched without one. status: type: string description: Poll until it leaves `running`. enum: - running - completed - partial - failed - rate_limited canceled: type: boolean description: >- True when somebody STOPPED this run. **Check this before showing a run as a failure**: a cancelled run reports `status: "failed"`, because cancellation is recorded as a marker rather than a status of its own. stale: type: boolean description: >- True when the runner went silent and the watchdog settled the run. Distinct from a run that failed while still reporting. error: type: string description: Raw marker behind `canceled` / `stale`. summary: $ref: '#/components/schemas/JourneyRunSummary' targets: type: array items: $ref: '#/components/schemas/JourneyRunTarget' persona: type: object description: >- The persona AS PINNED AT LAUNCH, from the run's immutable snapshot — not the persona's current values, which may have been edited since. properties: personaId: type: - string - 'null' name: type: - string - 'null' role: type: - string - 'null' attempts: type: array description: >- Per-session execution records. Present on the single-run read only — lists stay compact. items: $ref: '#/components/schemas/JourneyRunAttempt' targetSummaries: type: array description: The same counts as `summary`, broken down per target. items: type: object required: - hostId - total - succeeded - failed - rateLimited properties: hostId: type: string targetId: type: string total: type: integer succeeded: type: integer failed: type: integer rateLimited: type: integer createdAt: type: number description: Epoch milliseconds. lastHeartbeatAt: type: number description: >- Epoch milliseconds of the runner's last check-in. A long-stale heartbeat on a `running` run is what the watchdog acts on. insights: allOf: - $ref: '#/components/schemas/InsightsEnvelope' description: >- The common actionable-insights envelope. Present on the DETAIL response only — lists stay compact — and absent when the caller may not have it or the deployment cannot produce one. Treat absence exactly like `status: "not_available"`. verdictSummary: $ref: '#/components/schemas/JourneyRunVerdictSummary' report: $ref: '#/components/schemas/SwarmReport' JourneyRunSummary: type: object required: - total - succeeded - failed - rateLimited properties: total: type: integer description: Targets × `sessionsPerTarget`, fixed at launch. succeeded: type: integer failed: type: integer rateLimited: type: integer JourneyRunTarget: type: object required: - hostId properties: hostId: type: string hostName: type: string targetId: type: string description: >- Execution identity. TWO TARGETS CAN SHARE A `hostId` — two environments may resolve to the same host with different servers — so this, not `hostId`, is what identifies a target within a run. modelId: type: string JourneyRunAttempt: type: object description: 'One session''s execution record: (target, session index).' required: - chatSessionId - hostId - targetId - sessionIndex - status - errorCode - errorMessage properties: chatSessionId: type: - string - 'null' description: '`null` until the attempt claims a session.' hostId: type: string targetId: type: - string - 'null' sessionIndex: type: integer status: type: string description: >- `pending` → `running` → terminal. A `pending` attempt cannot jump straight to a terminal state. enum: - pending - running - succeeded - failed - rate_limited errorCode: type: - string - 'null' errorMessage: type: - string - 'null' description: Capped and redacted before it reaches this response. InsightsEnvelope: type: object required: - schemaVersion - scope - status - reasonCode - retryable - error - generatedAt - updatedAt - summary - coverage - findings - truncation description: >- The common insights envelope, shared by eval runs, swarm waves and user-testing windows. One shape for three producers, so a caller writes the reading code once. An ABSENT envelope and `status: "not_available"` mean the same thing and both are normal: the field is an enrichment, and a caller who may not have it gets the resource without it rather than an error. properties: schemaVersion: type: integer enum: - 1 scope: $ref: '#/components/schemas/InsightScope' status: type: string description: >- `not_available` means this deployment cannot produce insights at all — treat an ABSENT envelope the same way. `not_requested` means nobody has asked. `pending` means one is running: poll, do not re-request. enum: - not_available - not_requested - pending - completed - failed reasonCode: type: - string - 'null' retryable: type: boolean description: >- Whether asking again could produce a different answer. False on a `failed` envelope means the input, not the attempt, was the problem. error: oneOf: - type: object required: - code - message properties: code: type: string message: type: string - type: 'null' generatedAt: type: - integer - 'null' updatedAt: type: - integer - 'null' summary: type: - string - 'null' coverage: type: object required: - unit - analyzed - total - truncated - lowConfidence description: >- READ THIS BEFORE QUOTING ANY FINDING. `truncated` and `lowConfidence` are the difference between "this happens" and "this happened in the part we looked at". properties: unit: type: string enum: - iterations - sessions analyzed: type: integer total: type: integer gradedCount: type: integer feedbackCount: type: integer truncated: type: boolean description: The analysis saw `analyzed` of `total`, not all of it. lowConfidence: type: boolean description: >- Too little was analyzed to generalize. Findings still stand as observations of what WAS seen. findings: type: array items: $ref: '#/components/schemas/ActionableFinding' currentFindings: type: array description: >- Absent on a deployment that predates findings. The always-available observation view: findings assembled from deterministic evidence plus any identity-matching model enrichment, populated INDEPENDENTLY of `status`. Read `currentFindings ?? findings` — and treat an explicit `[]` as a real "nothing here needs a change" rather than falling back to the generated array. items: $ref: '#/components/schemas/ActionableFinding' observationState: type: string description: >- How much of the population `currentFindings` describes — distinct from `status`, which describes a model GENERATION. `unavailable` means nothing could be measured, which is NOT the same as an empty `currentFindings`. enum: - ready - partial - unavailable observationCoverage: type: object required: - unit - analyzed - total - gradedCount - exclusions description: >- Coverage for `currentFindings`, describing ITS population. Deliberately separate from `coverage`, whose counters describe the generation's population. properties: unit: type: string enum: - iterations analyzed: type: integer total: type: integer gradedCount: type: integer exclusions: type: object description: >- Counted reasons an iteration was left out, keyed by reason. An OPEN map: a new exclusion class must not require a consumer change to keep validating. additionalProperties: type: integer unifiedFindings: type: object required: - capability - snapshot - job - canBuild - canEnrich description: >- Absent on a deployment that predates findings. Its PRESENCE says the deployment serves findings; `snapshot: null` says this run has none built yet — two different answers a caller must not conflate. properties: capability: type: string enum: - unified_findings_v1 analysis: type: object description: >- The trace analysis pipeline's progress while one exists for the run. Absent when none has been requested. required: - phase - progress - models - completeness properties: phase: type: string enum: - reading - grouping - checking - done - failed progress: type: object required: - done - total - unit properties: done: type: integer total: type: integer unit: type: string enum: - iterations models: type: array items: type: string completeness: type: object required: - iterationReports - total - missingTraces properties: iterationReports: type: integer total: type: integer missingTraces: type: integer snapshot: type: - object - 'null' description: >- The built findings snapshot: its deterministic findings, per-finding provenance, and any pipeline-verified mechanisms. `null` means none has been built for this run. job: type: - object - 'null' description: >- The in-flight or last-failed operation, so a refusal never renders as a completed analysis. canBuild: type: boolean canEnrich: type: boolean runHealth: type: object required: - targets description: >- Swarm only. Launch outcomes never appear as findings — a run that could not start is an operational fact, not something the server under test did. properties: targets: type: array items: type: object required: - subjectKind - subjectId - subjectLabel - attempted - succeeded - failed - rateLimited properties: subjectKind: type: string enum: - environment - host subjectId: type: string subjectLabel: type: string attempted: type: integer succeeded: type: integer failed: type: integer rateLimited: type: integer truncation: type: object required: - truncated - omittedFindings - omittedEvidence - contractTruncated description: >- What this RESPONSE dropped to stay a sane size, as distinct from what the ANALYSIS did not look at (`coverage`). properties: truncated: type: boolean omittedFindings: type: integer omittedEvidence: type: integer contractTruncated: type: boolean journeyFindings: allOf: - $ref: '#/components/schemas/SwarmJourneyFindings' nullable: true journeyFindingsJob: allOf: - $ref: '#/components/schemas/SwarmJourneyFindingsJob' nullable: true JourneyRunVerdictSummary: oneOf: - type: object properties: status: type: string enum: - pending pendingSessions: type: integer minimum: 0 maximum: 9007199254740991 updatedAt: type: integer minimum: 0 maximum: 9007199254740991 required: - status - pendingSessions - updatedAt additionalProperties: false - type: object properties: status: type: string enum: - decided decision: $ref: '#/components/schemas/EvalVerdictDecision' updatedAt: type: integer minimum: 0 maximum: 9007199254740991 required: - status - decision - updatedAt additionalProperties: false - type: object properties: status: type: string enum: - notEstablished reason: type: string enum: - gradingNotConfigured updatedAt: type: integer minimum: 0 maximum: 9007199254740991 required: - status - reason - updatedAt additionalProperties: false - type: object properties: status: type: string enum: - integrityFailed reason: type: string minLength: 1 updatedAt: type: integer minimum: 0 maximum: 9007199254740991 required: - status - reason - updatedAt additionalProperties: false SwarmReport: type: object properties: contractVersion: type: number enum: - 1 runId: type: string minLength: 1 verdict: type: string enum: - passed - failed - inconclusive - notEstablished verdictSource: type: string enum: - policyV2 - none decision: $ref: '#/components/schemas/EvalVerdictDecision' undecidedReason: type: string enum: - executionPending - gradingPending - gradingNotConfigured - verdictSummaryUnavailable - integrityFailed execution: type: object properties: unit: type: string enum: - sessions configured: type: integer minimum: 0 maximum: 9007199254740991 reported: type: integer minimum: 0 maximum: 9007199254740991 started: type: integer minimum: 0 maximum: 9007199254740991 notStarted: type: integer minimum: 0 maximum: 9007199254740991 unknown: type: integer minimum: 0 maximum: 9007199254740991 completed: type: integer minimum: 0 maximum: 9007199254740991 interrupted: type: integer minimum: 0 maximum: 9007199254740991 neverLaunched: type: boolean required: - unit - configured - reported - started - notStarted - unknown - completed - interrupted - neverLaunched additionalProperties: false goalGrading: type: object properties: unit: type: string enum: - sessions reported: type: integer minimum: 0 maximum: 9007199254740991 passed: type: integer minimum: 0 maximum: 9007199254740991 failed: type: integer minimum: 0 maximum: 9007199254740991 pending: type: integer minimum: 0 maximum: 9007199254740991 unavailable: type: integer minimum: 0 maximum: 9007199254740991 notRequested: type: integer minimum: 0 maximum: 9007199254740991 waitingForDecisiveGrading: type: integer minimum: 0 maximum: 9007199254740991 required: - unit - reported - passed - failed - pending - unavailable - notRequested - waitingForDecisiveGrading additionalProperties: false observations: type: array items: type: object properties: evaluatorId: type: string minLength: 1 predicateType: type: string enum: - toolDescriptionsPresent - toolAnnotationsPresent - toolNamesUnique - noDeprecatedToolExposed - toolInputSchemasWellFormed - toolOutputSchemasPresent - toolCalledWith - toolCalledAtLeastOnce - toolNeverCalled - onlyToolsCalled - firstToolWas - toolCallCountUnder - toolCalledBefore - noDeprecatedToolCalled - noDestructiveToolCalled - argumentsMatchToolSchema - noRepeatedIdenticalCall - noToolErrors - toolLatencyUnder - toolResultContains - toolResultMatchesSchema - toolResultSizeUnder - toolErrorNamesInput - fullPageHasContinuation - responseCloseTo - responseContains - responseMatches - finalAssistantMessageNonEmpty - tokenBudgetUnder - turnCountUnder - widgetRendered - widgetRenderLatencyUnder - widgetNoConsoleErrors - noEndingQuestion role: type: string enum: - advisory - required stage: type: string enum: - connection - discovery - selection - call - response - userValue description: >- The stage this observation was read from, and the only stage it is evidence ABOUT. `connection` — the server was reachable and the session initialized. `discovery` — its tools and resources were listed and readable. `selection` — the model chose the right tool for the request. `call` — the call was made with usable arguments. `response` — the server returned data the model could use. `userValue` — the user's actual request was satisfied. unit: type: string enum: - sessions total: type: integer minimum: 0 maximum: 9007199254740991 passed: type: integer minimum: 0 maximum: 9007199254740991 failed: type: integer minimum: 0 maximum: 9007199254740991 pending: type: integer minimum: 0 maximum: 9007199254740991 unavailable: type: integer minimum: 0 maximum: 9007199254740991 required: - evaluatorId - predicateType - role - stage - unit - total - passed - failed - pending - unavailable additionalProperties: false required: - contractVersion - runId - verdict - verdictSource - execution - goalGrading - observations additionalProperties: false Error: type: object required: - code - message properties: code: type: string description: >- Stable, machine-readable error code. New codes may be added over time; treat unknown codes as non-retryable failures unless the HTTP status says otherwise. enum: - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - VALIDATION_ERROR - RATE_LIMITED - FEATURE_NOT_SUPPORTED - SERVER_UNREACHABLE - TIMEOUT - OAUTH_REQUIRED - INTERNAL_ERROR message: type: string description: >- Human-readable description. May change between releases — don't match on it. details: type: object description: Optional, unstructured context bag. additionalProperties: true InsightScope: type: object required: - kind - id description: What this envelope is about. The extra fields depend on `kind`. properties: kind: type: string enum: - eval_run - swarm_wave - user_testing_window id: type: string runId: type: string description: '`swarm_wave` only.' scenarioId: type: string description: '`user_testing_window` only.' windowStartAt: type: integer description: '`user_testing_window` only.' windowEndAt: type: integer description: '`user_testing_window` only.' ActionableFinding: type: object required: - id - signalFingerprint - title - category - attribution - actionTarget - actionability - severity - confidence - observed - recommendation - acceptanceCriteria - affected - evidence description: >- One actionable finding. The fields are ordered from cheapest to trust to most: `observed` is deterministic, `recommendation` is the model's, and `evidence` lets you check both. properties: id: type: string description: >- Stable remediation id (`rf_<16 hex>`). Survives dynamic error values, so the same problem keeps the same id across runs — dismiss it once and it stays dismissed. signalFingerprint: type: string description: >- The registry signal this derives from. Several findings can share one. title: type: string category: type: string enum: - unknown - tool_contract - tool_runtime - capability_gap - workflow - agent_behavior - test_design - environment attribution: type: string description: >- WHOSE problem this is. `server_*` points at the MCP server; `agent_or_prompt` and `test_design` point back at the caller. enum: - unknown - server_contract - server_runtime - server_capability - agent_or_prompt - test_design - environment actionTarget: type: string description: What you would change to fix it. enum: - investigate - mcp_server - agent_configuration - eval_case - environment actionability: type: string description: >- `ready` means the finding names a specific target and change. `investigate` means it does not yet. `informational` means there is nothing to do. enum: - informational - investigate - ready severity: type: string enum: - info - low - medium - high confidence: type: string enum: - low - medium - high observed: type: string description: >- DETERMINISTIC observation — counts and identities, never model prose. This is the part you can verify yourself. rootCause: type: string recommendation: type: string acceptanceCriteria: type: array description: How you would know the fix worked. items: type: string affected: type: object required: - count - total - unit description: >- How much of the analyzed population hit this. Read it as a ratio — `1/40` and `38/40` are different problems. properties: count: type: integer total: type: integer unit: type: string enum: - iterations - sessions patternSlug: type: string target: type: object required: - serverId - surface - snapshotHash description: >- Present only when a server (and, for tool surfaces, a tool) resolved against the pinned snapshot. Required for `mcp_server` / `ready`. properties: serverId: type: string toolName: type: string surface: type: string enum: - description - input_schema - output_schema - handler - server_instructions - capability fieldPath: type: string snapshotHash: type: string description: >- The pinned snapshot the target resolved against, so a finding cannot silently re-point at a definition that changed after it was written. currentDefinition: type: object required: - truncated properties: description: type: string inputSchemaJson: type: string outputSchemaJson: type: string truncated: type: boolean evidence: type: array items: $ref: '#/components/schemas/ActionableFindingEvidence' SwarmJourneyFindings: type: object properties: contractVersion: type: number enum: - 1 generatedAt: type: integer minimum: 0 maximum: 9007199254740991 sourceRevision: type: string pipelineVersion: type: integer minimum: 0 maximum: 9007199254740991 extractionVersion: type: integer minimum: 0 maximum: 9007199254740991 extractionModel: type: string reasoningModel: type: string summaryKind: type: string enum: - notLaunched - broken - friction - landed - ungraded - unread description: '`notLaunched`, `broken`, `friction`, `landed`, `ungraded`, `unread`' population: type: object properties: configured: type: integer minimum: 0 maximum: 9007199254740991 started: type: integer minimum: 0 maximum: 9007199254740991 read: type: integer minimum: 0 maximum: 9007199254740991 unread: type: integer minimum: 0 maximum: 9007199254740991 withdrawn: type: integer minimum: 0 maximum: 9007199254740991 limited: type: integer minimum: 0 maximum: 9007199254740991 graded: type: integer minimum: 0 maximum: 9007199254740991 required: - configured - started - read - unread - withdrawn - limited - graded additionalProperties: false coverageNotes: type: array items: type: string enum: - sessionScanCapped - budgetExhausted - transcriptMissing - contextTooLarge - extractionRejected - chainUnmeasured - judgeNotRun - sessionsWithdrawn - sessionsRateLimited - partialRead - toolCatalogMissing description: >- `sessionScanCapped`, `budgetExhausted`, `transcriptMissing`, `contextTooLarge`, `extractionRejected`, `chainUnmeasured`, `judgeNotRun`, `sessionsWithdrawn`, `sessionsRateLimited`, `partialRead`, `toolCatalogMissing` disclosure: type: object properties: rail: type: string enum: - gateway - openrouter evidenceSent: type: array items: type: string required: - rail - evidenceSent additionalProperties: false personas: type: array items: type: object properties: persona: type: object properties: personaRefId: type: string nullable: true name: type: string required: - personaRefId - name additionalProperties: false disposition: type: string enum: - notRun - blockedConnecting - lostFindingTool - blockedCallingTool - blockedByResponse - goalMissed - goalMetWithFriction - goalMet - notMeasured description: >- `notRun`, `blockedConnecting`, `lostFindingTool`, `blockedCallingTool`, `blockedByResponse`, `goalMissed`, `goalMetWithFriction`, `goalMet`, `notMeasured` tone: type: string enum: - fail - warn - ok - muted goalRunIds: type: array items: type: string required: - persona - disposition - tone - goalRunIds additionalProperties: false findings: maxItems: 200 type: array items: $ref: '#/components/schemas/SwarmJourneyFinding' required: - contractVersion - generatedAt - sourceRevision - pipelineVersion - extractionVersion - extractionModel - reasoningModel - summaryKind - population - coverageNotes - disclosure - personas - findings additionalProperties: false SwarmJourneyFindingsJob: type: object properties: status: type: string enum: - pending - completed - failed - skipped errorCode: type: string updatedAt: type: integer minimum: 0 maximum: 9007199254740991 required: - status - updatedAt additionalProperties: false EvalVerdictDecision: type: object properties: verdictPolicyVersion: type: number enum: - 2 verdict: type: string enum: - passed - failed - inconclusive reasons: minItems: 1 maxItems: 11 type: array items: type: string enum: - configuredTrialsNotAttempted - noGradeableTrials - eligibleTrialsBelowMinimum - completionRateBelowMinimum - completionRateNotMeasured - evaluatorErrorRateAboveMaximum - evaluatorErrorRateNotMeasured - caseHasNoEligibleTrials - casePassRateMetThreshold - casePassRateBelowThreshold - allMeasuredCasesMetThreshold description: >- Why the verdict is what it is. The validity reasons are evaluated FIRST and make a run `inconclusive`; the task reasons decide `passed` / `failed` once validity holds. `configuredTrialsNotAttempted` — some configured trial never ran. `noGradeableTrials` — nothing in the suite was gradeable. `eligibleTrialsBelowMinimum` — the explicit `minEligibleTrials` was not reached. `completionRateBelowMinimum` — measured, and under the floor. `completionRateNotMeasured` — nothing was attempted, so the floor is unsatisfiable; a not-measured rate never passes one. `evaluatorErrorRateAboveMaximum` — the grader failed too often for the run to describe the server. `evaluatorErrorRateNotMeasured` — the same unsatisfiable case for the ceiling. `caseHasNoEligibleTrials` — a case graded nothing, which is inconclusive even at `passThreshold: 0`. `casePassRateMetThreshold` — a case's own passing reason. `casePassRateBelowThreshold` — a case failed its threshold, and so therefore did the suite. `allMeasuredCasesMetThreshold` — the suite's only passing reason. validity: type: object properties: policy: type: object properties: coverage: oneOf: - type: object properties: kind: type: string enum: - allConfiguredTrialsAttempted minGradeableTrials: type: number enum: - 1 required: - kind - minGradeableTrials additionalProperties: false - type: object properties: kind: type: string enum: - minEligibleTrials minEligibleTrials: type: integer minimum: 1 maximum: 9007199254740991 required: - kind - minEligibleTrials additionalProperties: false minCompletionRate: type: number minimum: 0 maximum: 1 maxEvaluatorErrorRate: type: number minimum: 0 maximum: 1 required: - coverage - minCompletionRate - maxEvaluatorErrorRate additionalProperties: false holds: type: boolean configuredTrials: type: integer minimum: 0 maximum: 9007199254740991 attemptedTrials: type: integer minimum: 0 maximum: 9007199254740991 eligibleTrials: type: integer minimum: 0 maximum: 9007199254740991 completionRate: oneOf: - type: object properties: state: type: string enum: - measured value: type: number minimum: 0 maximum: 1 numerator: type: integer minimum: 0 maximum: 9007199254740991 denominator: type: integer minimum: 1 maximum: 9007199254740991 exclusions: type: object properties: notTerminal: type: integer minimum: 0 maximum: 9007199254740991 skipped: type: integer minimum: 0 maximum: 9007199254740991 setupFailed: type: integer minimum: 0 maximum: 9007199254740991 cancelled: type: integer minimum: 0 maximum: 9007199254740991 timedOut: type: integer minimum: 0 maximum: 9007199254740991 executionFailed: type: integer minimum: 0 maximum: 9007199254740991 evaluatorError: type: integer minimum: 0 maximum: 9007199254740991 additionalProperties: false required: - state - value - numerator - denominator - exclusions additionalProperties: false - type: object properties: state: type: string enum: - notMeasured value: type: string nullable: true enum: - null numerator: type: number enum: - 0 denominator: type: number enum: - 0 exclusions: type: object properties: notTerminal: type: integer minimum: 0 maximum: 9007199254740991 skipped: type: integer minimum: 0 maximum: 9007199254740991 setupFailed: type: integer minimum: 0 maximum: 9007199254740991 cancelled: type: integer minimum: 0 maximum: 9007199254740991 timedOut: type: integer minimum: 0 maximum: 9007199254740991 executionFailed: type: integer minimum: 0 maximum: 9007199254740991 evaluatorError: type: integer minimum: 0 maximum: 9007199254740991 additionalProperties: false required: - state - value - numerator - denominator - exclusions additionalProperties: false evaluatorErrorRate: oneOf: - type: object properties: state: type: string enum: - measured value: type: number minimum: 0 maximum: 1 numerator: type: integer minimum: 0 maximum: 9007199254740991 denominator: type: integer minimum: 1 maximum: 9007199254740991 exclusions: type: object properties: notTerminal: type: integer minimum: 0 maximum: 9007199254740991 skipped: type: integer minimum: 0 maximum: 9007199254740991 setupFailed: type: integer minimum: 0 maximum: 9007199254740991 cancelled: type: integer minimum: 0 maximum: 9007199254740991 timedOut: type: integer minimum: 0 maximum: 9007199254740991 executionFailed: type: integer minimum: 0 maximum: 9007199254740991 evaluatorError: type: integer minimum: 0 maximum: 9007199254740991 additionalProperties: false required: - state - value - numerator - denominator - exclusions additionalProperties: false - type: object properties: state: type: string enum: - notMeasured value: type: string nullable: true enum: - null numerator: type: number enum: - 0 denominator: type: number enum: - 0 exclusions: type: object properties: notTerminal: type: integer minimum: 0 maximum: 9007199254740991 skipped: type: integer minimum: 0 maximum: 9007199254740991 setupFailed: type: integer minimum: 0 maximum: 9007199254740991 cancelled: type: integer minimum: 0 maximum: 9007199254740991 timedOut: type: integer minimum: 0 maximum: 9007199254740991 executionFailed: type: integer minimum: 0 maximum: 9007199254740991 evaluatorError: type: integer minimum: 0 maximum: 9007199254740991 additionalProperties: false required: - state - value - numerator - denominator - exclusions additionalProperties: false required: - policy - holds - configuredTrials - attemptedTrials - eligibleTrials - completionRate - evaluatorErrorRate additionalProperties: false cases: minItems: 1 maxItems: 50000 type: array items: type: object properties: caseId: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_-]+$ executionVariant: type: object properties: model: type: string minLength: 1 maxLength: 200 provider: type: string minLength: 1 maxLength: 200 required: - model additionalProperties: false configuredTrials: type: integer minimum: 1 maximum: 100 attemptedTrials: type: integer minimum: 0 maximum: 9007199254740991 eligibleTrials: type: integer minimum: 0 maximum: 9007199254740991 passedTrials: type: integer minimum: 0 maximum: 9007199254740991 failedTrials: type: integer minimum: 0 maximum: 9007199254740991 effectivePassThreshold: type: number minimum: 0 maximum: 1 passRate: oneOf: - type: object properties: state: type: string enum: - measured value: type: number minimum: 0 maximum: 1 numerator: type: integer minimum: 0 maximum: 9007199254740991 denominator: type: integer minimum: 1 maximum: 9007199254740991 exclusions: type: object properties: notTerminal: type: integer minimum: 0 maximum: 9007199254740991 skipped: type: integer minimum: 0 maximum: 9007199254740991 setupFailed: type: integer minimum: 0 maximum: 9007199254740991 cancelled: type: integer minimum: 0 maximum: 9007199254740991 timedOut: type: integer minimum: 0 maximum: 9007199254740991 executionFailed: type: integer minimum: 0 maximum: 9007199254740991 evaluatorError: type: integer minimum: 0 maximum: 9007199254740991 additionalProperties: false required: - state - value - numerator - denominator - exclusions additionalProperties: false - type: object properties: state: type: string enum: - notMeasured value: type: string nullable: true enum: - null numerator: type: number enum: - 0 denominator: type: number enum: - 0 exclusions: type: object properties: notTerminal: type: integer minimum: 0 maximum: 9007199254740991 skipped: type: integer minimum: 0 maximum: 9007199254740991 setupFailed: type: integer minimum: 0 maximum: 9007199254740991 cancelled: type: integer minimum: 0 maximum: 9007199254740991 timedOut: type: integer minimum: 0 maximum: 9007199254740991 executionFailed: type: integer minimum: 0 maximum: 9007199254740991 evaluatorError: type: integer minimum: 0 maximum: 9007199254740991 additionalProperties: false required: - state - value - numerator - denominator - exclusions additionalProperties: false completionRate: oneOf: - type: object properties: state: type: string enum: - measured value: type: number minimum: 0 maximum: 1 numerator: type: integer minimum: 0 maximum: 9007199254740991 denominator: type: integer minimum: 1 maximum: 9007199254740991 exclusions: type: object properties: notTerminal: type: integer minimum: 0 maximum: 9007199254740991 skipped: type: integer minimum: 0 maximum: 9007199254740991 setupFailed: type: integer minimum: 0 maximum: 9007199254740991 cancelled: type: integer minimum: 0 maximum: 9007199254740991 timedOut: type: integer minimum: 0 maximum: 9007199254740991 executionFailed: type: integer minimum: 0 maximum: 9007199254740991 evaluatorError: type: integer minimum: 0 maximum: 9007199254740991 additionalProperties: false required: - state - value - numerator - denominator - exclusions additionalProperties: false - type: object properties: state: type: string enum: - notMeasured value: type: string nullable: true enum: - null numerator: type: number enum: - 0 denominator: type: number enum: - 0 exclusions: type: object properties: notTerminal: type: integer minimum: 0 maximum: 9007199254740991 skipped: type: integer minimum: 0 maximum: 9007199254740991 setupFailed: type: integer minimum: 0 maximum: 9007199254740991 cancelled: type: integer minimum: 0 maximum: 9007199254740991 timedOut: type: integer minimum: 0 maximum: 9007199254740991 executionFailed: type: integer minimum: 0 maximum: 9007199254740991 evaluatorError: type: integer minimum: 0 maximum: 9007199254740991 additionalProperties: false required: - state - value - numerator - denominator - exclusions additionalProperties: false observedStability: oneOf: - type: object properties: state: type: string enum: - measured value: type: number minimum: 0 maximum: 1 numerator: type: integer minimum: 0 maximum: 9007199254740991 denominator: type: integer minimum: 1 maximum: 9007199254740991 exclusions: type: object properties: notTerminal: type: integer minimum: 0 maximum: 9007199254740991 skipped: type: integer minimum: 0 maximum: 9007199254740991 setupFailed: type: integer minimum: 0 maximum: 9007199254740991 cancelled: type: integer minimum: 0 maximum: 9007199254740991 timedOut: type: integer minimum: 0 maximum: 9007199254740991 executionFailed: type: integer minimum: 0 maximum: 9007199254740991 evaluatorError: type: integer minimum: 0 maximum: 9007199254740991 additionalProperties: false required: - state - value - numerator - denominator - exclusions additionalProperties: false - type: object properties: state: type: string enum: - notMeasured value: type: string nullable: true enum: - null numerator: type: number enum: - 0 denominator: type: number enum: - 0 exclusions: type: object properties: notTerminal: type: integer minimum: 0 maximum: 9007199254740991 skipped: type: integer minimum: 0 maximum: 9007199254740991 setupFailed: type: integer minimum: 0 maximum: 9007199254740991 cancelled: type: integer minimum: 0 maximum: 9007199254740991 timedOut: type: integer minimum: 0 maximum: 9007199254740991 executionFailed: type: integer minimum: 0 maximum: 9007199254740991 evaluatorError: type: integer minimum: 0 maximum: 9007199254740991 additionalProperties: false required: - state - value - numerator - denominator - exclusions additionalProperties: false mixedVerdict: type: boolean verdict: type: string enum: - passed - failed - inconclusive reason: type: string enum: - configuredTrialsNotAttempted - noGradeableTrials - eligibleTrialsBelowMinimum - completionRateBelowMinimum - completionRateNotMeasured - evaluatorErrorRateAboveMaximum - evaluatorErrorRateNotMeasured - caseHasNoEligibleTrials - casePassRateMetThreshold - casePassRateBelowThreshold - allMeasuredCasesMetThreshold description: >- Why the verdict is what it is. The validity reasons are evaluated FIRST and make a run `inconclusive`; the task reasons decide `passed` / `failed` once validity holds. `configuredTrialsNotAttempted` — some configured trial never ran. `noGradeableTrials` — nothing in the suite was gradeable. `eligibleTrialsBelowMinimum` — the explicit `minEligibleTrials` was not reached. `completionRateBelowMinimum` — measured, and under the floor. `completionRateNotMeasured` — nothing was attempted, so the floor is unsatisfiable; a not-measured rate never passes one. `evaluatorErrorRateAboveMaximum` — the grader failed too often for the run to describe the server. `evaluatorErrorRateNotMeasured` — the same unsatisfiable case for the ceiling. `caseHasNoEligibleTrials` — a case graded nothing, which is inconclusive even at `passThreshold: 0`. `casePassRateMetThreshold` — a case's own passing reason. `casePassRateBelowThreshold` — a case failed its threshold, and so therefore did the suite. `allMeasuredCasesMetThreshold` — the suite's only passing reason. required: - caseId - configuredTrials - attemptedTrials - eligibleTrials - passedTrials - failedTrials - effectivePassThreshold - passRate - completionRate - observedStability - mixedVerdict - verdict - reason additionalProperties: false required: - verdictPolicyVersion - verdict - reasons - validity - cases additionalProperties: false ActionableFindingEvidence: type: object required: - kind - excerpt description: >- One citation behind a finding. Evidence is what makes a finding checkable rather than an assertion. properties: sessionId: type: string iterationId: type: string kind: type: string enum: - tool_error - transcript - feedback - judge - contrast excerpt: type: string description: Scrubbed and clipped at the producer. Never a full transcript. toolName: type: string errorCode: type: string SwarmJourneyFinding: type: object properties: id: type: string minLength: 1 basis: type: string enum: - verifiedMechanism - sessionReport - populationFact description: '`verifiedMechanism`, `sessionReport`, `populationFact`' scopeLevel: type: string enum: - session - goal - persona - target - wave description: '`session`, `goal`, `persona`, `target`, `wave`' persona: type: object properties: personaRefId: type: string nullable: true name: type: string required: - personaRefId - name additionalProperties: false goal: type: object properties: runId: type: string journeyRefId: type: string title: type: string required: - runId - journeyRefId - title additionalProperties: false target: type: object properties: kind: type: string enum: - environment - host id: type: string label: type: string modelId: type: string nullable: true required: - kind - id - label - modelId additionalProperties: false population: type: object properties: count: type: integer minimum: 0 maximum: 9007199254740991 total: type: integer minimum: 0 maximum: 9007199254740991 unit: type: string enum: - sessions required: - count - total - unit additionalProperties: false sessionIds: maxItems: 1000 type: array items: type: string citations: maxItems: 30 type: array items: type: string pattern: ^[^/]+\/.+$ verdictSeen: type: string enum: - passed - failed - inconclusive - notEstablished chainStage: nullable: true description: >- `connection`, `discovery`, `selection`, `call`, `response`, `userValue` type: string enum: - connection - discovery - selection - call - response - userValue chainStageState: nullable: true description: >- `passed`: passed; `failed`: failed; `notReached`: never ran (an earlier stage failed); `notMeasured`: not measured; `notApplicable`: not applicable to this case type: string enum: - passed - failed - notReached - notMeasured - notApplicable chainStageBasis: type: string enum: - derived - reported - unmeasured disposition: type: string enum: - notRun - blockedConnecting - lostFindingTool - blockedCallingTool - blockedByResponse - goalMissed - goalMetWithFriction - goalMet - notMeasured description: >- `notRun`, `blockedConnecting`, `lostFindingTool`, `blockedCallingTool`, `blockedByResponse`, `goalMissed`, `goalMetWithFriction`, `goalMet`, `notMeasured` tone: type: string enum: - fail - warn - ok - muted coverageNotes: type: array items: type: string enum: - sessionScanCapped - budgetExhausted - transcriptMissing - contextTooLarge - extractionRejected - chainUnmeasured - judgeNotRun - sessionsWithdrawn - sessionsRateLimited - partialRead - toolCatalogMissing description: >- `sessionScanCapped`, `budgetExhausted`, `transcriptMissing`, `contextTooLarge`, `extractionRejected`, `chainUnmeasured`, `judgeNotRun`, `sessionsWithdrawn`, `sessionsRateLimited`, `partialRead`, `toolCatalogMissing` outcomePhrase: nullable: true type: string maxLength: 100 pattern: ^[^0-9]*$ mechanismPhrase: type: string nullable: true fixPhrase: type: string nullable: true reportExcerpt: nullable: true type: object properties: actual: type: string maxLength: 1800 citations: maxItems: 30 type: array items: type: string pattern: ^[^/]+\/.+$ required: - actual - citations additionalProperties: false mechanismId: type: string nullable: true required: - id - basis - scopeLevel - persona - goal - target - population - sessionIds - citations - verdictSeen - chainStage - chainStageState - chainStageBasis - disposition - tone - coverageNotes - outcomePhrase - mechanismPhrase - fixPhrase - reportExcerpt - mechanismId additionalProperties: false responses: Unauthorized: description: >- Missing, invalid, revoked, or orphaned key (`UNAUTHORIZED`) — or the **target MCP server** needs an OAuth grant (`OAUTH_REQUIRED`), which is a property of the server, not your key. content: application/json: schema: $ref: '#/components/schemas/Error' examples: badKey: summary: Invalid or revoked key value: code: UNAUTHORIZED message: Invalid API key oauthRequired: summary: Target server needs an OAuth grant value: code: OAUTH_REQUIRED message: Server requires OAuth authorization Forbidden: description: Key is valid but not allowed to do this. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: FORBIDDEN message: You do not have access to this project NotFound: description: Unknown project, server, or resource. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: NOT_FOUND message: Server not found RateLimited: description: >- Per-key rate limit exceeded (60 requests/minute sustained, bursts up to 10). Honor `Retry-After` and back off with jitter. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: code: RATE_LIMITED message: API key rate limit exceeded. Slow down and retry. InternalError: description: Something failed on MCPJam's side. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: INTERNAL_ERROR message: Unexpected internal error securitySchemes: bearerAuth: type: http scheme: bearer description: >- MCPJam API key (`sk_…`). Create one at [Settings → API keys](https://app.mcpjam.com/settings/api-keys). Guest sessions cannot use the API, and API keys cannot manage other API keys. ````