Get one eval suite's configuration

GET

projects

{projectId}

eval-suites

{suiteId}

Get one eval suite's configuration

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

import requests

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

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}', 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}",
  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}"

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

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>",
  "environment": {
    "servers": [
      "<string>"
    ],
    "computerEnvironment": {
      "id": "<string>",
      "name": "<string>"
    }
  },
  "hosts": [
    {
      "id": "<string>",
      "name": "<string>",
      "servers": [
        "<string>"
      ]
    }
  ],
  "settings": {
    "minimumAccuracy": 123,
    "matchOptions": {},
    "checks": [
      {}
    ],
    "judge": {
      "enabled": true,
      "model": "<string>",
      "autoRun": true,
      "threshold": 123,
      "severity": "warn",
      "groundedness": {
        "role": "advisory",
        "model": "<string>",
        "threshold": 123,
        "severity": "warn"
      },
      "rubric": {
        "criteria": [
          {
            "id": "<string>",
            "label": "<string>",
            "description": "<string>",
            "required": true
          }
        ]
      }
    },
    "minimumIterations": 123,
    "verdictPolicyVersion": 2,
    "verdictPolicyDefaults": {
      "repetitions": 2,
      "passThreshold": 0.5,
      "validity": {
        "minEligibleTrials": 2,
        "minCompletionRate": 0.5,
        "maxEvaluatorErrorRate": 0.5
      }
    },
    "policy": "legacy",
    "qualityGate": {
      "baseline": {
        "kind": "run",
        "runId": "<string>"
      },
      "maximumPassRateDrop": 123,
      "noDeterministicRegressions": true,
      "maximumP95LatencyIncreaseMs": 123,
      "noGatingScoreErrors": true
    }
  },
  "schedule": {
    "enabled": true,
    "intervalMinutes": 5042,
    "environmentId": "<string>",
    "state": "active",
    "createdBy": "<string>",
    "nextDueAt": 123,
    "consecutiveFailures": 123
  },
  "declaredId": "<string>",
  "managedBy": "ci",
  "name": "<string>",
  "description": "<string>",
  "projectId": "<string>",
  "executionConfig": {
    "model": "<string>",
    "systemPrompt": "<string>",
    "temperature": 123
  },
  "environmentIds": [
    "<string>"
  ],
  "revisionNumber": 123,
  "createdAt": 123,
  "updatedAt": 123
}

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.

Headers

x-mcpjam-eval-vocabulary

enum<string>

Which vocabulary this request and its response speak. Absent means 1, which is byte-for-byte today's contract: the same request fields, the same refusals, the same response projection. 2 is the canonical vocabulary. Any other value is a 400 with code: "VALIDATION_ERROR".

Today it decides one thing: the spelling of an evaluator's policy role. Vocabulary 1 accepts and returns gating; vocabulary 2 accepts both spellings and returns the canonical required. Sending required without the header is a 400, deliberately — vocabulary 1 is not widened to meet vocabulary 2 half way, because a boundary that accepts a spelling it does not announce is one two implementations can disagree about.

A response that varies by vocabulary sends Vary: x-mcpjam-eval-vocabulary.

Available options:

1,

2

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.

Response

The suite.

One eval suite's full configuration. Distinct from the EvalSuite summary returned by the list route, which carries run rollups instead of settings.

string

required

environment

object

required

LEGACY server bag, kept as rollback data, plus the suite's sandbox-image pin. Unrelated to environmentIds.

Show child attributes

hosts

object[]

required

Show child attributes

settings

object

required

A suite's grading configuration, as vocabulary 1 spells it. FOUR SEPARATE SETTINGS, and the first two are the ones most often confused: the PASS CRITERION (minimumAccuracy, one percentage over the whole run, OR verdictPolicyDefaults.passThreshold, a fraction each case must meet over its own iterations — policy says which decides this suite), the ITERATION RULE (minimumIterations, a floor that RAISES a case's own count, OR verdictPolicyDefaults.repetitions, a default that REPLACES it), the evaluators (matchOptions, checks, judge), and the QUALITY GATE, which asks whether a run regressed against a baseline rather than whether it met a bar. The four REQUIRED fields are the ones the DTO always emits: minimumAccuracy and matchOptions are nullable rather than absent — null is the suite's real state (no suite-wide threshold in effect, no match options set), not a stand-in for a default — and judge is fully resolved, so it is present even on a suite that configured nothing.

