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"
}
]
}
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
string
required
Your API key for authentication.
Path Parameters
string
required
The agent’s unique identifier.
string
required
staging or production. Checks do not attach to dev. Any other value returns 400 BAD_REQUEST.Body Parameters
array
required
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.array
required
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.string
required
The judge’s unique identifier.
string
required
The judge version to pin. Must belong to
eval_agent_id. Runs keep using this version until you replace the config.array
default:"[]"
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.boolean
default:"true"
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.boolean
default:"true"
Whether check runs can be started for this environment. Because this endpoint replaces the whole config, omitting it re-enables a disabled config.
integer
default:"5"
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
object
The saved check config.
Show check config object
Show check config object
string
Unique identifier for the check config. Stable across replacements for the same environment.
string
The agent the config belongs to.
string
The environment the config gates:
staging or production.boolean
Whether check runs can be started for this environment.
array
The saved scenario IDs, duplicates removed.
array
Display names for
scenario_ids, in the same order.integer
The saved conversations-per-scenario count, after clamping.
array
The judges attached to the config. See
data.evals below.string
ISO 8601 timestamp the config was first created.
string
ISO 8601 timestamp of this update.
array
One entry per judge, in the order submitted.
null | array
null on success, or a list of error objects if the request failed.{
"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?