Skip to content
KataraKatara documentation

List your Locus actions

GET
/katara/v1/orgs/{org}/environments/{environment}/actions
curl --request GET \
  --url 'https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/actions?limit=25' \
  --header 'Authorization: Bearer <token>'

Requires locus:actions:read, the original requester, current organization and environment membership, and current key/service authority. Service key owners must also retain personal membership and the read permission. Key resource restrictions match resource_id, not the action ID. Workload credentials are refused. Current policy, grant, payer and reviewer authority are rechecked. Named source revocation or expiry produces sanitized history with authority_status stale; failures in database or internal checks fail the request. A Test reset mismatch returns 404. Recorded decisions and denial_source preserve why a request was denied. The response contains no action inputs, credential bindings, reviewer identities or authentication evidence. State is a read snapshot; it grants no approval or execution right. Claimed means an execution claim exists, not that its external effect completed.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

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

Query Parameters

Section titled “Query Parameters”
after
string format: uuid
limit
integer
default: 25 >= 1 <= 25

Header Parameters

Section titled “Header Parameters”
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}$/

Optional for reads after sign-in. 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.

Responses

Section titled “Responses”

200

Section titled “200”

Requester action metadata.

Media typeapplication/json
object
data
required
Array<object>
<= 25 items
object
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/
requester_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/
agent_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/
resource_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/
grant_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/
budget_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/
mode
required
string
Allowed values: test live
usage_class
required
string
Allowed values: simulation test_compute live
reset_generation
required
integer
>= 1
kind
required
string
Allowed values: tool inference sandbox evaluation memory
effect
required
string
Allowed values: read_only idempotent_write non_idempotent_write
implementation
required
object
id
required
string format: uuid
version
required
integer
>= 1
integrity
required
string
/^sha256:[a-f0-9]{64}$/
policy
required
object
id
required
string format: uuid
version
required
integer
>= 1
integrity
required
string
/^sha256:[a-f0-9]{64}$/
action_digest
required
string
/^sha256:[a-f0-9]{64}$/
recorded_decision
required
object
outcome
required
string
Allowed values: allow deny require_approval
reasons
required
Array<string>
<= 10 items
Allowed values: kind_not_allowed origin_not_allowed detector_blocked detector_unavailable detector_too_large detector_review effect_requires_approval test_compute_effect
state
required
string
Allowed values: pending ready denied claimed expired invalidated
authority_status
required
string
Allowed values: current stale
denial_source
required
string | null
Allowed values: policy reviewer
execution_claimed
required
boolean
created_at
required
string format: date-time
expires_at
required
string format: date-time
version
required
integer
>= 1
outcome

What an external runtime’s call reported when it ended. unknown: nobody can say whether the effect happened. Absent when no outcome was recorded, as for an action a managed run took.

string
Allowed values: reported_success unknown
reconciliation

For an unknown outcome: awaiting until an owner or admin records what happened, then recorded.

string
Allowed values: awaiting recorded
next_cursor
string format: uuid
Example
{
  "data": [
    {
      "mode": "test",
      "usage_class": "simulation",
      "kind": "tool",
      "effect": "read_only",
      "recorded_decision": {
        "outcome": "allow",
        "reasons": [
          "kind_not_allowed"
        ]
      },
      "state": "pending",
      "authority_status": "current",
      "denial_source": "policy",
      "outcome": "reported_success",
      "reconciliation": "awaiting"
    }
  ]
}

400

Section titled “400”

Invalid ID, cursor or query.

403

Section titled “403”

Current scoped read authority is unavailable.

404

Section titled “404”

Action is unavailable to this requester or Test generation.

409

Section titled “409”

The action changed during inspection. Reload before interpreting its state.

500

Section titled “500”

The action or its authority could not be checked.