Skip to content
KataraKatara documentation

Record the resolution of a run's reconciliation

POST
/katara/v1/orgs/{org_id}/environments/{environment_id}/runs/{id}/reconciliation
curl --request POST \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/runs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/reconciliation \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --header 'X-Katara-CSRF: 1' \
  --cookie katara_session=<katara_session> \
  --data '{ "outcome": "effect_completed", "reference": "example", "note": "example" }'

Owner or admin in a signed-in session only; requires synapse:runs:reconcile. Records what was found about the effect. The resolution is written once and never changed: a repeat with the same key returns it, and a second resolution of the same run is a conflict. Resolving releases the run’s recovery checkpoint unless a hold keeps it. It records a conclusion and moves no money. The run keeps its status, and getRun shows the outcome and when it was recorded.

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
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
object
outcome
required

Effect_completed: the effect happened. effect_not_completed: it did not. corrective_action: it was put right by hand. cancellation_finalized: the run stays cancelled and nothing more follows.

string
Allowed values: effect_completed effect_not_completed corrective_action cancellation_finalized
reference
required

Where the evidence is: a ticket, a provider receipt, a case number.

string
>= 3 characters <= 200 characters
note
required

What was found.

string
>= 1 characters <= 2000 characters

Responses

Section titled “Responses”

200

Section titled “200”

The resolution is recorded.

Media typeapplication/json

A run that ended awaiting reconciliation: what is needed to decide, and its resolution once there is one.

object
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
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
string
Allowed values: test live
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
agent_name
string
>= 1 characters <= 120 characters
reason
required
string
>= 1 characters <= 80 characters
ended_at
required
string format: date-time
effect

The step whose outcome is unknown: the run’s last.

object
step
required
integer
>= 1 <= 10000
kind
required
string
Allowed values: inference tool recall ingestion code browser
target_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
action_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
checkpoint_kept
required
boolean
held
required
boolean
resolution

What the person who resolved the reconciliation recorded. Written once and never changed.

object
outcome
required
string
Allowed values: effect_completed effect_not_completed corrective_action cancellation_finalized
reference
required
string
>= 3 characters <= 200 characters
note
string
>= 1 characters <= 2000 characters
recorded_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
recorded_at
required
string format: date-time
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
accounting

The reservation behind the effect, in atomic units, for a role that reads billing.

object
purpose
required
string
Allowed values: inference tool service sandbox evaluation
reserved
required
integer
>= 1 <= 9007199254740991
charged
required
integer
<= 9007199254740991
state
required
string
Allowed values: held unknown charged released
exposure
Array<object>
<= 200 items

One hold tied to the run, in atomic units, for a role that reads billing: the step it belongs to when it belongs to one.

object
kind
required
string
Allowed values: inference tool recall ingestion code browser
step
integer
>= 1 <= 10000
purpose
required
string
Allowed values: inference tool service sandbox evaluation
reserved
required
integer
>= 1 <= 9007199254740991
charged
required
integer
<= 9007199254740991
state
required
string
Allowed values: held unknown charged released
Example
{
  "mode": "test",
  "effect": {
    "kind": "inference"
  },
  "resolution": {
    "outcome": "effect_completed"
  },
  "accounting": {
    "purpose": "inference",
    "state": "held"
  },
  "exposure": [
    {
      "kind": "inference",
      "purpose": "inference",
      "state": "held"
    }
  ]
}

409

Section titled “409”

The key was used for another request, the state changed, or the cookie account changed. Reinspect before a new intent; keep the key to recover an uncertain reply.

default

Section titled “default”

Request rejected or unavailable.

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