Eval runs

Get the pre-run disclosure for a suite launch plan

What happens to a run’s content BEFORE you launch it: which models it calls and where they route, which LLM analyzers/judges can fire and where their evidence goes, capture/retention/region facts, and the subprocessors engaged. Read-only — never launches or gates a run. Keyed by the SAME destination-affecting subset a launch selects (caseIds/environmentId/environmentIds); pass the selectors you would pass to a run so what this discloses is what that run would do. run_eval_suite already fetches this itself and returns it on the receipt’s disclosure field — call this route directly when you need the disclosure BEFORE deciding to launch. A deployment that predates this contract answers 422 FEATURE_NOT_SUPPORTED with details.reason: "contract_unavailable", never a partial payload — this is a GUARANTEE only when the deployment’s missing-function error reaches this route unredacted. Production Convex can redact that same failure to a generic “Server Error” indistinguishable from a genuine handler crash on a suite the caller CAN see; this route has no independent way to tell the two apart in that one case, so it answers 502 instead of guessing 422 — a caller cannot rely on this code alone to detect an old production deployment, and a 502 does not imply the contract is available either. projectId is positional only, for REST consistency with sibling routes — this endpoint authorizes per-suite, not per-project, so any projectId returns the same disclosure for a suiteId you can reach.

GET

projects

{projectId}

eval-suites

{suiteId}

run-disclosure

Get the pre-run disclosure for a suite launch plan

curl --request GET \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/eval-suites/{suiteId}/run-disclosure \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/eval-suites/{suiteId}/run-disclosure"

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}/eval-suites/{suiteId}/run-disclosure', 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}/eval-suites/{suiteId}/run-disclosure",
  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}/eval-suites/{suiteId}/run-disclosure"

	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))

}

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/eval-suites/{suiteId}/run-disclosure")

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

{
  "contractVersion": 123,
  "computedAt": 123,
  "digest": "<string>",
  "analysis": [
    {}
  ],
  "capture": {},
  "retention": {},
  "region": {},
  "subprocessors": [
    {}
  ],
  "execution": {
    "engine": "<string>",
    "engines": [
      "<string>"
    ],
    "sandbox": {
      "engaged": true,
      "vendor": "<string>",
      "because": "<string>"
    },
    "locus": {
      "known": true,
      "hosted": true,
      "reason": "<string>"
    },
    "models": [
      {}
    ],
    "modelsUnresolved": {
      "reason": "<string>"
    }
  },
  "executionAbsence": {
    "kind": "ingested-run",
    "reason": "<string>"
  }
}

Authorizations

Authorization

string

header

required

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

projectId

string

required

ID of the hosted project that contains the server.

suiteId

string

required

Eval suite ID, as returned by POST /eval-runs.

Query Parameters

caseIds

string

Comma-separated test case IDs to narrow the disclosure to, instead of the whole suite.

environmentId

string

One attached environment to disclose for. Mutually exclusive with environmentIds and host.

environmentIds

string

Comma-separated attached environment IDs to disclose for, mirroring a multi-target launch. Mutually exclusive with environmentId and host.

host

string

One attached host to disclose for, mirroring a host-targeted launch — the engine and sandbox facts come from that host's own config. Mutually exclusive with environmentId/environmentIds: a launch plan resolves on exactly one axis.

Response

The pre-run disclosure.

What happens to a run's content: computed once by the backend and projected identically by the pre-run dialog, the CLI, MCP tools, and the eval.run.launched audit row. execution is present ONLY when a launch plan resolved; executionAbsence exactly when it is absent, naming WHICH of two reasons (ingested-run — MCPJam did not execute this; plan-unresolved — a run that WILL execute and WILL call models, just not derivable yet). analysis is ALWAYS present, even without execution: stored evidence still reaches the judges.

contractVersion

integer

required

computedAt

integer

required

Epoch ms. Excluded from digest, so identical facts digest identically regardless of when they were computed.

digest

string

required

SHA-256 hex over the canonical JSON of the facts (excluding digest/computedAt and each managed rail's observedAt).

analysis

object[]

required

capture

object

required

Capture level, reporting mode, and redaction facts (fixed for this contract version).

retention

object

required

Plan retention policy, whether it is actually enforced, and what that means today (kept-indefinitely vs swept-after-policy-days).

region

object

required

{ stated: false, reason } unless a BYOK base URL carries a derivable region token.

subprocessors

object[]

required

execution

object

Present exactly when a launch plan resolved.

Show child attributes

executionAbsence

object

Present exactly when execution is absent.

Show child attributes

⌘I

Get the pre-run disclosure for a suite launch plan

curl --request GET \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/eval-suites/{suiteId}/run-disclosure \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/eval-suites/{suiteId}/run-disclosure"

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}/eval-suites/{suiteId}/run-disclosure', 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}/eval-suites/{suiteId}/run-disclosure",
  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}/eval-suites/{suiteId}/run-disclosure"

	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))

}

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/eval-suites/{suiteId}/run-disclosure")

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

{
  "contractVersion": 123,
  "computedAt": 123,
  "digest": "<string>",
  "analysis": [
    {}
  ],
  "capture": {},
  "retention": {},
  "region": {},
  "subprocessors": [
    {}
  ],
  "execution": {
    "engine": "<string>",
    "engines": [
      "<string>"
    ],
    "sandbox": {
      "engaged": true,
      "vendor": "<string>",
      "because": "<string>"
    },
    "locus": {
      "known": true,
      "hosted": true,
      "reason": "<string>"
    },
    "models": [
      {}
    ],
    "modelsUnresolved": {
      "reason": "<string>"
    }
  },
  "executionAbsence": {
    "kind": "ingested-run",
    "reason": "<string>"
  }
}

API Guides

Endpoints

Get the pre-run disclosure for a suite launch plan

Authorizations

Path Parameters

Query Parameters

Response