Change freshness, thresholds and outcome settings without a new version

curl --request PATCH \
  --url https://api.vainona.ai/v1/namespaces/{ns}/judgments/{name} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "freshness": {
    "debounce_ms": 0,
    "interval": "<string>",
    "max_wait_ms": 2,
    "fanout": {
      "scope": {
        "created_within": "<string>",
        "where": {}
      },
      "debounce_ms": 600000,
      "max_wait_ms": 2,
      "job_above": 1,
      "confirm_jobs": true,
      "auto_daily_limit": 100000
    }
  },
  "thresholds": {},
  "outcomes": {
    "implicit_negatives": false
  },
  "confirm": false
}
'

import requests

url = "https://api.vainona.ai/v1/namespaces/{ns}/judgments/{name}"

payload = {
    "freshness": {
        "debounce_ms": 0,
        "interval": "<string>",
        "max_wait_ms": 2,
        "fanout": {
            "scope": {
                "created_within": "<string>",
                "where": {}
            },
            "debounce_ms": 600000,
            "max_wait_ms": 2,
            "job_above": 1,
            "confirm_jobs": True,
            "auto_daily_limit": 100000
        }
    },
    "thresholds": {},
    "outcomes": { "implicit_negatives": False },
    "confirm": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    freshness: {
      debounce_ms: 0,
      interval: '<string>',
      max_wait_ms: 2,
      fanout: {
        scope: {created_within: '<string>', where: {}},
        debounce_ms: 600000,
        max_wait_ms: 2,
        job_above: 1,
        confirm_jobs: true,
        auto_daily_limit: 100000
      }
    },
    thresholds: {},
    outcomes: {implicit_negatives: false},
    confirm: false
  })
};

