Evaluators use AI to assess content — for example, which category a statement falls into on a faith journey map. In a missional context, they can determine whether a person’s activities and content fit a predetermined step, then trigger actions such as displaying more relevant content or routing the user to a specialist.
Benchmarks group evaluators and questions so you can run a suite of assessments in one request (including against chat completions or corpus sources). Benchmarks were formerly called evaluator groups.
These endpoints require the Agent capability for the evaluator API (has_evaluator_api). Contact us if you need it enabled for your Agent.
Authentication #
See Authentication on the Overview page for how to authenticate Fusion API requests. List and get endpoints always require an API key.
Evaluate Content #
Use POST /api/v1/evaluators/{id}/evaluations to run an evaluator against content. The path {id} may be the evaluator’s numeric id or its key (for example sos).
The legacy path /api/v1/evaluators/{id}/evaluate is rewritten to /evaluations for compatibility; new integrations should use /evaluations.
Minimal Request Example #
curl --header 'x-api-key: apg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' --header 'Content-Type: application/json' --data '{
"content": "Jesus was just a great moral teacher, not God."
}' --url https://my.gospel.bot/api/v1/evaluators/sos/evaluationsPlease note: replace the x-api-key value with your API key and my.gospel.bot with your Agent’s domain.
Full Request Example #
content is required (string, or an array of chat messages). Additional properties are rejected.
curl --header 'Authorization: Bearer apg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' --header 'Content-Type: application/json' --data '{
"content": "Jesus was just a great moral teacher, not God.",
"score_threshold": 0.75,
"value_threshold": 1,
"model": "openai/gpt/5-mini",
"frequency_penalty": 0,
"presence_penalty": 0,
"reasoning_effort": "high",
"verbosity": "medium",
"temperature": 0.1,
"top_p": 1
}' --url https://my.gospel.bot/api/v1/evaluators/sos/evaluationsRequest Body #
| Field | Type | Description |
|---|---|---|
content | string | array | Required. Text to evaluate (2–100000 chars), or a messages array |
model | string | Optional model override |
score_threshold | number | Optional pass/fail score threshold override |
value_threshold | number | Optional numeric value threshold override |
temperature | number | Optional |
top_p | number | Optional |
frequency_penalty | number | Optional |
presence_penalty | number | Optional |
reasoning_effort | string | low, medium, or high |
verbosity | string | minimal, low, medium, or high |
Response #
{
"id": "11111111-1111-1111-1111-111111111111",
"evaluator_id": 1,
"evaluator_name": "Spiritual Openness Score",
"content": "Jesus was just a great moral teacher, not God.",
"started_at": "2026-07-22 12:00:00",
"completed_at": "2026-07-22 12:00:02",
"score": 0.9,
"passed": true,
"reasoning": "...",
"resolved_input": null,
"benchmark_run_id": null,
"benchmark_question_id": null,
"agent_id": 42,
"input_tokens": 10,
"output_tokens": 5,
"reasoning_tokens": null
}The public id is a UUID. Numeric ids are still accepted when fetching a single evaluation.
List Evaluations #
Use GET /api/v1/evaluators/{id}/evaluations for a paginated list of past evaluations for that evaluator, newest first.
Pagination #
| Parameter | Type | Default | Max | Description |
|---|---|---|---|---|
page | integer | 1 | — | Page number |
per_page | integer | 50 | 100 | Records per page |
Filter Parameters #
| Parameter | Type | Description |
|---|---|---|
min_timestamp / max_timestamp | string | Filter by start time (ISO 8601) |
min_duration / max_duration | number | Duration filters |
min_score / max_score | number | Score filters |
passed | boolean | true or false |
benchmark | string | integer | Filter evaluations tied to a benchmark |
benchmark_run_id | string | integer | Filter by benchmark run |
benchmark_question_id | string | integer | Filter by benchmark question |
Response #
{
"data": [ /* evaluation objects */ ],
"total": 142,
"page": 1,
"per_page": 50
}Get Evaluation #
Use GET /api/v1/evaluators/{id}/evaluations/{evaluationId} to fetch a single evaluation by UUID or legacy numeric id.
{
"data": { /* evaluation object */ }
}Benchmarks #
Use /api/v1/benchmarks/{id}/runs to execute a configured benchmark (a set of evaluators and questions). The path {id} may be the benchmark’s numeric id or key.
Run a Benchmark #
POST /api/v1/benchmarks/{id}/runs — body may be empty ({}) to run the benchmark’s configured questions. Optional fields:
| Field | Type | Description |
|---|---|---|
content | string | array | Optional content to evaluate (used with question flow or source_id) |
completion_id | string (UUID) | Evaluate an existing chat completion instead of running questions |
source_id | integer | Evaluate a corpus source; requires content |
num_responses | integer | 1–10 completions per question (default 1) |
use_question_variants | boolean | Include configured question variants when present |
score_threshold / value_threshold | number | Optional threshold overrides |
model, temperature, top_p, … | various | Same LLM knobs as single evaluations, including verbosity and reasoning_effort |
When completion_id or source_id is supplied, the question set is skipped and each benchmark evaluator runs once against that target.
curl --request POST --header 'x-api-key: apg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' --header 'Content-Type: application/json' --data '{
"completion_id": "11111111-1111-1111-1111-111111111111",
"num_responses": 1
}' --url https://my.gospel.bot/api/v1/benchmarks/my-benchmark/runsA successful run returns an aggregate object including score, passed, nested evaluators, questions, and evaluations. The run id is a UUID. The field formerly named prompt_id is now completion_id.
List and Get Benchmark Runs #
GET /api/v1/benchmarks/{id}/runs— paginated list (page,per_page, plus filters such as timestamps, score,passed,min_responses,max_responses)GET /api/v1/benchmarks/{id}/runs/{runId}— single run by UUID or numeric id
Global Evaluators #
Several popular assessment frameworks are available by key out of the box; for example /api/v1/evaluators/sos/evaluations.
| Name | Key | Description |
| Spiritual Openness Score | sos | A proprietary scoring framework based heavily on the Cru Audience Map, but quantified to enable threshold triggering for our calls to action system. |
| Cru Audience Map | cru_audience_map | In a rapidly changing world where the human heart is not easily understood, the Audience Map helps you see and understand how people move on their spiritual journey and provides a framework for positioning what your ministry has to offer them. Rooted in data but centered on people, the Audience Map equips you to love more like Jesus: seeing individuals as they truly are and meeting them with truth, patience, and understanding. |
| Engel Scale | engel_scale | “The Engel Scale” originates with James F Engel, from the book What’s gone wrong with the harvest?, published by Zondervan in 1975. The insight into evangelism that is generally drawn from the Engel scale is that all people go on a journey or process on their way to conversion and then on into discipleship. |
| Seeker Map | seeker_map | A proprietary framework focused on categorizing seekers, while painting with a broad brush for existing believers. |
| Sentiment | sentiment | Standard sentiment analysis: Positive, Negative, Neutral. |
Custom Evaluators #
In addition, ministries may create custom evaluators to suit their specific use cases. Follow the directions below to do so:
- Click on the “Evaluators” link on the left nav. This will take you straight to the form where you can create a new Evaluator.
- Enter a name and optional description. Be sure to toggle the new Evaluator to Active when you’re ready to use it.
- Next, head to the “Instructions” tab. This is where you customize the Evaluator prompt. A default that usually works great is provided. Exercise caution if attempting to change it. Note that the {options} and {descriptions} merge fields must exist in the prompt to dynamically inject the categories and their definitions.
- Finally, click on the “Model” tab. The recommended model is pre-selected, but you may change it if desired. A lower powered model is usually sufficient, but feel free to experiment with higher powered models if the lower powered ones don’t cut it.
- Click the “Save” button to save the new Evaluator.
- Now it’s time to define the categories to be evaluated against. Scroll down past the main Evaluator form to the “Options” tab. Click on the “Add Evaluator Option” to create a new category.
- Enter a name and optional description, and be sure to toggle the new category to Active. The Numeric Value is optional as well; it will help provide a quantified value for your category, allowing your custom use case to utilize mathematical thresholds. Save the category when done.
- Repeat steps 6 & 7 until all categories are accounted for.
- That’s it! Call
POST /api/v1/evaluators/{your-key-or-id}/evaluationsto assess content. You can find the key for your evaluator on the Evaluators listing screen.
Error Responses #
| Status | Meaning |
|---|---|
400 | Invalid JSON or request error |
403 | Missing/invalid API key, or evaluator API capability not enabled for this Agent |
404 | Evaluator, benchmark, evaluation, or run not found |
422 | Body failed schema validation (unknown fields such as legacy confidence_threshold or prompt are rejected) |
500 | Internal server error |
503 | Agent not found or inactive for the request’s host |