Checks
Set Checks
Replace an environment’s check config.
PUT
/
v2
/
agents
/
{agent_id}
/
environments
/
{env}
/
checks
Set Checks
curl --request PUT \
--url https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/checks \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"scenario_ids": [
{}
],
"evals": [
{}
],
"evals[].eval_agent_id": "<string>",
"evals[].eval_agent_version_id": "<string>",
"evals[].target_level_keys": [
{}
],
"evals[].required": true,
"enabled": true,
"simulations_count": 123
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/checks"
payload = {
"scenario_ids": [{}],
"evals": [{}],
"evals[].eval_agent_id": "<string>",
"evals[].eval_agent_version_id": "<string>",
"evals[].target_level_keys": [{}],
"evals[].required": True,
"enabled": True,
"simulations_count": 123
}
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
scenario_ids: [{}],
evals: [{}],
'evals[].eval_agent_id': '<string>',
'evals[].eval_agent_version_id': '<string>',
'evals[].target_level_keys': [{}],
'evals[].required': true,
enabled: true,
simulations_count: 123
})
};
fetch('https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/checks', 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://api.bland.ai/v2/agents/{agent_id}/environments/{env}/checks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'scenario_ids' => [
[
]
],
'evals' => [
[
]
],
'evals[].eval_agent_id' => '<string>',
'evals[].eval_agent_version_id' => '<string>',
'evals[].target_level_keys' => [
[
]
],
'evals[].required' => true,
'enabled' => true,
'simulations_count' => 123
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <authorization>"
],
]);
$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://api.bland.ai/v2/agents/{agent_id}/environments/{env}/checks"
payload := strings.NewReader("{\n \"scenario_ids\": [\n {}\n ],\n \"evals\": [\n {}\n ],\n \"evals[].eval_agent_id\": \"<string>\",\n \"evals[].eval_agent_version_id\": \"<string>\",\n \"evals[].target_level_keys\": [\n {}\n ],\n \"evals[].required\": true,\n \"enabled\": true,\n \"simulations_count\": 123\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("authorization", "<authorization>")
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.put("https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/checks")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"scenario_ids\": [\n {}\n ],\n \"evals\": [\n {}\n ],\n \"evals[].eval_agent_id\": \"<string>\",\n \"evals[].eval_agent_version_id\": \"<string>\",\n \"evals[].target_level_keys\": [\n {}\n ],\n \"evals[].required\": true,\n \"enabled\": true,\n \"simulations_count\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/checks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"scenario_ids\": [\n {}\n ],\n \"evals\": [\n {}\n ],\n \"evals[].eval_agent_id\": \"<string>\",\n \"evals[].eval_agent_version_id\": \"<string>\",\n \"evals[].target_level_keys\": [\n {}\n ],\n \"evals[].required\": true,\n \"enabled\": true,\n \"simulations_count\": 123\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "202787b7-f07b-4bb8-9cc3-8383e8475601",
"agent_id": "fd497648-881e-4c22-8641-b7b1d08810bc",
"env_type": "staging",
"enabled": true,
"scenario_ids": [
"b29848b2-2dda-47c6-be10-67d32a0818e7",
"15de9946-b614-484b-a848-47947f21a15a"
],
"scenario_names": [
"Verify identity before account changes",
"Caller disputes a charge"
],
"simulations_count": 3,
"evals": [
{
"eval_agent_id": "43209e25-b51c-421b-b080-653b1fbbba97",
"eval_agent_version_id": "66640bc3-47f1-4dc9-9c09-b8adf4d58205",
"name": "Identity verified",
"target_level_keys": [],
"required": true
},
{
"eval_agent_id": "cf13ff40-580a-4841-b7bb-4ee7e2887925",
"eval_agent_version_id": "31064d1a-fcef-4e34-8520-03f72e801481",
"name": "Tone",
"target_level_keys": ["neutral", "warm"],
"required": false
}
],
"created_at": "2026-09-03T10:12:45.771Z",
"updated_at": "2026-09-10T15:48:02.236Z"
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "scenario_ids and evals are required arrays"
}
]
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "One or more scenarios do not belong to this agent"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
Overview
Creates or fully replaces the check config for one environment: the test scenarios to drive conversations from, the judges that score them, and how many conversations to generate per scenario. The whole config is validated up front, so an unrunnable config fails here with400 BAD_REQUEST instead of erroring mid-run. Runs already in flight keep the config they started with. Read it back with Get Checks and run it with Start Check Run.
Requires an admin, owner, operator, or prompter role.
Headers
Path Parameters
staging or production. Checks do not attach to dev. Any other value returns 400 BAD_REQUEST.Body Parameters
IDs of this agent’s test scenarios, 1 to 5 after duplicates are removed. Every ID must belong to this agent and must target the agent rather than a pathway. Returns
400 BAD_REQUEST otherwise.The judges to attach. At least one, and each judge may appear once. Returns
400 BAD_REQUEST when a judge or judge version is not found in your organization, the version does not belong to the judge, or the version is not runnable.The judge version to pin. Must belong to
eval_agent_id. Runs keep using this version until you replace the config.For graded judges, the level keys counted as passing. At least one is required, and each must be a level defined on the pinned version. For pass/fail judges, omit it or pass an empty array; any level key returns
400 BAD_REQUEST.true makes the judge blocking: a run fails when this judge fails. false makes it informational; its verdict is reported but never fails the run.Whether check runs can be started for this environment. Because this endpoint replaces the whole config, omitting it re-enables a disabled config.
Conversations to generate per scenario on each run. Fractional values are floored and the result is clamped to 1 to 50, then rejected with
400 BAD_REQUEST if it exceeds your organization’s per-scenario limit (10 unless raised for your account).Response
The saved check config.
Show check config object
Show check config object
One entry per judge, in the order submitted.
{
"data": {
"id": "202787b7-f07b-4bb8-9cc3-8383e8475601",
"agent_id": "fd497648-881e-4c22-8641-b7b1d08810bc",
"env_type": "staging",
"enabled": true,
"scenario_ids": [
"b29848b2-2dda-47c6-be10-67d32a0818e7",
"15de9946-b614-484b-a848-47947f21a15a"
],
"scenario_names": [
"Verify identity before account changes",
"Caller disputes a charge"
],
"simulations_count": 3,
"evals": [
{
"eval_agent_id": "43209e25-b51c-421b-b080-653b1fbbba97",
"eval_agent_version_id": "66640bc3-47f1-4dc9-9c09-b8adf4d58205",
"name": "Identity verified",
"target_level_keys": [],
"required": true
},
{
"eval_agent_id": "cf13ff40-580a-4841-b7bb-4ee7e2887925",
"eval_agent_version_id": "31064d1a-fcef-4e34-8520-03f72e801481",
"name": "Tone",
"target_level_keys": ["neutral", "warm"],
"required": false
}
],
"created_at": "2026-09-03T10:12:45.771Z",
"updated_at": "2026-09-10T15:48:02.236Z"
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "scenario_ids and evals are required arrays"
}
]
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "One or more scenarios do not belong to this agent"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
Docs for agents: llms.txt
Was this page helpful?
⌘I
Set Checks
curl --request PUT \
--url https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/checks \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"scenario_ids": [
{}
],
"evals": [
{}
],
"evals[].eval_agent_id": "<string>",
"evals[].eval_agent_version_id": "<string>",
"evals[].target_level_keys": [
{}
],
"evals[].required": true,
"enabled": true,
"simulations_count": 123
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/checks"
payload = {
"scenario_ids": [{}],
"evals": [{}],
"evals[].eval_agent_id": "<string>",
"evals[].eval_agent_version_id": "<string>",
"evals[].target_level_keys": [{}],
"evals[].required": True,
"enabled": True,
"simulations_count": 123
}
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
scenario_ids: [{}],
evals: [{}],
'evals[].eval_agent_id': '<string>',
'evals[].eval_agent_version_id': '<string>',
'evals[].target_level_keys': [{}],
'evals[].required': true,
enabled: true,
simulations_count: 123
})
};
fetch('https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/checks', 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://api.bland.ai/v2/agents/{agent_id}/environments/{env}/checks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'scenario_ids' => [
[
]
],
'evals' => [
[
]
],
'evals[].eval_agent_id' => '<string>',
'evals[].eval_agent_version_id' => '<string>',
'evals[].target_level_keys' => [
[
]
],
'evals[].required' => true,
'enabled' => true,
'simulations_count' => 123
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <authorization>"
],
]);
$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://api.bland.ai/v2/agents/{agent_id}/environments/{env}/checks"
payload := strings.NewReader("{\n \"scenario_ids\": [\n {}\n ],\n \"evals\": [\n {}\n ],\n \"evals[].eval_agent_id\": \"<string>\",\n \"evals[].eval_agent_version_id\": \"<string>\",\n \"evals[].target_level_keys\": [\n {}\n ],\n \"evals[].required\": true,\n \"enabled\": true,\n \"simulations_count\": 123\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("authorization", "<authorization>")
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.put("https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/checks")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"scenario_ids\": [\n {}\n ],\n \"evals\": [\n {}\n ],\n \"evals[].eval_agent_id\": \"<string>\",\n \"evals[].eval_agent_version_id\": \"<string>\",\n \"evals[].target_level_keys\": [\n {}\n ],\n \"evals[].required\": true,\n \"enabled\": true,\n \"simulations_count\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/checks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"scenario_ids\": [\n {}\n ],\n \"evals\": [\n {}\n ],\n \"evals[].eval_agent_id\": \"<string>\",\n \"evals[].eval_agent_version_id\": \"<string>\",\n \"evals[].target_level_keys\": [\n {}\n ],\n \"evals[].required\": true,\n \"enabled\": true,\n \"simulations_count\": 123\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "202787b7-f07b-4bb8-9cc3-8383e8475601",
"agent_id": "fd497648-881e-4c22-8641-b7b1d08810bc",
"env_type": "staging",
"enabled": true,
"scenario_ids": [
"b29848b2-2dda-47c6-be10-67d32a0818e7",
"15de9946-b614-484b-a848-47947f21a15a"
],
"scenario_names": [
"Verify identity before account changes",
"Caller disputes a charge"
],
"simulations_count": 3,
"evals": [
{
"eval_agent_id": "43209e25-b51c-421b-b080-653b1fbbba97",
"eval_agent_version_id": "66640bc3-47f1-4dc9-9c09-b8adf4d58205",
"name": "Identity verified",
"target_level_keys": [],
"required": true
},
{
"eval_agent_id": "cf13ff40-580a-4841-b7bb-4ee7e2887925",
"eval_agent_version_id": "31064d1a-fcef-4e34-8520-03f72e801481",
"name": "Tone",
"target_level_keys": ["neutral", "warm"],
"required": false
}
],
"created_at": "2026-09-03T10:12:45.771Z",
"updated_at": "2026-09-10T15:48:02.236Z"
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "scenario_ids and evals are required arrays"
}
]
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "One or more scenarios do not belong to this agent"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}