Skip to content
KataraKatara documentation

Read an immutable evidence preview

GET
/katara/v1/orgs/{org_id}/promotion-evidence/previews/{id}
curl --request GET \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/promotion-evidence/previews/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

Requires a signed-in human owner session and current owner authority in both the source Test and destination Live environments. API keys, service identities and workloads are refused. Reads and later changes derive environment bindings from the immutable declaration, preview or receipt. Query parameters are rejected. Responses are no-store. A criteria_met calibration certificate is necessary but does not authorize publication: explicit human quality policy, complete actual-run correspondence, current dependencies and a separate owner approval are required. Paid scores and calibration certificates retain their uncalibrated status. Returns immutable recorded metadata under current owner authority; a historical read does not certify that publication remains authorized.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000

Header Parameters

Section titled “Header Parameters”
X-Katara-Account-ID
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Required for cookie-authenticated changes. Use the UUID of the account that loaded the application. A different current cookie account returns account_changed before the handler runs. Session bearer and API key clients do not require this header.

Responses

Section titled “Responses”

200

Section titled “200”

Successful request

Media typeapplication/json
object
preview
required
object
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
input
required
object
declaration
required
object
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
candidate
required
object
certificate
required
object
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
runs
required
Array<object>
>= 1 items <= 1000 items
object
case_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
key
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
run_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
agent_version_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
reset_epoch
required
integer
>= 1 <= 9007199254740991
mode
required
Allowed value: test
usage
required
Allowed value: test_compute
baseline
required
One of:
object
certificate
required
object
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
runs
required
Array<object>
>= 1 items <= 1000 items
object
case_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
key
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
run_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
agent_version_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
reset_epoch
required
integer
>= 1 <= 9007199254740991
mode
required
Allowed value: test
usage
required
Allowed value: test_compute
candidate
required
Array<object>
>= 1 items <= 1000 items
object
case_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
assessment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
assessment_digest
required
string
/^sha256:[a-f0-9]{64}$/
score_digest
required
string
/^sha256:[a-f0-9]{64}$/
output_digest
required
string
/^sha256:[a-f0-9]{64}$/
key
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
run_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
agent_version_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
reset_epoch
required
integer
>= 1 <= 9007199254740991
mode
required
Allowed value: test
usage
required
Allowed value: test_compute
admission_digest
required
string
/^sha256:[a-f0-9]{64}$/
projection_digest
required
string
/^sha256:[a-f0-9]{64}$/
decision_digest
required
string
/^sha256:[a-f0-9]{64}$/
artifact_digest
required
string
/^sha256:[a-f0-9]{64}$/
artifact_ref
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9007199254740991
integrity
required
string
/^sha256:[a-f0-9]{64}$/
media_type
required
Allowed values: application/json text/plain text/markdown
size_bytes
required
integer
>= 1 <= 131072
expires_at
required
string format: date-time
baseline
required
Array<object>
0 <= 1000 items
object
case_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
assessment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
assessment_digest
required
string
/^sha256:[a-f0-9]{64}$/
score_digest
required
string
/^sha256:[a-f0-9]{64}$/
output_digest
required
string
/^sha256:[a-f0-9]{64}$/
key
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
run_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
agent_version_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
reset_epoch
required
integer
>= 1 <= 9007199254740991
mode
required
Allowed value: test
usage
required
Allowed value: test_compute
admission_digest
required
string
/^sha256:[a-f0-9]{64}$/
projection_digest
required
string
/^sha256:[a-f0-9]{64}$/
decision_digest
required
string
/^sha256:[a-f0-9]{64}$/
artifact_digest
required
string
/^sha256:[a-f0-9]{64}$/
artifact_ref
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9007199254740991
integrity
required
string
/^sha256:[a-f0-9]{64}$/
media_type
required
Allowed values: application/json text/plain text/markdown
size_bytes
required
integer
>= 1 <= 131072
expires_at
required
string format: date-time
report
required
object
metric_version
required
Allowed value: katara.promotion-human-quality.wilson-bonferroni.v1
policy_digest
required
string
/^sha256:[a-f0-9]{64}$/
confidence_ppm
required
integer
>= 1 <= 999999
comparisons
required
integer
>= 2 <= 224
state
required
Allowed values: insufficient_evidence criteria_failed criteria_met
criteria
required
Array<object>
>= 1 items <= 32 items
object
criterion_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
counts
required
object
cases
required
integer
<= 1000
missing_human
required
integer
<= 1000
human_abstentions
required
integer
<= 1000
human_pass
required
integer
<= 1000
human_fail
required
integer
<= 1000
missing_baseline
required
integer
<= 1000
baseline_abstentions
required
integer
<= 1000
paired
required
integer
<= 1000
both_pass
required
integer
<= 1000
candidate_only_pass
required
integer
<= 1000
baseline_only_pass
required
integer
<= 1000
neither_pass
required
integer
<= 1000
label_coverage
required
One of:
object
numerator
required
integer
<= 1000
denominator
required
integer
>= 1 <= 1000
lower_ppm
required
integer
<= 1000000
upper_ppm
required
integer
<= 1000000
human_pass_rate
required
One of:
object
numerator
required
integer
<= 1000
denominator
required
integer
>= 1 <= 1000
lower_ppm
required
integer
<= 1000000
upper_ppm
required
integer
<= 1000000
pair_coverage
required
One of:
object
numerator
required
integer
<= 1000
denominator
required
integer
>= 1 <= 1000
lower_ppm
required
integer
<= 1000000
upper_ppm
required
integer
<= 1000000
pass_rate_difference
required
One of:
object
numerator
required
integer
>= -1000 <= 1000
denominator
required
integer
>= 1 <= 1000
lower_ppm
required
integer
>= -1000000 <= 1000000
upper_ppm
required
integer
>= -1000000 <= 1000000
state
required
Allowed values: insufficient_evidence criteria_failed criteria_met
reasons
required
Array
0 <= 11 items
Allowed values: minimum_cases minimum_resolved_cases minimum_paired_cases label_coverage_undefined label_coverage_below_bound human_pass_rate_undefined human_pass_rate_below_bound pair_coverage_undefined pair_coverage_below_bound regression_undefined regression_above_bound
expires_at
required
string format: date-time
created_by
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
created_at
required
string format: date-time
integrity
required
string
/^sha256:[a-f0-9]{64}$/
Example
{
  "preview": {
    "input": {
      "candidate": {
        "runs": [
          {
            "key": {
              "mode": "test",
              "usage": "test_compute"
            }
          }
        ]
      },
      "baseline": {
        "runs": [
          {
            "key": {
              "mode": "test",
              "usage": "test_compute"
            }
          }
        ]
      }
    },
    "candidate": [
      {
        "key": {
          "mode": "test",
          "usage": "test_compute"
        },
        "artifact_ref": {
          "media_type": "application/json"
        }
      }
    ],
    "baseline": [
      {
        "key": {
          "mode": "test",
          "usage": "test_compute"
        },
        "artifact_ref": {
          "media_type": "application/json"
        }
      }
    ],
    "report": {
      "metric_version": "katara.promotion-human-quality.wilson-bonferroni.v1",
      "state": "insufficient_evidence",
      "criteria": [
        {
          "state": "insufficient_evidence",
          "reasons": [
            "minimum_cases"
          ]
        }
      ]
    }
  }
}

Headers

Section titled “Headers”
Cache-Control
string
Allowed value: no-store

409

Section titled “409”

Account_changed: reload and review with the signed-in account.

default

Section titled “default”

Request error

Media typeapplication/json
object
error
required
object
message
required
string
>= 1 characters <= 500 characters
type
required
string
>= 1 characters <= 100 characters
code
required

Stable; branch on it. Any operation can answer invalid_request, with param naming the refused field when there is one; human_session_required, when an API key, service account or workload calls an operation only a signed-in person may perform; reauthentication_required, when a person’s sign-in is too old for the operation; permission_denied; route_not_found and method_not_allowed, when no operation matches the path or method; and feature_unavailable, when the operation’s service is not enabled on this deployment.

string
>= 1 characters <= 100 characters
param
required

The request field a refusal is about, such as the agent_id or run_id query parameter; null when the refusal is not about one field.

string | null
request_id
required
string
>= 1 characters <= 100 characters
upstream_status
required
integer | null
action
Allowed values: sign_in reauthenticate request_access review fund retry reconcile refresh support
operation_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
snapshot_ref
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
Example
{
  "error": {
    "action": "sign_in"
  }
}