fetch('https://api.vainona.ai/v1/namespaces/{ns}/judgments/{name}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vainona.ai/v1/namespaces/{ns}/judgments/{name}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'freshness' => [
        'debounce_ms' => 0,
        'interval' => '<string>',
        'max_wait_ms' => 2,
        'fanout' => [
                'scope' => [
                                'created_within' => '<string>',
                                'where' => [
                                                                
                                ]
                ],
                'debounce_ms' => 600000,
                'max_wait_ms' => 2,
                'job_above' => 1,
                'confirm_jobs' => true,
                'auto_daily_limit' => 100000
        ]
    ],
    'thresholds' => [
        
    ],
    'outcomes' => [
        'implicit_negatives' => false
    ],
    'confirm' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vainona.ai/v1/namespaces/{ns}/judgments/{name}"

	payload := strings.NewReader("{\n  \"freshness\": {\n    \"debounce_ms\": 0,\n    \"interval\": \"<string>\",\n    \"max_wait_ms\": 2,\n    \"fanout\": {\n      \"scope\": {\n        \"created_within\": \"<string>\",\n        \"where\": {}\n      },\n      \"debounce_ms\": 600000,\n      \"max_wait_ms\": 2,\n      \"job_above\": 1,\n      \"confirm_jobs\": true,\n      \"auto_daily_limit\": 100000\n    }\n  },\n  \"thresholds\": {},\n  \"outcomes\": {\n    \"implicit_negatives\": false\n  },\n  \"confirm\": false\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.vainona.ai/v1/namespaces/{ns}/judgments/{name}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"freshness\": {\n    \"debounce_ms\": 0,\n    \"interval\": \"<string>\",\n    \"max_wait_ms\": 2,\n    \"fanout\": {\n      \"scope\": {\n        \"created_within\": \"<string>\",\n        \"where\": {}\n      },\n      \"debounce_ms\": 600000,\n      \"max_wait_ms\": 2,\n      \"job_above\": 1,\n      \"confirm_jobs\": true,\n      \"auto_daily_limit\": 100000\n    }\n  },\n  \"thresholds\": {},\n  \"outcomes\": {\n    \"implicit_negatives\": false\n  },\n  \"confirm\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vainona.ai/v1/namespaces/{ns}/judgments/{name}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"freshness\": {\n    \"debounce_ms\": 0,\n    \"interval\": \"<string>\",\n    \"max_wait_ms\": 2,\n    \"fanout\": {\n      \"scope\": {\n        \"created_within\": \"<string>\",\n        \"where\": {}\n      },\n      \"debounce_ms\": 600000,\n      \"max_wait_ms\": 2,\n      \"job_above\": 1,\n      \"confirm_jobs\": true,\n      \"auto_daily_limit\": 100000\n    }\n  },\n  \"thresholds\": {},\n  \"outcomes\": {\n    \"implicit_negatives\": false\n  },\n  \"confirm\": false\n}"

response = http.request(request)
puts response.read_body

{
  "judgment": {
    "name": "<string>",
    "active_version": 2,
    "freshness": {
      "policy": "on_read",
      "debounce_ms": 0,
      "interval": "<string>",
      "max_wait_ms": 2,
      "fanout": {
        "scope": {
          "created_within": "<string>",
          "where": {}
        },
        "debounce_ms": 600000,
        "max_wait_ms": 2,
        "job_above": 1,
        "confirm_jobs": true,
        "auto_daily_limit": 100000
      }
    },
    "thresholds": {},
    "outcomes": {
      "implicit_negatives": false
    },
    "versions": [
      {
        "version": 2,
        "created_at": "2023-11-07T05:31:56Z",
        "definition": {
          "name": "<string>",
          "question": "<string>",
          "type": "bool",
          "criteria": "<string>",
          "context": {
            "fields": [
              "<string>"
            ],
            "last_n": {},
            "window": {},
            "max_tokens": 2,
            "related": {}
          },
          "engine": {
            "name": "jev",
            "version": "<string>"
          },
          "horizon": "0s",
          "applies_to": {},
          "thresholds": {},
          "parts": [
            {
              "name": "<string>",
              "question": "<string>"
            }
          ],
          "features": [
            "<string>"
          ]
        }
      }
    ],
    "template": "<string>",
    "overrides": [
      "thresholds"
    ],
    "fanout_sources": {
      "scope": {
        "created_within": "judgment",
        "where": "judgment"
      },
      "debounce_ms": "judgment",
      "max_wait_ms": "judgment",
      "job_above": "judgment",
      "confirm_jobs": "judgment",
      "auto_daily_limit": "judgment"
    }
  },
  "job_id": "<string>"
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

Judgments

Change freshness, thresholds and outcome settings without a new version

Freshness settings, thresholds and outcome settings are not part of the definition, so this creates no version (§6.5).

Thresholds replace the judgment’s whole set of named thresholds ({} removes them all). They apply at the next read to every answer, including answers already computed, with no evaluation. Every change is an audit event. A recommended threshold (GET .../thresholds/recommend) is applied this way.
Switching to on_change needs answers for every document: without confirm: true it returns a backfill estimate for the documents with no current answer and changes nothing, thresholds included; with it, the settings apply and the backfill job starts. For an entity judgment (entities, E1) the estimate also has replay, what the judgment would cost a month from then on (§6.9), and a confirmed switch whose replay is more than the namespace’s monthly budget is budget_exceeded.
max_wait_ms (entities, E1) sets the debounce ceiling (§7.3.9).
fanout (entities, E3a) sets which judged documents a change to a referenced document re-judges, and when (§6.5.2). Keys you send replace those keys, and the others keep their values. null for job_above or confirm_jobs clears the judgment’s own value, so it follows the namespace’s again. It never starts a job and never needs confirm. The response’s judgment.fanout_sources says where each value in effect comes from.
outcomes (§6.10) sets how outcomes are read, such as {"implicit_negatives": true} on a bool judgment with a horizon. It is refused on any other judgment, and on a namespace that inherits the judgment (set it on the template’s prefix path).

On a namespace that inherits the judgment from a template, this sets that namespace’s own override, which applies to it alone. On the prefix path it changes the template’s settings for every namespace that has no override (§7.7).

PATCH

namespaces

{ns}

judgments

{name}

Change freshness, thresholds and outcome settings without a new version

curl --request PATCH \
  --url https://api.vainona.ai/v1/namespaces/{ns}/judgments/{name} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "freshness": {
    "debounce_ms": 0,
    "interval": "<string>",
    "max_wait_ms": 2,
    "fanout": {
      "scope": {
        "created_within": "<string>",
        "where": {}
      },
      "debounce_ms": 600000,
      "max_wait_ms": 2,
      "job_above": 1,
      "confirm_jobs": true,
      "auto_daily_limit": 100000
    }
  },
  "thresholds": {},
  "outcomes": {
    "implicit_negatives": false
  },
  "confirm": false
}
'

