Resources

Actions

An action is a single event from your AI agent. Every action recorded here writes into the signed audit trail behind your compliance packs, and registers the agent if it's new.

Two kinds:

Invocation — the normal case: an agent did something (called an LLM, ran a tool, produced a response)
Rogue event — the abnormal case: an agent did something out of scope (called a tool it shouldn't have, tripped a jailbreak check)

Both are POST-only. Both accept either a kya_live_ API token or an ingress token.

Record an invocation

Log a single agent action. You can send just metadata (empty prompt/response/tool fields are fine). Sending LLM content or tool payloads turns on deeper policy checks and PII redaction.

Request

POST /api/v1/admin/agents/events/invocation

Headers

Authorization: Bearer <token> — a kya_live_ API token OR an ingress token

Body

Field	Type	Required	Description
`agent_key`	string	✓	Stable id for the agent. 1–512 chars. First-sight registers the agent.
`mode`	string		`observed`, `enforced`, or `shadow`. Defaults to `observed`.
`outcome`	string		`success`, `error`, `denied`, `throttled`, etc. Defaults to `success`.
`duration_ms`	integer		How long the action took, in milliseconds. `>= 0`.
`principal_kind`	string		`user` or `agent`. What kind of actor made the call.
`principal_id`	string		The actor's id (defaults to `agent_key` when omitted).
`parent_invocation_id`	integer		If this action was spawned by another, the parent's id. `>= 1`.
`correlation_id`	string		Free-form id to tie events together. Up to 64 chars.
`tenant_id`	string		REQUIRED when using the fallback ingress token. IGNORED with a scoped ingress token or `kya_live_` token.
`prompt`	string		Prompt sent to the LLM. Up to 32,000 chars.
`response`	string		Response from the LLM. Up to 32,000 chars.
`context`	string		Extra context sent to the model (system prompt, retrieved docs). Up to 32,000 chars.
`tool_name`	string		If the action IS a tool call, the tool's name. Up to 256 chars.
`tool_input`	string		Tool input as a string. Up to 32,000 chars. Scanned for PII at ingest — see Security › Automatic PII redaction.
`tool_output`	string		Tool output as a string. Up to 32,000 chars. Scanned for PII after the fact.

Example — minimal (metadata only)

bash

curl -X POST https://api.veldtlabs.ai/api/v1/admin/agents/events/invocation \
  -H "Authorization: Bearer $VELDT_KYA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_key": "billing.orchestrator",
    "outcome": "success",
    "duration_ms": 142
  }'

Response (201 Created):

json response

{
  "invocation_id": 91827,
  "tenant_id": "tenant_example",
  "verdict": "allow",
  "evidence_id": 555,
  "pii_count": 0
}

verdict is decided at write time (allow / flag_for_review / deny). evidence_id appears when we wrote a signed audit-trail entry. pii_count appears when tool_input contained PII.

Self-hosted operators — you can also send this event via a shared ingress token instead of a kya_live_* token. See Authentication › Ingress tokens.

Example — with LLM content

bash

curl -X POST https://api.veldtlabs.ai/api/v1/admin/agents/events/invocation \
  -H "Authorization: Bearer $VELDT_KYA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_key": "billing.orchestrator",
    "mode": "observed",
    "outcome": "success",
    "duration_ms": 142,
    "principal_kind": "agent",
    "principal_id": "billing.orchestrator",
    "correlation_id": "req-3f2a1c-4bef-9d1f",
    "prompt": "Summarize Q3 invoice exceptions",
    "response": "3 invoices exceed threshold: INV-4471, INV-4519, INV-4602"
  }'

Example — tool call with parent link

bash

curl -X POST https://api.veldtlabs.ai/api/v1/admin/agents/events/invocation \
  -H "Authorization: Bearer $VELDT_KYA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_key": "invoice.reviewer",
    "principal_kind": "agent",
    "principal_id": "invoice.reviewer",
    "parent_invocation_id": 91827,
    "correlation_id": "req-3f2a1c-4bef-9d1f",
    "tool_name": "invoice_lookup",
    "tool_input": "{\"invoice_id\": \"INV-4471\"}",
    "tool_output": "{\"amount_usd\": 42000, \"status\": \"pending\"}"
  }'

Errors

401 unauthorized — bad or missing token
402 payment_required — account trial expired or subscription lapsed (see Errors › Account gated)
403 forbidden — fallback token used without tenant_id
422 unprocessable — validation failed (e.g. a text field over 32,000 chars)
500 internal_error — storage layer unavailable

Flag a rogue spawn

Record an out-of-policy event for an agent — typically, an agent tried to call a tool it isn't allowed to use.

Request

POST /api/v1/admin/agents/events/rogue

Headers

Authorization: Bearer <token> — ingress token or kya_live_

Body

Field	Type	Required	Description
`event_type`	string	✓	Use `oos_tool` (out-of-scope tool call). 1–40 chars.
`agent_key`	string	✓	The agent the event is attached to. 1–512 chars.
`actor_agent_key`	string		The agent that actually tried the action, if different from `agent_key`.
`tool`	string	✓ (for `oos_tool`)	The out-of-scope tool name. Up to 256 chars.
`user_id`	string		Human user id, if the attempt was user-triggered.
`tenant_id`	string		REQUIRED when using the fallback ingress token. IGNORED otherwise.
`severity`	string		Free-form severity hint.
`source`	string		Free-form source hint (e.g. `"policy_engine"`).

Example

bash

curl -X POST https://api.veldtlabs.ai/api/v1/admin/agents/events/rogue \
  -H "Authorization: Bearer $VELDT_KYA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "oos_tool",
    "agent_key": "billing.orchestrator",
    "actor_agent_key": "billing.orchestrator",
    "tool": "delete_customer_record",
    "severity": "high",
    "source": "runtime_policy_engine"
  }'

Self-hosted operators can send this via a shared ingress token instead. See Authentication › Ingress tokens.

Response (201 Created):

json response

{
  "accepted": true,
  "event_type": "oos_tool",
  "tenant_id": "tenant_example"
}

Errors

400 — oos_tool without tool field
401 — bad/missing token
500 — storage layer unavailable