Goodeye Verifiers API

openapi: 3.2.0
info:
  title: Goodeye Verifiers API
  version: 0.1.0
servers:
- url: /v1
tags:
- name: verifiers
paths:
  /verifiers:
    post:
      tags:
      - verifiers
      summary: Deploy a verifier (create or new version)
      description: 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}``.
      operationId: deploy_verifier_route_verifiers_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeployVerifierInput'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Deploy Verifier Route Verifiers Post
        '400':
          description: 'Validation error: bad contract, fields, or examples.'
        '401':
          description: Authentication required.
        '409':
          description: 'Conflict: missing or mismatched ``expected_version_token``, or name reserved for a platform-managed verifier.'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - verifiers
      summary: List active verifiers visible to the caller
      description: 'Returns ``{items: [...], next_cursor: str | null}`` with one entry per non-revoked verifier the caller owns or can access through skill-derived grants. Platform ``scope=system`` verifiers never appear here. Anonymous callers get an empty list.'
      operationId: list_verifiers_route_verifiers_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Verifiers Route Verifiers Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /verifiers/{verifier_id}:
    get:
      tags:
      - verifiers
      summary: Get one verifier version (criterion, contract, calibration)
      description: 'Defaults to the current version; pass ``?version=N`` to pin. Returns the full deploy-time payload plus ``config_hash`` for drift detection. ``verifier_id`` accepts UUID string or accessible user-scope verifier name. Any caller who can reach the verifier can read it: the owner and skill grantees at any role (a view/exec grantee can read, not only run). Platform-managed (``scope=system``), unauthorized, or revoked verifiers are always 404.'
      operationId: get_verifier_version_route_verifiers__verifier_id__get
      parameters:
      - name: verifier_id
        in: path
        required: true
        schema:
          type: string
          title: Verifier Id
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Verifier Version Route Verifiers  Verifier Id  Get
        '401':
          description: Authentication required.
        '404':
          description: Verifier not found, revoked, or not accessible to caller.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - verifiers
      summary: Revoke a verifier
      description: Sets ``status="revoked"`` and ``revoked_at`` for **caller-owned** ``scope=user`` verifiers only (UUID or name). Platform ``scope=system`` verifiers reject as 404. The verifier disappears from list/get/run for the owner; existing run rows are retained. Irreversible; replace by deploying a fresh verifier under a new name.
      operationId: revoke_verifier_route_verifiers__verifier_id__delete
      parameters:
      - name: verifier_id
        in: path
        required: true
        schema:
          type: string
          title: Verifier Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Revoke Verifier Route Verifiers  Verifier Id  Delete
        '401':
          description: Authentication required.
        '404':
          description: Verifier not found, already revoked, or not owned by caller.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /verifiers/{verifier_id}/runs:
    post:
      tags:
      - verifiers
      summary: Run a verifier to check whether an output meets its criterion
      description: Runs the judge against ``inputs`` (and optional ``media_url``). Path ``verifier_id`` is a Verifier UUID, or ``system:`` for platform-managed verifiers. Anonymous callers may run a Verifier UUID iff it appears in some live ``template_versions.verifier_snapshots`` (publicly-runnable gate); spend is gated by the credit ledger. Caller-shape errors return 400 with no row written; runtime errors return 201 with ``status="error"`` and an ``error_code`` of ``runtime_error``, ``verifier_unavailable``, or ``timeout``. Returns ``{verifier_run_id, anonymous_verifier_run_id, verifier_id, version, status, passed, reasoning, duration_ms, created_at}`` (one of ``verifier_run_id`` or ``anonymous_verifier_run_id`` populated). A successful run attributed to a skill you own also echoes that skill's ``skill_id``.
      operationId: run_verifier_route_verifiers__verifier_id__runs_post
      parameters:
      - name: verifier_id
        in: path
        required: true
        schema:
          type: string
          title: Verifier Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_RunVerifierBody'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Run Verifier Route Verifiers  Verifier Id  Runs Post
        '400':
          description: Caller-shape error (bad inputs, missing or excess fields, wrong media).
        '404':
          description: Verifier or referenced skill not visible to caller.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /verifiers/{verifier_id}/permanent:
    delete:
      tags:
      - verifiers
      summary: Permanently delete a verifier
      description: 'Permanently and immediately erase a **caller-owned** ``scope=user`` verifier. The verifier, all its versions (criterion, calibration examples, input contracts), all run records, and all access grants are removed from the live system at once. There is no recovery path. Use ``DELETE /{verifier_id}`` (revoke) to deactivate without erasing, keeping the audit trail intact. Serving gate: if any live published template version carries a snapshot that references this verifier, deletion is refused (409). Unpublish the relevant template version(s) first, then retry. Platform ``scope=system`` verifiers and another user''s verifiers always surface as 404. Encrypted backups age out within the platform''s standard retention window (up to three months), so the data is not instantly erased from all systems everywhere, but it is no longer accessible through any product surface after this call. Returns ``{verifier_id, name, deleted: true}``.'
      operationId: delete_verifier_route_verifiers__verifier_id__permanent_delete
      parameters:
      - name: verifier_id
        in: path
        required: true
        schema:
          type: string
          title: Verifier Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Delete Verifier Route Verifiers  Verifier Id  Permanent Delete
        '401':
          description: Authentication required.
        '404':
          description: Verifier not found, not owned by caller, or platform-managed (scope=system).
        '409':
          description: Verifier is referenced by a live published template version. Unpublish the template version(s) first.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    FewShotExample:
      properties:
        inputs:
          additionalProperties:
            type: string
          type: object
          title: Inputs
          description: Map of ``input_fields`` name to value. Required for ``text`` and ``text_image`` contracts, must be empty for ``image``.
        media_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Media Url
          description: Public HTTPS image URL. Required for ``text_image`` and ``image`` contracts, rejected for ``text``.
        passed:
          type: boolean
          title: Passed
          description: 'Ground-truth label: did this example satisfy the criterion?'
        reasoning:
          anyOf:
          - type: string
          - type: 'null'
          title: Reasoning
          description: Optional rationale shown to the judge alongside the label.
      additionalProperties: false
      type: object
      required:
      - passed
      title: FewShotExample
      description: 'A single labeled example attached to a verifier version. The runtime

        shows these to the judge as calibration demonstrations.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    InputContract:
      type: string
      enum:
      - text
      - text_image
      - image
      title: InputContract
      description: '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).'
    ModelConfig:
      properties:
        model:
          type: string
          maxLength: 128
          minLength: 1
          title: Model
          description: 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:
          type: string
          enum:
          - low
          - medium
          - high
          - xhigh
          title: Reasoning Effort
          description: Reasoning budget hint forwarded to providers that accept it. Silently dropped for models that don't expose ``reasoning_effort``.
          default: medium
      additionalProperties: false
      type: object
      title: ModelConfig
      description: '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.'
    _RunVerifierBody:
      properties:
        version:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Version
          description: Pin to a specific verifier version; defaults to the current version.
        inputs:
          additionalProperties:
            type: string
          type: object
          title: Inputs
          description: Map keyed by the version's ``input_fields``. Keys must match the deployed list exactly; values must be non-empty strings.
        media_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Media Url
          description: Public HTTPS image URL. Required for ``text_image`` and ``image`` contracts, rejected for ``text``.
        skill_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Skill Id
          description: 'Optional skill UUID for provenance. Access-checked: a skill the caller cannot see surfaces as 404.'
        skill_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Skill Version
          description: Skill version invoking this run, paired with ``skill_id``.
        skill_ref:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Skill Ref
          description: Free-form skill label (slug, name) for human-readable provenance.
        run_id:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Run Id
          description: Optional caller-supplied correlation ID stamped onto the run row.
      type: object
      title: _RunVerifierBody
      description: 'Request body for ``POST /verifiers/{verifier_id}/runs``.


        ``inputs`` keys must match the version''s ``input_fields`` exactly.

        ``media_url`` is required for ``text_image`` and ``image`` contracts, and

        rejected for ``text``. Caller-shape errors return 400 with no run row

        written; judge runtime errors return 201 with ``status="error"``.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DeployVerifierInput:
      properties:
        name:
          type: string
          maxLength: 128
          minLength: 1
          pattern: ^[a-z0-9][a-z0-9-]*$
          title: Name
          description: Verifier name, unique per owner among non-revoked verifiers. Lowercase letters, digits, and hyphens; no spaces.
        description:
          type: string
          maxLength: 1024
          minLength: 1
          title: Description
          description: Short human-readable summary of what the verifier judges.
        criterion:
          type: string
          maxLength: 20000
          minLength: 1
          title: Criterion
          description: The rubric prose the judge applies. Write it as a direct instruction to the judge (e.g. 'Return passed=true when ...').
        input_contract:
          $ref: '#/components/schemas/InputContract'
          description: 'Shape of inputs at run time: ``text``, ``text_image``, or ``image``. Drives signature shape and what ``run_verifier`` accepts.'
        input_fields:
          items:
            type: string
          type: array
          title: Input Fields
          description: 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:
          items:
            $ref: '#/components/schemas/FewShotExample'
          type: array
          title: Few Shot Examples
          description: '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``.'
        model_settings:
          $ref: '#/components/schemas/ModelConfig'
          description: Judge LM settings. Only ``model`` and ``reasoning_effort`` are honored; see ``ModelConfig``.
        expected_version_token:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Expected Version Token
          description: 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.
      type: object
      required:
      - name
      - description
      - criterion
      - input_contract
      title: DeployVerifierInput
      description: 'Payload for ``deploy_verifier``: create a new verifier or append a new

        version to an existing one (owner-scoped, name-uniqueness within owner).'