Skip to content
KataraKatara documentation

Read an immutable evidence declaration

GET
/katara/v1/orgs/{org_id}/promotion-evidence/declarations/{id}
curl --request GET \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/promotion-evidence/declarations/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
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
input
required
object
request
required
object
source
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
mode
required
Allowed value: test
organization_epoch
required
integer
>= 1 <= 9007199254740991
authority_epoch
required
integer
>= 1 <= 9007199254740991
reset_generation
required
integer
>= 1 <= 9007199254740991
destination
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
mode
required
Allowed value: live
organization_epoch
required
integer
>= 1 <= 9007199254740991
authority_epoch
required
integer
>= 1 <= 9007199254740991
reset_generation
required
integer
>= 1 <= 9007199254740991
source_version
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
version
required
integer
>= 1 <= 9007199254740991
integrity
required
string
/^sha256:[a-f0-9]{64}$/
agent_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
subject_epoch
required
integer
>= 1 <= 9007199254740991
target
required
object
agent_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
subject_epoch
required
integer
>= 1 <= 9007199254740991
previous_version
required
One of:
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
version
required
integer
>= 1 <= 9007199254740991
integrity
required
string
/^sha256:[a-f0-9]{64}$/
definition
required
object
schema_version
required
Allowed value: 1
name
required
string
>= 1 characters <= 120 characters /^\S(?:[^\x00-\x1f\x7f]*\S)?$/
instructions_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: text/plain text/markdown
size_bytes
required
integer
>= 1 <= 131072
model_policy
required
object
mode
required
Allowed value: cortex
capability_revision
required
string
/^sha256:[a-f0-9]{64}$/
model_ids
required
Array<string>
>= 1 items <= 20 items unique items
tool_versions
required
Array<object>
<= 100 items unique items
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
version
required
integer
>= 1 <= 9007199254740991
integrity
required
string
/^sha256:[a-f0-9]{64}$/
knowledge_collections
required
Array<string>
<= 100 items unique items
input_schema_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 value: application/json
size_bytes
required
integer
>= 1 <= 262144
output_schema_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 value: application/json
size_bytes
required
integer
>= 1 <= 262144
approval_policy_versions
required
Array<object>
<= 100 items unique items
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
version
required
integer
>= 1 <= 9007199254740991
integrity
required
string
/^sha256:[a-f0-9]{64}$/
limits
required

The API also checks steps <= decisions, plan changes <= decisions, active and approval seconds <= elapsed seconds, and children/depth are either both zero or both positive. Structured output is a JSON envelope; larger artifacts use content references. Active time includes Activity scheduling, retries and execution. Approval waits consume the cumulative approval and elapsed limits; ordinary delays consume elapsed time only. Counters survive continuation.

object
max_steps
required
integer
>= 1 <= 10000
max_children
required
integer
<= 1000
max_depth
required
integer
<= 16
max_active_seconds
required
integer
>= 1 <= 86400
max_elapsed_seconds
required
integer
>= 1 <= 2592000
max_approval_wait_seconds
required
integer
>= 1 <= 604800
max_output_bytes
required
integer
>= 1 <= 1048576
max_decisions
required
integer
>= 1 <= 20000
max_plan_changes
required
integer
>= 1 <= 1000
evidence
required
One of:
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
version
required
integer
>= 1 <= 9007199254740991
integrity
required
string
/^sha256:[a-f0-9]{64}$/
grants
required
Array<object>
>= 1 items <= 8 items unique items
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
audience
required
Allowed values: katara:synapse katara:locus
authority_epoch
required

The selected immutable grant leaf agent_epoch, fenced to the target agent subject epoch.

integer
>= 1 <= 9007199254740991
funding
required
object
payer_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
consent_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
budget_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
limit
required
object
ledger_kind
required
Allowed value: real
asset
required
Allowed value: CREDIT_ATOMIC
scale
required
Allowed value: 9
amount
required
string
/^[1-9][0-9]{0,17}$/
purpose_caps
required
object
inference
required
string
/^(0|[1-9][0-9]{0,17})$/
tool
required
string
/^(0|[1-9][0-9]{0,17})$/
service
required
string
/^(0|[1-9][0-9]{0,17})$/
sandbox
required
string
/^(0|[1-9][0-9]{0,17})$/
evaluation
required
string
/^(0|[1-9][0-9]{0,17})$/
evidence
required
candidate_campaign
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}$/
baseline
required
One of:
object
agent
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
version
required
integer
>= 1 <= 9007199254740991
integrity
required
string
/^sha256:[a-f0-9]{64}$/
agent_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
subject_epoch
required
integer
>= 1 <= 9007199254740991
campaign
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}$/
policy
required
object
metric_version
required
Allowed value: katara.promotion-human-quality.wilson-bonferroni.v1
confidence_ppm
required
integer
>= 1 <= 999999
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
min_cases
required
integer
>= 1 <= 1000
min_resolved_cases
required
integer
>= 1 <= 1000
min_label_coverage_ppm
required
integer
<= 1000000
min_human_pass_rate_ppm
required
integer
<= 1000000
regression
required
One of:
object
min_paired_cases
required
integer
>= 1 <= 1000
min_pair_coverage_ppm
required
integer
<= 1000000
max_pass_rate_loss_ppm
required
integer
<= 1000000
threshold_version
required
integer
>= 1 <= 9007199254740991
acknowledge
required
bindings_digest
required
string
/^sha256:[a-f0-9]{64}$/
baseline_bindings_digest
required
One of:
string
/^sha256:[a-f0-9]{64}$/
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
{
  "declaration": {
    "input": {
      "request": {
        "source": {
          "mode": "test"
        },
        "destination": {
          "mode": "live"
        },
        "target": {
          "definition": {
            "schema_version": 1,
            "instructions_ref": {
              "media_type": "text/plain"
            },
            "model_policy": {
              "mode": "cortex"
            },
            "input_schema_ref": {
              "media_type": "application/json"
            },
            "output_schema_ref": {
              "media_type": "application/json"
            }
          }
        },
        "evidence": {
          "id": "",
          "version": 0,
          "integrity": ""
        },
        "grants": [
          {
            "audience": "katara:synapse"
          }
        ],
        "funding": {
          "limit": {
            "ledger_kind": "real",
            "asset": "CREDIT_ATOMIC",
            "scale": 9
          }
        }
      },
      "policy": {
        "metric_version": "katara.promotion-human-quality.wilson-bonferroni.v1"
      },
      "acknowledge": true
    },
    "baseline_bindings_digest": ""
  }
}

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"
  }
}