Retrieve an evaluator

GET

https://api.respan.ai/api/evaluators/:evaluator_id/

GET

/api/evaluators/:evaluator_id/

$ curl https://api.respan.ai/api/evaluators/evaluator_id/ \
>      -H "Authorization: Bearer <respanApiKey>"

1 {
2   "id": "evl_550e8400",
3   "name": "Response Quality",
4   "type": "llm",
5   "score_value_type": "numerical",
6   "version_id": "evlv_550e8400",
7   "version": 1,
8   "is_read_only": false,
9   "version_description": "Tightened rubric wording",
10   "evaluator_slug": "response_quality",
11   "eval_class": "keywordsai_custom_llm",
12   "description": "Grades whether the response is accurate and complete.",
13   "score_config": {
14     "min_score": 1,
15     "max_score": 5,
16     "choices": [
17       {
18         "name": "Excellent",
19         "value": "excellent"
20       }
21     ]
22   },
23   "passing_conditions": {
24     "primary_score": {
25       "operator": "gte",
26       "value": 3
27     }
28   },
29   "llm_config": {
30     "model": "gpt-4o-mini",
31     "evaluator_definition": "Rate the response quality.\n<input>{{input}}</input>\n<output>{{output}}</output>",
32     "scoring_rubric": "1=Poor, 5=Excellent",
33     "temperature": 0.1,
34     "max_tokens": 200,
35     "top_p": 1.1,
36     "frequency_penalty": 1.1,
37     "presence_penalty": 1.1,
38     "stop": [
39       "string"
40     ],
41     "response_format": {},
42     "tools": [
43       {}
44     ],
45     "verbosity": "string"
46   },
47   "code_config": {
48     "eval_code_snippet": "def main(eval_inputs):\n    return 1 if eval_inputs.get('output') else 0"
49   },
50   "configurations": {},
51   "categorical_choices": [
52     {
53       "name": "Excellent",
54       "value": "excellent"
55     }
56   ],
57   "starred": false,
58   "created_at": "2024-01-15T09:30:00Z",
59   "updated_at": "2024-01-15T09:30:00Z",
60   "created_by": {
61     "id": 1,
62     "first_name": "string",
63     "last_name": "string",
64     "email": "string"
65   },
66   "updated_by": {
67     "id": 1,
68     "first_name": "string",
69     "last_name": "string",
70     "email": "string"
71   },
72   "editor": {
73     "id": 1,
74     "first_name": "string",
75     "last_name": "string",
76     "email": "string"
77   },
78   "tags": [
79     {
80       "id": 1,
81       "name": "string",
82       "color": "string"
83     }
84   ],
85   "is_public": true
86 }

Retrieve the current draft/latest version of an evaluator by ID.

Authentication

AuthorizationBearer

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

AuthorizationBearer

Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.

Path parameters

evaluator_idstringRequired

Evaluator ID. To run a specific version, pass an ID with a version suffix where supported, for example evl_abc123:2.

Response

Evaluator details.

idstring

Stable evaluator ID shared by all versions.

namestring

typeenum

score_value_typeenum

version_idstringOptional

Unique ID for this evaluator version.

versionintegerOptional

Version number. The first draft is version 0.

is_read_onlybooleanOptional

Whether this version is committed and immutable.

version_descriptionstringOptional

Commit message for this version.

evaluator_slugstringOptional

Organization-scoped evaluator slug.

eval_classenumOptional

Optional pre-built evaluator template.

descriptionstring or nullOptional

score_configobjectOptional

Score configuration. For numerical/percentage scores, use min_score and max_score. For select scores, use choices.

passing_conditionsobject or nullOptional

Passing conditions in the standard Respan filter format.

llm_configobject or nullOptional

LLM grader configuration. The backend validates this against the selected evaluator form.

code_configobject or nullOptional

Code grader configuration.

configurationsmap from strings to anyOptional

Legacy user-facing configuration object. New clients should prefer llm_config, code_config, score_config, and passing_conditions.

categorical_choiceslist of objects or nullOptional

starredbooleanOptional

created_atdatetimeOptional

updated_atdatetimeOptional

created_byobjectOptional

updated_byobjectOptional

editorobjectOptional

tagslist of objectsOptional

is_publicbooleanOptionalRead-only

Whether this is a Respan-managed public evaluator.

Errors

401

Unauthorized Error

404

Not Found Error