Skip to content
KataraKatara documentation

Record what happened to an action whose outcome is unknown

POST
/katara/v1/orgs/{org}/environments/{environment}/actions/{id}/reconciliation
curl --request POST \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/actions/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/reconciliation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --header 'X-Katara-CSRF: 1' \
  --data '{ "outcome": "completed", "reference": "example", "note": "example" }'

Owner or admin, as a person whose sign-in is under five minutes old; requires locus:actions:reconcile, which no key carries. An API key, a service account or a workload is refused with human_session_required, and an older sign-in with reauthentication_required. The record is written once and never changed, and it settles the action’s tool unit in the same transaction: completed charges it at the price the action was admitted at, not_completed releases it. A repeat with the same key and body returns the record; the same key with another body, or any second resolution of the action, is a 409 conflict, and the money stays where the first record put it. Nothing calls the tool again.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
org
required
string format: uuid
environment
required
string format: uuid
id
required
string format: uuid

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

Completed: the effect happened, and the unit is charged at the price the action was admitted at. not_completed: it did not, and the unit is released.

string
Allowed values: completed not_completed
reference
required

Where the evidence is: a ticket, the provider’s log entry, 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 and the unit settled.

Media typeapplication/json

An external runtime’s action whose outcome is unknown, and its resolution once there is one. It carries identifiers, states, amounts and times, never the action’s input or the tool’s output. unit is absent when the action had no tool unit.

object
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
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
resource_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
effect
required
string
Allowed values: read_only idempotent_write non_idempotent_write
claimed_at
required
string format: date-time
outcome
required

The call ended without a reply anyone could trust, so nobody knows whether the effect happened.

string
Allowed value: unknown
observed_at
required
string format: date-time
unit

The action’s one tool unit as its budget holds it.

object
price
required

The tool tariff the action was admitted at, in atomic credit units (nine decimal places).

integer
>= 1 <= 9007199254740991
state
required

Held: reserved and not yet decided. unknown: reserved and marked as awaiting reconciliation once no call could still be running. charged: the unit was spent. released: it was returned to the budget.

string
Allowed values: held unknown charged released
charged
required
integer
<= 9007199254740991
resolution

What the owner or admin who resolved the action recorded. Written once and never changed.

object
outcome
required
string
Allowed values: completed not_completed
reference
required
string
>= 3 characters <= 200 characters
note
required
string
>= 1 characters <= 2000 characters
unit_outcome

What the record did to the unit. Absent when the action had none.

string
Allowed values: charged released
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
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
Example
{
  "mode": "test",
  "effect": "read_only",
  "outcome": "unknown",
  "unit": {
    "state": "held"
  },
  "resolution": {
    "outcome": "completed",
    "unit_outcome": "charged"
  }
}

400

Section titled “400”

The body is malformed, names a field the contract lacks, or the key is missing.

403

Section titled “403”

Human_session_required: the caller is not a person. reauthentication_required: the sign-in is older than five minutes. permission_denied: the role is not owner or admin.

404

Section titled “404”

The action is unavailable in this environment.

409

Section titled “409”

The action does not await reconciliation, it already has one, its unit was settled another way, or the key was used for another request. The first record stands; a key with wider permissions does not change this.

500

Section titled “500”

The action or its authority could not be checked.