import requests

url = "https://api.vainona.ai/v1/namespaces/{ns}/judgments/{name}"

payload = {
    "freshness": {
        "debounce_ms": 0,
        "interval": "<string>",
        "max_wait_ms": 2,
        "fanout": {
            "scope": {
                "created_within": "<string>",
                "where": {}
            },
            "debounce_ms": 600000,
            "max_wait_ms": 2,
            "job_above": 1,
            "confirm_jobs": True,
            "auto_daily_limit": 100000
        }
    },
    "thresholds": {},
    "outcomes": { "implicit_negatives": False },
    "confirm": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    freshness: {
      debounce_ms: 0,
      interval: '<string>',
      max_wait_ms: 2,
      fanout: {
        scope: {created_within: '<string>', where: {}},
        debounce_ms: 600000,
        max_wait_ms: 2,
        job_above: 1,
        confirm_jobs: true,
        auto_daily_limit: 100000
      }
    },
    thresholds: {},
    outcomes: {implicit_negatives: false},
    confirm: false
  })
};

fetch('https://api.vainona.ai/v1/namespaces/{ns}/judgments/{name}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vainona.ai/v1/namespaces/{ns}/judgments/{name}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'freshness' => [
        'debounce_ms' => 0,
        'interval' => '<string>',
        'max_wait_ms' => 2,
        'fanout' => [
                'scope' => [
                                'created_within' => '<string>',
                                'where' => [
                                                                
                                ]
                ],
                'debounce_ms' => 600000,
                'max_wait_ms' => 2,
                'job_above' => 1,
                'confirm_jobs' => true,
                'auto_daily_limit' => 100000
        ]
    ],
    'thresholds' => [
        
    ],
    'outcomes' => [
        'implicit_negatives' => false
    ],
    'confirm' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vainona.ai/v1/namespaces/{ns}/judgments/{name}"

	payload := strings.NewReader("{\n  \"freshness\": {\n    \"debounce_ms\": 0,\n    \"interval\": \"<string>\",\n    \"max_wait_ms\": 2,\n    \"fanout\": {\n      \"scope\": {\n        \"created_within\": \"<string>\",\n        \"where\": {}\n      },\n      \"debounce_ms\": 600000,\n      \"max_wait_ms\": 2,\n      \"job_above\": 1,\n      \"confirm_jobs\": true,\n      \"auto_daily_limit\": 100000\n    }\n  },\n  \"thresholds\": {},\n  \"outcomes\": {\n    \"implicit_negatives\": false\n  },\n  \"confirm\": false\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.vainona.ai/v1/namespaces/{ns}/judgments/{name}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"freshness\": {\n    \"debounce_ms\": 0,\n    \"interval\": \"<string>\",\n    \"max_wait_ms\": 2,\n    \"fanout\": {\n      \"scope\": {\n        \"created_within\": \"<string>\",\n        \"where\": {}\n      },\n      \"debounce_ms\": 600000,\n      \"max_wait_ms\": 2,\n      \"job_above\": 1,\n      \"confirm_jobs\": true,\n      \"auto_daily_limit\": 100000\n    }\n  },\n  \"thresholds\": {},\n  \"outcomes\": {\n    \"implicit_negatives\": false\n  },\n  \"confirm\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vainona.ai/v1/namespaces/{ns}/judgments/{name}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"freshness\": {\n    \"debounce_ms\": 0,\n    \"interval\": \"<string>\",\n    \"max_wait_ms\": 2,\n    \"fanout\": {\n      \"scope\": {\n        \"created_within\": \"<string>\",\n        \"where\": {}\n      },\n      \"debounce_ms\": 600000,\n      \"max_wait_ms\": 2,\n      \"job_above\": 1,\n      \"confirm_jobs\": true,\n      \"auto_daily_limit\": 100000\n    }\n  },\n  \"thresholds\": {},\n  \"outcomes\": {\n    \"implicit_negatives\": false\n  },\n  \"confirm\": false\n}"

response = http.request(request)
puts response.read_body

{
  "judgment": {
    "name": "<string>",
    "active_version": 2,
    "freshness": {
      "policy": "on_read",
      "debounce_ms": 0,
      "interval": "<string>",
      "max_wait_ms": 2,
      "fanout": {
        "scope": {
          "created_within": "<string>",
          "where": {}
        },
        "debounce_ms": 600000,
        "max_wait_ms": 2,
        "job_above": 1,
        "confirm_jobs": true,
        "auto_daily_limit": 100000
      }
    },
    "thresholds": {},
    "outcomes": {
      "implicit_negatives": false
    },
    "versions": [
      {
        "version": 2,
        "created_at": "2023-11-07T05:31:56Z",
        "definition": {
          "name": "<string>",
          "question": "<string>",
          "type": "bool",
          "criteria": "<string>",
          "context": {
            "fields": [
              "<string>"
            ],
            "last_n": {},
            "window": {},
            "max_tokens": 2,
            "related": {}
          },
          "engine": {
            "name": "jev",
            "version": "<string>"
          },
          "horizon": "0s",
          "applies_to": {},
          "thresholds": {},
          "parts": [
            {
              "name": "<string>",
              "question": "<string>"
            }
          ],
          "features": [
            "<string>"
          ]
        }
      }
    ],
    "template": "<string>",
    "overrides": [
      "thresholds"
    ],
    "fanout_sources": {
      "scope": {
        "created_within": "judgment",
        "where": "judgment"
      },
      "debounce_ms": "judgment",
      "max_wait_ms": "judgment",
      "job_above": "judgment",
      "confirm_jobs": "judgment",
      "auto_daily_limit": "judgment"
    }
  },
  "job_id": "<string>"
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

An organization API key. Keys carry a role (read_write or read_only) and may be restricted to a namespace prefix such as acme/*, or to one namespace such as acme/prod/tenant_1. A prefix matches on a / boundary: acme/prod/tenant_1* covers acme/prod/tenant_1 and everything under acme/prod/tenant_1/, never acme/prod/tenant_12.

Headers

Idempotency-Key

string

Returns the original response verbatim while the node still caches it. Correctness never depends on it.

Minimum string length: 1

Path Parameters

string

required

A namespace name, or a template prefix ending in /* (§7.7), with any / sent as %2F: acme%2Fprod%2Ftenant_123 or acme%2Fprod%2F*.

A namespace name, or a template prefix: a namespace path ending in /*, such as acme/prod/*, which every namespace under acme/prod/ inherits judgments from (§7.7). Up to 256 bytes.

Required string length: 1 - 256

Pattern: ^[A-Za-z0-9._:/-]+(/\*)?$

name

string

required

A judgment, attribute or threshold name. Names are path segments in field references, so they never contain ..

Required string length: 1 - 128

Pattern: ^[A-Za-z0-9_-]+$

Body

application/json

Option 1
Option 2
Option 3

At least one of freshness, thresholds and outcomes.

freshness

object

required

Settings, not part of the definition. Changing them creates no version.

Show child attributes

thresholds

object

Replaces the judgment's whole set of named thresholds; {} removes them all. Applies at the next read, with no evaluation and no new version.

Show child attributes

outcomes

object

Replaces how outcomes are read. The next nightly fit and every report use it; no version is created.

Show child attributes

confirm

boolean

default:false

Required to switch to on_change, which starts a backfill.

Response

The settings were applied, or an estimate was returned.

Option 1
Option 2

judgment

object

required

Show child attributes

job_id

string

The backfill started by a confirmed switch to on_change.

Namespaces

Documents

Judgments

Outcomes and calibration

Jobs

Engines

Change freshness, thresholds and outcome settings without a new version

Authorizations

Headers

Path Parameters

Body

Response