SEsenso
Evals

Evaluate text you supply

Judges arbitrary text with no setup — paste a draft, an answer, or a page and have every factual claim it makes about your brand checked against your knowledge base (the default kb_accuracy evaluator), or its writing graded against your brand kit (brand_alignment). The text is stored with the run and returned in the run detail. By default the run is queued and a 202 returns the run to poll at GET /org/evals/runs/{runId}. With wait: true the connection is held and the finished run is returned as a 200; if the run has not finished within the server's wait ceiling (about a minute), the response degrades to the 202 handle and the run keeps executing. Send an idempotency_key to make a retried trigger return the original run instead of judging the same text twice.

post/org/evals/text

Request

  • Base URL
    https://apiv2.senso.ai/api/v1
  • Auth
    API key in header X-API-Key

Request body

evaluator'kb_accuracy' | 'brand_alignment'

Which check to run. kb_accuracy verifies the text's factual claims about your brand against your knowledge base. brand_alignment grades the text against your brand kit's writing rules and needs a brand kit with rules configured, otherwise the run ends failed. Defaults to kb_accuracy.

evaluator_versionstring

Pin an exact evaluator version (see latest_version on GET /org/evals/evaluators). Omit for the current version. An unknown version is a 422.

judge_modelstring

Override the model that judges the text. Must be on the server's allowlist, otherwise a 422. Omit for the evaluator's default.

labelstring

A free-form tag stored on the run for finding it later.

idempotency_keystring

Makes the trigger safe to retry. A second trigger with the same key in your organization returns the original run instead of judging again.

waitboolean

Hold the connection until the run finishes and return the full run as a 200. If the server's wait ceiling lapses first, the response degrades to the 202 run handle and the run keeps executing.

textstring required

The text to judge. An empty string is a 400; text that is only whitespace is a 422.

titlestring

Optional title, stored with the run's subject.

Response

The run finished within the wait ceiling (wait: true only) — the full run, including claims, verdicts, and the judge's audit trail.

eval_run_idstring uuid required
evaluator_keystring required

The evaluator that ran, e.g. kb_accuracy or brand_alignment.

evaluator_versionstring required

The evaluator version this run was pinned to.

status'queued' | 'running' | 'completed' | 'gated' | 'failed' | 'canceled' required

queued — waiting for a worker. running — being judged. completed — judged, with metrics and claims. gated — a pre-check found nothing to judge (an empty answer or a refusal), so the run ended with no model spend; the reason is under outputs.gates in the run detail. failed — the judgment could not complete; see error_code and error_message. canceled is reserved and not currently produced. A run is finished when its status is completed, gated, or failed.

subject_type'content' | 'content_generation_run_item' | 'builder_workspace_version' | 'question_run' | 'search_turn' | 'inline' required

What was judged — inline for text supplied to POST /org/evals/text, content for a saved content item. Other values belong to runs triggered elsewhere in Senso.

subject_idstring uuid

The judged item's id — the content_id for a content run. Absent for inline text.

subject_version_idstring uuid

The exact content version that was judged. Absent for inline text.

judge_modelstring required

The model that judged the text.

labelstring

The label supplied on the trigger, if any.

metricsobject nullable

The evaluator's reported metrics, keyed as its metric descriptors describe them (GET /org/evals/evaluators). For kb_accuracy these are accuracy_pct, coverage_pct, contradiction_pct, and band, plus grounding_failures and kb_internal_conflicts when non-zero. For brand_alignment they are the metrics its descriptors list, such as brand_score and brand_verdict. Present once the run has completed.

claims_totalinteger

Claims extracted from the text. Present once the run has completed; 0 for brand_alignment, which grades rules rather than claims.

claims_scoredinteger

Claims that counted toward the score — those about your brand and verifiable. Present once completed; 0 for brand_alignment.

accuracy_pctnumber

Share of scored claims the knowledge base verified, 0–100. Claim-based evaluators only.

band'green' | 'yellow' | 'red'

Traffic-light reading of accuracy_pct against the evaluator's cut-offs. Claim-based evaluators only.

total_costnumber

Judge model spend for this run, in US dollars. Recorded for transparency; not billed to your credits.

error_codestring

Why a failed run failed, e.g. judge_failed or dispatch_failed.

error_messagestring

Detail for error_code.

created_atstring date-time required
finished_atstring date-time

When the run reached a finished status. Absent while queued or running.

subjectobject

The subject exactly as it was judged, so later edits cannot change what a verdict refers to. For inline text: title and text. For a content item: content_id, content_version_id, version_num, title, editorial_status, and text.

outputsobject nullable

Structured detail too bulky or too shaped for metrics, present once the run has been processed. Includes gates, the pre-check result (passed, answer_produced, is_refusal, sources_present, and reason and detail when the run was gated). kb_accuracy adds mode, relevance_floor, and search_type; brand_alignment adds its full review under brand_alignment. extraction_salvaged or result_salvaged flag a run whose model output had to be partially recovered.

searches_over_budgetinteger

Searches the judge wanted to run beyond its budget. Non-zero means some claims were judged on less evidence than the judge asked for.

Example response

{
  "evaluator_version": "1.1",
  "claims": [
    {
      "claim_key": "c15"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.