This endpoint is currently in BETA.
Evaluators use AI to assess content to determine which category the content falls into. In a missional context, they can be used to determine whether a person’s activities and content fit into a predetermined step in a faith journey. This assessment can then trigger actions such as displaying more relevant content, or passing the user on to a human that specializes in that area.
Minimal Request Example #
By default, the search will include a) any source your team has uploaded, and b) any source that has been contributed to the global corpus. Here is a minimal 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/evaluatePlease note: you must replace the x-api-key value with your API key and my.gospel.bot with your Agent’s domain.
Full Request Example #
However, the API supports several parameters that will affect the output. Here’s an example of all supported parameters that have an effect on the output:
curl \
--header 'Authorization: Bearer apg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
"content": "Jesus was just a great moral teacher, not God.",
"prompt": "Evaluator instructions ...",
"confidence_threshold": 0.75,
"model": "openai/gpt/5-mini",
"frequency_penalty": 0,
"presence_penalty": 0,
"reasoning_effort": "high",
"temperature": 0.1,
"top_p": 1
}' \
--url https://my.gospel.bot/api/v1/evaluators/sos/evaluatePlease note: you must replace the Authorization bearer token value with your API key and my.gospel.bot with your Agent’s domain.
API Keys #
API keys are provisioned against a given Agent and cannot be used for another Agent.
Global Evaluators #
Several popular existing assessment frameworks are accessible via their unique key to any ministry straight out of the box; e.g., /v1/evaluators/sos/evaluate.
| 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! Now you can use the API your custom evaluator to assess arbitrary content and assign it a category based on your definitions. You can find the URL to your evaluator on the Evaluators listing screen.