Show child attributes

schedule

object

required

Recurring-run schedule. A schedule fires exactly ONE run, so an environment-based suite pins the environment it runs against.

Show child attributes

declaredId

string

The suite's declared file identity (suite.id in a suite file). Present on file-owned suites; absent on UI-authored suites, which have no declared id and cannot be claimed by eval run --file.

managedBy

enum<string>

Where this suite's configuration lives. ci means it is owned by a committed suite file or by MCPJam SDK ingest, and the platform REFUSES configuration writes to it — name, settings, environments, schedule, models, skills, execution config and cases — from this API and from the app alike, with 409 CONFLICT and details.reason: "CI_OWNED_SUITE_READ_ONLY".

Running, replaying and comparing are unaffected. To change a CI-owned suite, either edit its file and send that file's suite.id as declaredSuiteId on the write, or duplicate the suite for an editable copy.

declaredId alone is not this answer: a suite created by SDK ingest is CI-owned and has no declared id.

Available options:

ci,

app

name

string | null

description

string | null

projectId

string | null

executionConfig

object | null

Show child attributes

environmentIds

string[]

Attached project environments, in attach order.

revisionNumber

integer | null

How many committed edits this suite has had, or null on a deployment that does not record revisions. Send it back as expectedRevisionNumber on a PATCH to make that edit a compare-and-set.

createdAt

number | null

Epoch milliseconds.

updatedAt

number | null

⌘I

Get one eval suite's configuration

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

import requests

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

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}', 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}",
  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}"

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

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>",
  "environment": {
    "servers": [
      "<string>"
    ],
    "computerEnvironment": {
      "id": "<string>",
      "name": "<string>"
    }
  },
  "hosts": [
    {
      "id": "<string>",
      "name": "<string>",
      "servers": [
        "<string>"
      ]
    }
  ],
  "settings": {
    "minimumAccuracy": 123,
    "matchOptions": {},
    "checks": [
      {}
    ],
    "judge": {
      "enabled": true,
      "model": "<string>",
      "autoRun": true,
      "threshold": 123,
      "severity": "warn",
      "groundedness": {
        "role": "advisory",
        "model": "<string>",
        "threshold": 123,
        "severity": "warn"
      },
      "rubric": {
        "criteria": [
          {
            "id": "<string>",
            "label": "<string>",
            "description": "<string>",
            "required": true
          }
        ]
      }
    },
    "minimumIterations": 123,
    "verdictPolicyVersion": 2,
    "verdictPolicyDefaults": {
      "repetitions": 2,
      "passThreshold": 0.5,
      "validity": {
        "minEligibleTrials": 2,
        "minCompletionRate": 0.5,
        "maxEvaluatorErrorRate": 0.5
      }
    },
    "policy": "legacy",
    "qualityGate": {
      "baseline": {
        "kind": "run",
        "runId": "<string>"
      },
      "maximumPassRateDrop": 123,
      "noDeterministicRegressions": true,
      "maximumP95LatencyIncreaseMs": 123,
      "noGatingScoreErrors": true
    }
  },
  "schedule": {
    "enabled": true,
    "intervalMinutes": 5042,
    "environmentId": "<string>",
    "state": "active",
    "createdBy": "<string>",
    "nextDueAt": 123,
    "consecutiveFailures": 123
  },
  "declaredId": "<string>",
  "managedBy": "ci",
  "name": "<string>",
  "description": "<string>",
  "projectId": "<string>",
  "executionConfig": {
    "model": "<string>",
    "systemPrompt": "<string>",
    "temperature": 123
  },
  "environmentIds": [
    "<string>"
  ],
  "revisionNumber": 123,
  "createdAt": 123,
  "updatedAt": 123
}

API Guides

Endpoints

Get one eval suite's configuration

Authorizations

Headers

Path Parameters

Response