---
title: "Create a shadow evaluation"
method: POST
path: "/api/v1/evaluations"
tags: ["canonical"]
---

# Create a shadow evaluation

`POST /api/v1/evaluations`

## Request

- Base URL: `https://app.graypass.org` (the document declares no server; this is the origin it was published from)
- URL: `https://app.graypass.org/api/v1/evaluations`
- Auth: HTTP bearer

Register the action selection, observation window and thresholds for an operational shadow study.

## Request body

- EvaluationCreate: Create a shadow integration study for registered actions with explicit success criteria.
  - `action_keys` string[], required: Registered action keys included in the evaluation; the service deduplicates this selection.
  - `ends_at` string, nullable: Timezone-aware ISO 8601 study end, later than starts_at. Creation defaults to 30 days after the start; closing can shorten this cutoff.
  - `name` string, required: Customer-visible display name for the action or evaluation.
  - `starts_at` string, nullable: Timezone-aware ISO 8601 study start. If omitted during creation, the service uses the current time.
  - `success_criteria` EvaluationCriteria: Thresholds for operational integration metrics used to evaluate the selected shadow decisions.
    - `max_abstention_rate` number: Maximum permitted fraction of selected decisions carrying decision.insufficient_evidence, from 0 to 1; default 0.5.
    - `min_outcome_coverage` number: Minimum fraction of selected decisions with recorded customer outcomes, from 0 to 1; default 0.5.
    - `min_shadow_decisions` integer: Minimum number of selected shadow decisions; default 50.

## Response `201`

Open evaluation with deduplicated action keys, recorded thresholds and effective observation window.

- Evaluation: Stored selection, thresholds and observation window for a shadow integration study.
  - `action_keys` string[], required: Registered action keys included in the evaluation; the service deduplicates this selection.
  - `created_at` string, required: Creation time as an ISO 8601 timestamp.
  - `ends_at` string, nullable: Timezone-aware ISO 8601 study end, later than starts_at. Creation defaults to 30 days after the start; closing can shorten this cutoff.
  - `id` string, required: Identifier of this record. Treat it as opaque and retain it for subsequent operations.
  - `name` string, required: Customer-visible display name for the action or evaluation.
  - `starts_at` string, required: Timezone-aware ISO 8601 study start. If omitted during creation, the service uses the current time.
  - `status` 'open' | 'closed', required: Lifecycle state of this record; use the operation-specific values listed in the schema.
  - `success_criteria` EvaluationCriteria, required: Thresholds for operational integration metrics used to evaluate the selected shadow decisions.
    - `max_abstention_rate` number: Maximum permitted fraction of selected decisions carrying decision.insufficient_evidence, from 0 to 1; default 0.5.
    - `min_outcome_coverage` number: Minimum fraction of selected decisions with recorded customer outcomes, from 0 to 1; default 0.5.
    - `min_shadow_decisions` integer: Minimum number of selected shadow decisions; default 50.

## Other responses

- `422`: The canonical handler returns a Problem for invalid input; correct the request before retrying.

---

[API](https://skmtc.dev/graypass/apis/graypass-api.md) - [All operations](https://skmtc.dev/graypass/apis/graypass-api/llms.txt) - [OpenAPI document](https://skmtc.dev/graypass/apis/graypass-api/revisions/5f9ab64fdfdb?raw)