Sign in
Edge

Append a single Edge agent action event

Changed on

Writes a redacted AgentActionEvent for an existing Edge session/execution. Raw tool inputs, raw tool results, and transcripts must not be sent inline; send bounded input_redacted details and reference large evidence with artifact_ptrs. Optional Idempotency-Key retries are scoped by tenant and endpoint: the same normalized request replays the first 201 response without appending a duplicate event, while the same key with a different normalized request returns 409 idempotency_conflict. The append and replay record commit in one Redis transaction. If the replay record has expired and the same logical event_id is already present, the API returns 409 idempotency_window_expired and does not append a duplicate event.

post/api/v1/edge/events

Request

  • Base URL: http://localhost:8081
  • URL: http://localhost:8081/api/v1/edge/events
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Headers

X-Tenant-IDstring required

Tenant isolation header (required on all protected routes).

Idempotency-Keystring uuid

Optional idempotency key for safe retries. Edge event create/batch scopes keys by tenant and endpoint, replays the first response for the same normalized request, and returns 409 idempotency_conflict if the same key is reused with a different normalized request. Callers SHOULD send a UUID (per the original Job submit contract); the Edge runtime additionally accepts any non-empty string up to 512 bytes for backward-compatible local-dev keys.

Request body

event_idstring required
session_idstring required
execution_idstring required
tenant_idstring

Optional body tenant; when present it must match X-Tenant-ID.

principal_idstring
seqinteger

Optional sequence number. Omit or set 0 for server assignment; explicit values must be the next sequence for the execution.

tsstring date-time required
layer'hook' | 'mcp' | 'llm' | 'runtime' | 'workflow' | 'system' required
kindstring required

Open-ended non-empty event kind such as hook.pre_tool_use or mcp.tool.pre.

agent_productstring
tool_namestring
tool_use_idstring
action_namestring
capabilitystring
risk_tagsstring[]
input_redactedobject nullable

Bounded, redacted, client-safe input summary. Secrets and large raw payloads are rejected; store large evidence using artifact_ptrs.

input_hashstring

Optional stable hash. When input_redacted is present, the server derives a stable sha256: hash before persistence.

decision'ALLOW' | 'DENY' | 'REQUIRE_APPROVAL' | 'THROTTLE' | 'CONSTRAIN' | 'RECORDED' required
decision_reasonstring
rule_idstring
policy_snapshotstring
approval_refstring
duration_msinteger
status'ok' | 'blocked' | 'failed' | 'degraded' required
error_codestring
error_messagestring
labelsEdgeLabels

Response

Edge event appended

event_idstring required
session_idstring required
execution_idstring required
tenant_idstring required
principal_idstring
seqinteger required
tsstring date-time required
layer'hook' | 'mcp' | 'llm' | 'runtime' | 'workflow' | 'system' required
kindstring required

Open-ended non-empty event kind such as hook.pre_tool_use or mcp.tool.pre.

agent_productstring
tool_namestring
tool_use_idstring
action_namestring
capabilitystring
risk_tagsstring[]
input_redactedobject nullable

Bounded redacted input summary safe to persist and return.

input_hashstring

Stable sha256: hash for the original input when available.

decision'ALLOW' | 'DENY' | 'REQUIRE_APPROVAL' | 'THROTTLE' | 'CONSTRAIN' | 'RECORDED' required
decision_reasonstring
rule_idstring
policy_snapshotstring
approval_refstring
duration_msinteger
status'ok' | 'blocked' | 'failed' | 'degraded' required
error_codestring
error_messagestring
labelsEdgeLabels

Changes

  • 12120aad0bfeRevision changes
    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

  • 9f66383d6e95Revision changes
    • info

      endpoint added