---
title: "Deploy a verifier (create or new version)"
method: POST
path: "/verifiers"
tags: ["verifiers"]
---

# Deploy a verifier (create or new version)

`POST /verifiers`

## Request

- Base URL: `https://api.goodeye.dev/v1`
- URL: `https://api.goodeye.dev/v1/verifiers`
- Auth: none declared

Create a **caller-owned** verifier or append a new version to one with the same ``name``. First deploy must omit ``expected_version_token``; subsequent deploys must include the latest token returned by deploy, list, or get. Token mismatch returns 409. Creating a new verifier whose ``name`` matches an active platform-managed (``scope=system``) verifier returns 409. Returns ``{verifier_id, name, current_version, version, version_token, status, input_contract, config_hash}``.

## Request body

- DeployVerifierInput: Payload for ``deploy_verifier``: create a new verifier or append a new version to an existing one (owner-scoped, name-uniqueness within owner).
  - `name` string, required: Verifier name, unique per owner among non-revoked verifiers. Lowercase letters, digits, and hyphens; no spaces.
  - `description` string, required: Short human-readable summary of what the verifier judges.
  - `criterion` string, required: The rubric prose the judge applies. Write it as a direct instruction to the judge (e.g. 'Return passed=true when ...').
  - `input_contract` 'text' | 'text_image' | 'image', required: Shape of inputs the verifier judges. ``text``: text fields only (``input_fields`` required, ``media_url`` rejected). ``text_image``: text fields plus one image (both required at run time). ``image``: a single image only (``input_fields`` must be empty, ``media_url`` required).
  - `input_fields` string[]: Names of the text inputs the judge sees. Required for ``text`` and ``text_image``; must be empty for ``image``. Names are deduplicated case-insensitively. ``run_verifier`` rejects callers whose ``inputs`` keys do not match this list exactly.
  - `few_shot_examples` FewShotExample[]: Labeled calibration examples (3 to 10 are typical). Each example must satisfy the contract: ``text`` examples carry only ``inputs``; ``text_image`` carries both ``inputs`` and ``media_url``; ``image`` carries only ``media_url``.
    - `inputs` object: Map of ``input_fields`` name to value. Required for ``text`` and ``text_image`` contracts, must be empty for ``image``.
    - `media_url` string, nullable: Public HTTPS image URL. Required for ``text_image`` and ``image`` contracts, rejected for ``text``.
    - `passed` boolean, required: Ground-truth label: did this example satisfy the criterion?
    - `reasoning` string, nullable: Optional rationale shown to the judge alongside the label.
  - `model_settings` ModelConfig: Verifier judge LM configuration. Only ``model`` and ``reasoning_effort`` are honored; any other field is rejected so callers can't quietly leak sampling knobs (temperature, max_tokens, etc.) into the judge.
    - `model` string: Model identifier for the judge LLM (e.g. ``openai/gpt-5.4-mini``, ``anthropic/claude-sonnet-4-6``). Must be one of the platform's supported models. Defaults to the platform's standard judge model.
    - `reasoning_effort` 'low' | 'medium' | 'high' | 'xhigh': Reasoning budget hint forwarded to providers that accept it. Silently dropped for models that don't expose ``reasoning_effort``.
  - `expected_version_token` string, uuid, nullable: Optimistic-concurrency token. Required when re-deploying an existing verifier to confirm you've seen the latest version (get it from ``deploy_verifier``, ``list_verifiers``, or ``get_verifier``). Must be omitted on first deploy. Mismatch returns a Conflict with the current token.

## Response `201`

Successful Response

- object

## Other responses

- `400`: Validation error: bad contract, fields, or examples.
- `401`: Authentication required.
- `409`: Conflict: missing or mismatched ``expected_version_token``, or name reserved for a platform-managed verifier.
- `422`: Validation Error

---

[API](https://skmtc.dev/goodeye/apis/goodeye-api.md) · [All operations](https://skmtc.dev/goodeye/apis/goodeye-api/llms.txt) · [OpenAPI document](https://skmtc.dev/goodeye/apis/goodeye-api/revisions/547cb8bb6ede?raw)