Skip to main content
POST
/
v1
/
evals
/
user-templates
Create User Template
curl --request POST \
  --url https://api.bland.ai/v1/evals/user-templates \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "category": "<string>",
  "modality": "<string>",
  "system_prompt_md": "<string>",
  "prompt_md": "<string>",
  "levels": [
    {}
  ],
  "target_level_keys": [
    {}
  ],
  "visibility": "<string>",
  "from_agent_id": "<string>",
  "from_version_id": "<string>"
}
'
{
  "data": {
    "id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
    "org_id": "b2c3d4e5-6789-abcd-ef01-234567890abc",
    "key": "my_hallucination_check",
    "name": "My Hallucination Check",
    "description": "Customized hallucination detection for our product domain.",
    "category": "quality",
    "modality": "text",
    "system_prompt_md": "You are an expert evaluator assessing whether an AI agent fabricated information.",
    "prompt_md": "Review the conversation and identify any claims that were factually incorrect or unsupported.",
    "levels": [
      {
        "level_key": "no_hallucination",
        "label": "No Hallucination",
        "prompt_md": "The agent made no factually incorrect or unsupported claims.",
        "color": "emerald"
      },
      {
        "level_key": "hallucination_detected",
        "label": "Hallucination Detected",
        "prompt_md": "The agent stated something factually incorrect or unsupported.",
        "color": "rose"
      }
    ],
    "target_level_keys": ["no_hallucination"],
    "visibility": "org",
    "source_agent_id": null,
    "source_version_id": null,
    "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba",
    "created_at": "2026-05-27T10:00:00.000Z",
    "updated_at": "2026-05-27T10:00:00.000Z"
  },
  "errors": null
}

Documentation Index

Fetch the complete documentation index at: https://docs.bland.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Headers

​
authorization
string
required
Your API key for authentication.

​
Body Parameters

​
name
string
Display name for the template. Maximum 120 characters.
​
description
string
Description of the template. Maximum 4000 characters. Pass null to leave blank.
​
category
string
Category label for the template. Maximum 64 characters. Pass null to leave blank.
​
modality
string
Evaluation modality. Either text or audio.
​
system_prompt_md
string
System prompt for the eval agent, in Markdown. Maximum 50000 characters.
​
prompt_md
string
Evaluation prompt, in Markdown. Maximum 50000 characters.
​
levels
array
Ordered scoring levels. Each level object requires level_key (string, 1-64 chars), label (string, 1-80 chars), and prompt_md (string). The color field is optional: one of rose, amber, gold, emerald, blue, indigo, violet, or fog.
​
target_level_keys
array
Array of level_key strings that represent the passing threshold.
​
visibility
string
Access scope for the template. One of private, org, or public.
​
from_agent_id
string
UUID of an existing eval agent to snapshot content from.
​
from_version_id
string
UUID of a specific version of the eval agent to snapshot. Only used when from_agent_id is provided. Defaults to the agent’s current version if omitted.
There are two creation paths. Pass from_agent_id (optionally with from_version_id) to snapshot an existing agent’s content into the template, or pass inline content fields to build one from scratch. When both are supplied, from_agent_id provides the content and inline fields act as overrides.

​
Response

​
id
string
Unique identifier (UUID) for the new template.
​
org_id
string
UUID of the organization that owns this template.
​
key
string
Short key used to reference the template.
​
name
string
Display name of the template.
​
description
string
Description of the template, or null.
​
category
string
Category of the template, or null.
​
modality
string
Evaluation modality. Either text or audio.
​
system_prompt_md
string
System prompt for the eval agent, in Markdown.
​
prompt_md
string
Evaluation prompt, in Markdown.
​
levels
array
Ordered scoring levels.
​
target_level_keys
array
Array of level_key strings that represent the passing threshold.
​
visibility
string
Access scope. One of private, org, or public.
​
source_agent_id
string
UUID of the eval agent this template was snapshotted from, or null.
​
source_version_id
string
UUID of the specific version snapshotted, or null.
​
created_by
string
UUID of the user who created the template, or null.
​
created_at
string
ISO 8601 timestamp of when the template was created.
​
updated_at
string
ISO 8601 timestamp of when the template was last updated.
{
  "data": {
    "id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
    "org_id": "b2c3d4e5-6789-abcd-ef01-234567890abc",
    "key": "my_hallucination_check",
    "name": "My Hallucination Check",
    "description": "Customized hallucination detection for our product domain.",
    "category": "quality",
    "modality": "text",
    "system_prompt_md": "You are an expert evaluator assessing whether an AI agent fabricated information.",
    "prompt_md": "Review the conversation and identify any claims that were factually incorrect or unsupported.",
    "levels": [
      {
        "level_key": "no_hallucination",
        "label": "No Hallucination",
        "prompt_md": "The agent made no factually incorrect or unsupported claims.",
        "color": "emerald"
      },
      {
        "level_key": "hallucination_detected",
        "label": "Hallucination Detected",
        "prompt_md": "The agent stated something factually incorrect or unsupported.",
        "color": "rose"
      }
    ],
    "target_level_keys": ["no_hallucination"],
    "visibility": "org",
    "source_agent_id": null,
    "source_version_id": null,
    "created_by": "9a8b7c6d-5e4f-3210-9876-543210fedcba",
    "created_at": "2026-05-27T10:00:00.000Z",
    "updated_at": "2026-05-27T10:00:00.000Z"
  },
  "errors": null
}
Docs for agents: llms.txt