Create an eval case

POST

projects

{projectId}

eval-suites

{suiteId}

cases

Create an eval case

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/eval-suites/{suiteId}/cases \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "lists files",
  "steps": [
    {
      "id": "s1",
      "kind": "prompt",
      "prompt": "List the files in the project root."
    },
    {
      "id": "s2",
      "kind": "assert",
      "assertion": {
        "type": "toolCalledWith",
        "toolName": "list_files",
        "args": {
          "args": {}
        }
      }
    }
  ]
}
'

import requests

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

payload = {
    "title": "lists files",
    "steps": [
        {
            "id": "s1",
            "kind": "prompt",
            "prompt": "List the files in the project root."
        },
        {
            "id": "s2",
            "kind": "assert",
            "assertion": {
                "type": "toolCalledWith",
                "toolName": "list_files",
                "args": { "args": {} }
            }
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    title: 'lists files',
    steps: [
      {id: 's1', kind: 'prompt', prompt: 'List the files in the project root.'},
      {
        id: 's2',
        kind: 'assert',
        assertion: {type: 'toolCalledWith', toolName: 'list_files', args: {args: {}}}
      }
    ]
  })
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/eval-suites/{suiteId}/cases', 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}/cases",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'lists files',
    'steps' => [
        [
                'id' => 's1',
                'kind' => 'prompt',
                'prompt' => 'List the files in the project root.'
        ],
        [
                'id' => 's2',
                'kind' => 'assert',
                'assertion' => [
                                'type' => 'toolCalledWith',
                                'toolName' => 'list_files',
                                'args' => [
                                                                'args' => [
                                                                                                                                
                                                                ]
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"title\": \"lists files\",\n  \"steps\": [\n    {\n      \"id\": \"s1\",\n      \"kind\": \"prompt\",\n      \"prompt\": \"List the files in the project root.\"\n    },\n    {\n      \"id\": \"s2\",\n      \"kind\": \"assert\",\n      \"assertion\": {\n        \"type\": \"toolCalledWith\",\n        \"toolName\": \"list_files\",\n        \"args\": {\n          \"args\": {}\n        }\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.mcpjam.com/api/v1/projects/{projectId}/eval-suites/{suiteId}/cases")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"lists files\",\n  \"steps\": [\n    {\n      \"id\": \"s1\",\n      \"kind\": \"prompt\",\n      \"prompt\": \"List the files in the project root.\"\n    },\n    {\n      \"id\": \"s2\",\n      \"kind\": \"assert\",\n      \"assertion\": {\n        \"type\": \"toolCalledWith\",\n        \"toolName\": \"list_files\",\n        \"args\": {\n          \"args\": {}\n        }\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"lists files\",\n  \"steps\": [\n    {\n      \"id\": \"s1\",\n      \"kind\": \"prompt\",\n      \"prompt\": \"List the files in the project root.\"\n    },\n    {\n      \"id\": \"s2\",\n      \"kind\": \"assert\",\n      \"assertion\": {\n        \"type\": \"toolCalledWith\",\n        \"toolName\": \"list_files\",\n        \"args\": {\n          \"args\": {}\n        }\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "title": "<string>",
  "steps": [
    {
      "id": "<string>",
      "kind": "prompt",
      "prompt": "<string>",
      "serverName": "<string>",
      "toolName": "<string>",
      "arguments": {},
      "action": {},
      "assertion": {}
    }
  ],
  "iterations": 5,
  "isNegative": true,
  "models": [
    {
      "model": "<string>",
      "provider": "<string>"
    }
  ],
  "declaredId": "<string>",
  "expectedOutput": "<string>",
  "scenario": "<string>",
  "matchOptions": {},
  "checks": {
    "mode": "inherit",
    "list": [
      {}
    ]
  },
  "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.

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.

Body

application/json

Create one case. title and a non-empty steps array are both required — a case persisted without executable steps could never run.

title

string

required

Minimum string length: 1

steps

object[]

required

REPLACES the case's test definition wholesale when provided.

Minimum array length: 1

Show child attributes

string

Stable declared id for the case — the id it answers to in a suite file, an import or a CLI argument. Minted for you when omitted, and unique within the suite. Distinct from the id on the response, which is the case's platform row id.

Pattern: ^[A-Za-z0-9_-]{1,128}$

expectedOutput

string

iterations

integer

Required range: 1 <= x <= 10

isNegative

boolean

scenario

string

models

object[]

Show child attributes

matchOptions

object | null

null clears the case override and inherits the suite's.

checks

object | null

null clears the case override.

Show child attributes

Response

The created case.

A persisted eval case, in the public steps-first shape. Note this is NOT EvalTestCase, which is the INLINE authoring shape accepted by suite creation.

string

required

title

string

required

steps

object[]

required

Ordered test steps. A prompt step is a model turn; a single model-free toolCall step is a render-check; assert steps hold the expectations.

Minimum array length: 1

Show child attributes

iterations

integer

required

Required range: 1 <= x <= 10

isNegative

boolean

required

When true, the case passes if NO tools are called.

models

object[]

required

Show child attributes

declaredId

string

The case's effective declared id. Absent on cases authored before declared identity existed.

expectedOutput

string

scenario

string

matchOptions

object

Absent when the case sets none — omitted from the response rather than sent as null.

checks

object

Absent when the case sets none — omitted from the response rather than sent as null.

Show child attributes

createdAt

number | null

updatedAt

number | null

⌘I

Create an eval case

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/eval-suites/{suiteId}/cases \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "lists files",
  "steps": [
    {
      "id": "s1",
      "kind": "prompt",
      "prompt": "List the files in the project root."
    },
    {
      "id": "s2",
      "kind": "assert",
      "assertion": {
        "type": "toolCalledWith",
        "toolName": "list_files",
        "args": {
          "args": {}
        }
      }
    }
  ]
}
'

import requests

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

payload = {
    "title": "lists files",
    "steps": [
        {
            "id": "s1",
            "kind": "prompt",
            "prompt": "List the files in the project root."
        },
        {
            "id": "s2",
            "kind": "assert",
            "assertion": {
                "type": "toolCalledWith",
                "toolName": "list_files",
                "args": { "args": {} }
            }
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    title: 'lists files',
    steps: [
      {id: 's1', kind: 'prompt', prompt: 'List the files in the project root.'},
      {
        id: 's2',
        kind: 'assert',
        assertion: {type: 'toolCalledWith', toolName: 'list_files', args: {args: {}}}
      }
    ]
  })
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/eval-suites/{suiteId}/cases', 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}/cases",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'lists files',
    'steps' => [
        [
                'id' => 's1',
                'kind' => 'prompt',
                'prompt' => 'List the files in the project root.'
        ],
        [
                'id' => 's2',
                'kind' => 'assert',
                'assertion' => [
                                'type' => 'toolCalledWith',
                                'toolName' => 'list_files',
                                'args' => [
                                                                'args' => [
                                                                                                                                
                                                                ]
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"title\": \"lists files\",\n  \"steps\": [\n    {\n      \"id\": \"s1\",\n      \"kind\": \"prompt\",\n      \"prompt\": \"List the files in the project root.\"\n    },\n    {\n      \"id\": \"s2\",\n      \"kind\": \"assert\",\n      \"assertion\": {\n        \"type\": \"toolCalledWith\",\n        \"toolName\": \"list_files\",\n        \"args\": {\n          \"args\": {}\n        }\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.mcpjam.com/api/v1/projects/{projectId}/eval-suites/{suiteId}/cases")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"lists files\",\n  \"steps\": [\n    {\n      \"id\": \"s1\",\n      \"kind\": \"prompt\",\n      \"prompt\": \"List the files in the project root.\"\n    },\n    {\n      \"id\": \"s2\",\n      \"kind\": \"assert\",\n      \"assertion\": {\n        \"type\": \"toolCalledWith\",\n        \"toolName\": \"list_files\",\n        \"args\": {\n          \"args\": {}\n        }\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"lists files\",\n  \"steps\": [\n    {\n      \"id\": \"s1\",\n      \"kind\": \"prompt\",\n      \"prompt\": \"List the files in the project root.\"\n    },\n    {\n      \"id\": \"s2\",\n      \"kind\": \"assert\",\n      \"assertion\": {\n        \"type\": \"toolCalledWith\",\n        \"toolName\": \"list_files\",\n        \"args\": {\n          \"args\": {}\n        }\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "title": "<string>",
  "steps": [
    {
      "id": "<string>",
      "kind": "prompt",
      "prompt": "<string>",
      "serverName": "<string>",
      "toolName": "<string>",
      "arguments": {},
      "action": {},
      "assertion": {}
    }
  ],
  "iterations": 5,
  "isNegative": true,
  "models": [
    {
      "model": "<string>",
      "provider": "<string>"
    }
  ],
  "declaredId": "<string>",
  "expectedOutput": "<string>",
  "scenario": "<string>",
  "matchOptions": {},
  "checks": {
    "mode": "inherit",
    "list": [
      {}
    ]
  },
  "createdAt": 123,
  "updatedAt": 123
}

API Guides

Endpoints

Authorizations

Path Parameters

Body

Response