Skip to content
KataraKatara documentation

Close the organization

POST
/katara/v1/orgs/{org_id}/close
curl --request POST \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/close \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --header 'X-Katara-CSRF: 1' \
  --cookie katara_session=<katara_session> \
  --data '{ "reason": "example" }'

Organization owner in a signed-in session only; requires org:close. Closing is final. From the moment it commits the organization takes no new member, invitation, run, grant or execution work, invitations already sent stop working, every run that has not ended is asked to cancel, and its execution environments are cleaned up. A run whose last effect cannot be confirmed ends awaiting reconciliation, and its recovery checkpoint is kept until it is resolved. The call returns once the closure is recorded; read the closure for its progress. A repeat with the same key returns the same operation.

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

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

Closing an organization is final. Only its owner closes it, in a signed-in session.

object
reason
required

Why the organization is closing, in a line. Kept with the closure.

string
>= 1 characters <= 200 characters
Examplegenerated
{
  "reason": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

The closure is recorded and cleanup has begun.

Media typeapplication/json

An organization’s state and how far its closure has come. Closing reads closed once every execution environment is gone and nothing is kept.

object
operation
object
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
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
completed
required
boolean
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
state
required
string
Allowed values: active closing closed
stage
string
Allowed values: fencing cancelling_runs cleaning_environments releasing_checkpoints awaiting_reconciliation awaiting_hold_release removing_templates deleting_namespace complete
requested_at
string format: date-time
requested_by
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
closed_at
string format: date-time
counts
required

What is left, as counts.

object
active_runs
required

Runs that have not ended yet; the closure asked each to cancel.

integer
<= 1000000
awaiting_reconciliation
required

Runs that ended with an effect nobody could confirm, and no resolution yet.

integer
<= 1000000
retained_checkpoints
required

Recovery checkpoints kept because a reconciliation or a hold still needs them.

integer
<= 1000000
active_holds
required

Legal or security holds in force.

integer
<= 1000000
environments_remaining
required

Execution environments still to be removed.

integer
<= 1000000
checkpoints_remaining
required

Checkpoints still stored, kept or not yet deleted.

integer
<= 1000000
templates_remaining
required

Environment templates still to be removed.

integer
<= 1000000
policies_remaining
required

Network policies still to be removed.

integer
<= 1000000
sandboxes

The cleanup of the organization’s execution environments.

object
phase
required
string
Allowed values: runs actors egress checkpoints retaining templates verifying namespace completed
attempts
required
integer
<= 1000000
escalated
required
boolean
retained
required
Array<object>
<= 1000 items
object
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
reason
required

What keeps the checkpoint: the run awaits reconciliation, or a hold names it.

string
Allowed values: reconciliation hold
audit
required
Array<object>
<= 200 items

One entry of the cleanup’s audit record: a kind, keyed counts and classes, and when. Never content.

object
kind
required
string
Allowed values: cleanup_started cleanup_retry runs_cancellation_requested runs_drained actor_cleanup_attempted actor_cleanup_completed worker_recycled egress_cleanup_completed checkpoints_retained checkpoint_cleanup_completed template_cleanup_completed namespace_verified_empty namespace_deleted cleanup_completed cleanup_failed
detail
required
object
phase
string
Allowed values: runs actors egress checkpoints retaining templates verifying namespace completed
count
integer
<= 1000000
remaining
integer
<= 1000000
retained
integer
<= 1000000
attempt
integer
<= 1000000
reason
string
>= 1 characters <= 120 characters
error
string
>= 1 characters <= 40 characters
environments
integer
<= 1000000
worker
string
>= 1 characters <= 200 characters
at
required
string format: date-time
audit_term_days
required

How long a completed cleanup’s audit record is kept.

integer
>= 30 <= 3650
Example
{
  "state": "active",
  "stage": "fencing",
  "sandboxes": {
    "phase": "runs",
    "retained": [
      {
        "reason": "reconciliation"
      }
    ]
  },
  "audit": [
    {
      "kind": "cleanup_started",
      "detail": {
        "phase": "runs"
      }
    }
  ]
}

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