Skip to content
KataraKatara documentation

Review an exact prior Live configuration

POST
/katara/v1/orgs/{org_id}/environments/{environment_id}/agent-rollbacks/reviews
curl --request POST \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/agent-rollbacks/reviews \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --header 'X-Katara-CSRF: 1' \
  --data '{ "environment": { "org_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "environment_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "mode": "live", "organization_epoch": 1, "authority_epoch": 1, "reset_generation": 1 }, "agent_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "subject_epoch": 1, "current_version": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "version": "example", "integrity": "example" }, "restore_version": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "version": 1, "integrity": "example" }, "grants": [ { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "audience": "katara:synapse", "authority_epoch": 1 } ], "funding": { "payer_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "consent_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "budget_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "limit": { "ledger_kind": "real", "asset": "CREDIT_ATOMIC", "scale": 9, "amount": "example" }, "purpose_caps": { "inference": "example", "tool": "example", "service": "example", "sandbox": "example", "evaluation": "example" } } }'

Requires a signed-in human owner session in the selected Live environment. API keys, service accounts and workloads are refused. Query parameters are rejected and responses are no-store. Rollback restores an exact prior approved immutable definition as a new monotonically increasing publication; it never moves a deployment pointer or restores historical authority. Current source, model, tool, collection, policy, grant, funded consent and head-version checks remain mandatory. Pins the current head and exact prior version with approved publication provenance. A broken current head does not permit a revoked or unavailable restore source.

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

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
required
string
/^[A-Za-z0-9._:-]{8,128}$/
X-Katara-CSRF
Allowed value: 1

Browser cookie mutations require value 1 and an allowed Origin. Session bearer clients may omit this header.

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.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Live owner request. Restore must be an earlier distinct version of the same agent with approved publication provenance. Every selected grant authority epoch must match subject_epoch; current grant coverage, consent and funding are independently verified.

object
environment
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
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
current_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}$/
version
required
>= 2 <= 9007199254740990
restore_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}$/
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})$/

Responses

Section titled “Responses”

201

Section titled “201”

Successful request

Media typeapplication/json

The target copies the exact restored definition into current_version.version + 1 with a new immutable version ID. Review does not publish.

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
request
required

Live owner request. Restore must be an earlier distinct version of the same agent with approved publication provenance. Every selected grant authority epoch must match subject_epoch; current grant coverage, consent and funding are independently verified.

object
environment
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
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
current_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}$/
version
required
>= 2 <= 9007199254740990
restore_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}$/
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})$/
restore
required
object
bundle
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
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
revision
required
integer
>= 1 <= 9007199254740991
reset_generation
required
integer
>= 1 <= 9007199254740991
subject_epoch
required
integer
>= 1 <= 9007199254740991
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
One of:
object
mode
required
Allowed value: simulated
fixture_set
required
string
/^[a-z0-9][a-z0-9._-]{0,119}$/
fixture_revision
required
string
/^sha256:[a-f0-9]{64}$/
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
schema_profile
required
Allowed value: json-schema-2020-12/v1
published_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
published_at
required
string format: date-time
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
digest
required
string
/^sha256:[a-f0-9]{64}$/
signing_key_id
required
string
/^[A-Za-z0-9._-]{1,80}$/
signature
required
string
>= 88 characters <= 88 characters /^[A-Za-z0-9+/]{85}[AQgw]==$/
target
required
object
bundle
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
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
revision
required
integer
>= 1 <= 9007199254740991
reset_generation
required
integer
>= 1 <= 9007199254740991
subject_epoch
required
integer
>= 1 <= 9007199254740991
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
One of:
object
mode
required
Allowed value: simulated
fixture_set
required
string
/^[a-z0-9][a-z0-9._-]{0,119}$/
fixture_revision
required
string
/^sha256:[a-f0-9]{64}$/
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
schema_profile
required
Allowed value: json-schema-2020-12/v1
published_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
published_at
required
string format: date-time
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
digest
required
string
/^sha256:[a-f0-9]{64}$/
signing_key_id
required
string
/^[A-Za-z0-9._-]{1,80}$/
signature
required
string
>= 88 characters <= 88 characters /^[A-Za-z0-9+/]{85}[AQgw]==$/
dependency_digest
required
string
/^sha256:[a-f0-9]{64}$/
preparation_digest
required
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
digest
required
string
/^sha256:[a-f0-9]{64}$/
Example
{
  "request": {
    "environment": {
      "mode": "live"
    },
    "grants": [
      {
        "audience": "katara:synapse"
      }
    ],
    "funding": {
      "limit": {
        "ledger_kind": "real",
        "asset": "CREDIT_ATOMIC",
        "scale": 9
      }
    }
  },
  "restore": {
    "bundle": {
      "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"
        }
      },
      "schema_profile": "json-schema-2020-12/v1"
    }
  },
  "target": {
    "bundle": {
      "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"
        }
      },
      "schema_profile": "json-schema-2020-12/v1"
    }
  }
}

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