Skip to content
KataraKatara documentation

Admit a governed action for an external runtime and run it

POST
/katara/v1/orgs/{org}/environments/{environment}/actions
curl --request POST \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/actions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "tool": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "version": 1, "integrity": "example" }, "arguments": { "org_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "environment_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "version": 1, "integrity": "example", "media_type": "text/plain", "size_bytes": 1 }, "grant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "budget_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "expires_at": "2026-04-15T12:00:00Z", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

For an external agent’s key. Admits the action under the caller’s id with fresh authorization, policy, approval and budget checks, and runs it through the tool engine when nothing stands in the way; the tool’s output comes back inline and is not stored. An action waiting for a person’s approval answers 202; submit the same request again once it is approved to run it. Repeating an action already claimed runs nothing. Tools that need a Katara-held credential or a price answer 409 managed_run_required: only a managed run can use them.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

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

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

The action to admit under the caller’s own id. The same id with the same body finds the same action; the same id with another body conflicts.

object
tool
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 <= 9223372036854776000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
arguments
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 <= 9223372036854776000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
media_type
required
Allowed values: text/plain text/markdown application/json application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document image/png image/jpeg text/csv application/zip
size_bytes
required
integer
<= 104857600
grant_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
expires_at
required
string format: date-time
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

Responses

Section titled “Responses”

200

Section titled “200”

Admitted; ran, refused or expired.

Media typeapplication/json
object
action
required

The admitted action as the runtime that submitted it sees it. It carries no arguments and no approver.

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
action_digest
required
string
/^sha256:[a-f0-9]{64}$/
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
Allowed values: read_only idempotent_write non_idempotent_write
decision
required
Allowed values: allow deny require_approval
reasons
required
Array<string>
<= 32 items
state
required
Allowed values: ready pending denied expired claimed
expires_at
required
string format: date-time
outcome
Allowed values: reported_success unknown
output

The tool’s response, validated against the version’s output schema. Present only after a reported success.

Example
{
  "action": {
    "effect": "read_only",
    "decision": "allow",
    "state": "ready"
  },
  "outcome": "reported_success"
}

202

Section titled “202”

Admitted; waiting for approval.

Media typeapplication/json
object
action
required

The admitted action as the runtime that submitted it sees it. It carries no arguments and no approver.

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
action_digest
required
string
/^sha256:[a-f0-9]{64}$/
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
Allowed values: read_only idempotent_write non_idempotent_write
decision
required
Allowed values: allow deny require_approval
reasons
required
Array<string>
<= 32 items
state
required
Allowed values: ready pending denied expired claimed
expires_at
required
string format: date-time
outcome
Allowed values: reported_success unknown
output

The tool’s response, validated against the version’s output schema. Present only after a reported success.

Example
{
  "action": {
    "effect": "read_only",
    "decision": "allow",
    "state": "ready"
  },
  "outcome": "reported_success"
}

400

Section titled “400”

The request is malformed or names what the catalog decides.

403

Section titled “403”

The key is not an external agent’s, or its grant, policy or budget refuses the action.

404

Section titled “404”

The tool version, grant or budget is unavailable in this environment.

409

Section titled “409”

Managed_run_required: the tool needs a Katara-held credential or a price. conflict: the id names another action.

500

Section titled “500”

The action or its authority could not be checked.