Evaluation API

Authenticate a request, submit text, and interpret the decision and completion diagnostics.

Base URL and authentication

Send requests to your backend API origin, such as https://api.nyraxis.io or http://127.0.0.1:8000 for local development. The frontend's /docs route is this documentation site, not the evaluation API.

Use an issued ingest key in the X-API-Key header. full also permits ingestion; read and test keys do not authorize evaluation. Dashboard session authentication is a separate path. See keys and access.

POST /api/v1/evaluate

Terminal

curl --fail-with-body "$NYRAXIS_BASE_URL/api/v1/evaluate" \
  -H "X-API-Key: $NYRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"input":"Demo-only internal password is DEMO-ONLY-NEVER-USE.","agent_name":"quickstart-support","capture_mode":"metadata"}'

Use this synthetic credential marker only. Configure the applicable Secrets Detection policy before running the request. The policy decision normally returns HTTP 200, including allowed: false.

Field	Type / default	Meaning
`input`	Required non-empty string	Text to evaluate; required even when `output` is supplied.
`output`	Optional string	Proposed generated text or tool result to check before release.
`agent_name`	String; `"default"` when omitted	Agent identity within the key's organization. An unknown name can provision an agent, subject to quota.
`policies`	Optional string array	Explicit detector-type selection. Normally omit to use enabled scoped policies.
`mode`	`"thorough"`	`"fast"` or `"thorough"`; see depth semantics.
`capture_mode`	Optional `"metadata"` or `"full"`	May reduce the organization's permitted capture level, never widen it.
`no_trace`	Boolean; `false`	Skip evaluation trace/span recording. Evaluation still processes submitted text.
`metadata`	Optional object	API-level metadata; retention is subject to the capture policy. Not all SDK methods expose this field.

An explicit non-empty policies list requests those detector types with their default configuration and blocking behavior. It does not select configured policy IDs, inherit custom thresholds, or preserve their warning mode. Prefer omitting the field for a normal application integration. policy_versions can be empty for explicit ad-hoc checks.

Interpret the response

Illustrative response shape; IDs, timings, descriptions, and versions vary:

Example response

{
  "allowed": false,
  "violations": [{
    "policy_type": "secrets_detection",
    "severity": "critical",
    "description": "Secret/credential detected in input: PASSWORD",
    "details": {"location": "input", "secret_types": ["PASSWORD"]}
  }],
  "latency_ms": 12.4,
  "mode": "thorough",
  "policies_evaluated": 1,
  "trace_id": "11111111-1111-4111-8111-111111111111",
  "provisioned": false,
  "provisioned_message": null,
  "evaluation_status": "complete",
  "errors": [],
  "policy_versions": {"22222222-2222-4222-8222-222222222222": 1},
  "capture_mode": "metadata"
}

For a required check, permit the next operation only when all four conditions hold:

allowed is true.
evaluation_status is complete.
errors is empty.
policies_evaluated is greater than zero.

A warning policy can return findings while allowing the request. A failed blocking detector can deny the request without a normal finding. Incomplete states are degraded, unavailable, and not_configured.

The API response is not the same as retained evidence. Metadata-only stored traces can withhold descriptions and content. Treat response diagnostics as potentially sensitive and avoid printing them wholesale.

Errors and retry

Status	Action
`401`	Check key value, revocation, and backend destination.
`403`	Check key scope or access; do not turn an access denial into an allow.
`409`	A related resource conflicts; inspect the operation before retrying.
`422`	Correct the request fields.
`429`	Respect rate limits or workspace quota; apply bounded backoff.
`5xx` or timeout	A required check did not authorize the operation. Return a controlled unavailable response.

Evaluation can record evidence and consume quota. A retry may produce another trace; it is not a general exactly-once operation. Keep the protected model/tool operation outside automatic request retries.

Telemetry ingestion

POST /api/v1/ingest/otel accepts OTLP/HTTP protobuf from a configured exporter using an ingest or full key. /api/v1/ingest/otlp is the legacy JSON ingestion path. Do not send OTLP protobuf to the JSON route. See tracing.

Other interfaces

Purpose	Interface
Liveness	`GET /health`
Dependency readiness	`GET /ready`
Deployment-specific OpenAPI schema	Backend `/openapi.json` and `/docs`, when exposed by the operator
Saved Test Lab suite in CI	`POST /api/v1/testing/ci/suites/{suite_id}/run`
Connected-agent regression in CI	`POST /api/v1/testing/ci/regressions/{case_id}/run`

CI uses a separate test key and returns a queued job receipt. See regressions and CI. UI management endpoints use authenticated, organization-scoped sessions; a read key is not a universal dashboard API credential.