---
title: "Append Agent Event"
method: POST
path: "/v1/agent-events"
tags: ["agent-run-monitoring"]
---

# Append Agent Event

`POST /v1/agent-events`

## Request

- Base URL: `https://api.forgeorbital.com`
- URL: `https://api.forgeorbital.com/v1/agent-events`
- Auth: one of:
  - API key in header `X-API-Key`
  - OAuth 2 (client credentials, token URL `/oauth/token`, scopes: `decision_records.write`)
  - OAuth 2 (client credentials, token URL `/oauth/token`, scopes: `decision_records`)
  - HTTP bearer

Append exactly the next ordered event; exact duplicates are safe.

## Headers

- `Idempotency-Key` string, required

## Request body

- AgentRunEventAppendRequest: One immutable event proposed for the next run sequence position.
  - `schema_version` 'forge-agent-run-event/v1'
  - `event_id` string, required
  - `run_id` string, required
  - `sequence` integer, required
  - `parent_event_id` string, nullable
  - `occurred_at` string, date-time, required
  - `event_type` string, required
  - `tool_call_id` string, nullable
  - `action_payload_sha256` string, nullable
  - `result_payload_sha256` string, nullable
  - `previous_event_sha256` string, nullable
  - `event_sha256` string, nullable: Optional caller-computed canonical hash. When supplied it must match Forge's domain-separated v1 hash exactly.
  - `decision_reference` AgentRunDecisionReference
    - `schema_version` 'forge-agent-run-decision-reference/v1', required
    - `validation_status` 'verified_complete_signed_record_projection', required
    - `record_id` string, required
    - `complete_record_sha256` string, required
    - `decision_signing_key_id` string, required
    - `selected_action` string, required
    - `integration_mode` 'pre_action', required
    - `signed_normalized_request_sha256` string, required
    - `signed_action_identity_sha256` string, required
    - `proposed_action_sha256` string, required
    - `proposed_action_payload_sha256` string, required
    - `agent_control_profile_id` string, required
    - `agent_control_profile_version` integer, required
    - `agent_control_profile_sha256` string, required
    - `agent_control_profile_binding_sha256` string, required
    - `authenticated_submitter_principal_sha256` string, required
    - `authenticated_submitter_binding_sha256` string, required

## Response `200`

Exact normalized event replay; no additional event was stored.

- AgentRunAppendResponse
  - `schema_version` 'forge-agent-run-append-response/v1', required
  - `tenant_id` string, required
  - `accepted` true, required
  - `idempotent_replay` boolean, required
  - `event` AgentRunStoredEvent, required
    - `schema_version` 'forge-agent-run-event/v1', required
    - `event_id` string, required
    - `run_id` string, required
    - `sequence` integer, required
    - `parent_event_id` string, nullable, required
    - `occurred_at` string, required
    - `event_type` string, required
    - `tool_call_id` string, nullable, required
    - `action_payload_sha256` string, nullable, required
    - `result_payload_sha256` string, nullable, required
    - `previous_event_sha256` string, nullable, required
    - `event_sha256` string, required
  - `receipt` AgentRunAppendReceipt, required
    - `schema_version` 'forge-agent-run-append-receipt/v1', required
    - `tenant_id` string, required
    - `run_id` string, required
    - `sequence` integer, required
    - `event_type` 'agent.action.blocked' | 'agent.action.executed' | 'agent.action.proposed' | 'forge.decision.received' | 'observation.recorded' | 'run.aborted' | 'run.completed' | 'run.failed' | 'run.started' | 'tool.call.completed' | 'tool.call.started', required
    - `event_id` string, required
    - `event_sha256` string, required
    - `previous_receipt_sha256` string, nullable
    - `committed_at` string, required
    - `runtime` AgentRunRuntimeIdentity, required
      - `schema_version` 'forge-runtime-identity/v1', required
      - `deployment_id` string, required
      - `environment` string, required
      - `image_digest` string, required
    - `decision_reference` AgentRunDecisionReference, required
      - `schema_version` 'forge-agent-run-decision-reference/v1', required
      - `validation_status` 'verified_complete_signed_record_projection', required
      - `record_id` string, required
      - `complete_record_sha256` string, required
      - `decision_signing_key_id` string, required
      - `selected_action` string, required
      - `integration_mode` 'pre_action', required
      - `signed_normalized_request_sha256` string, required
      - `signed_action_identity_sha256` string, required
      - `proposed_action_sha256` string, required
      - `proposed_action_payload_sha256` string, required
      - `agent_control_profile_id` string, required
      - `agent_control_profile_version` integer, required
      - `agent_control_profile_sha256` string, required
      - `agent_control_profile_binding_sha256` string, required
      - `authenticated_submitter_principal_sha256` string, required
      - `authenticated_submitter_binding_sha256` string, required
    - `authenticated_submitter` AgentRunAuthenticatedSubmitter, required
      - `schema_version` 'forge-authenticated-submitter/v1', required
      - `principal_sha256` string, required
      - `credential_class` 'interactive_identity' | 'machine_api_key' | 'machine_oauth_client', required
      - `auth_source` string, required
      - `role` string, required
      - `raw_identity_disclosed` false, required
    - `receipt_sha256` string, required
    - `signature` AgentRunSignatureBlock, required
      - `schema_version` 'forge-record-signature/v2', required
      - `algorithm` 'ed25519', required
      - `signed_field` 'agent_run_append_receipt' | 'complete_agent_run_export', required
      - `canonicalization` 'utf8-json-sort-keys-compact-v1', required
      - `message_prefix` string, required
      - `signed_message_sha256` string, required
      - `signature` string, required
      - `public_key` string, required
      - `key_id` string, required
      - `key_scope` 'configured', required
      - `signed_at` string, required
  - `chain` AgentRunChainTail, required
    - `event_count` integer, required
    - `last_sequence` integer, required
    - `last_event_id` string, required
    - `last_event_sha256` string, required
    - `last_occurred_at` string, required
    - `last_receipt_sha256` string, required
    - `closed` boolean, required
    - `closed_at` string, nullable, required
    - `terminal_event_type` 'run.completed' | 'run.failed' | 'run.aborted', nullable, required

## Other responses

- `201`: Successful Response
- `422`: Stable, sanitized product API error.
- `default`: Stable, sanitized product API error.

---

[API](https://skmtc.dev/forgeorbital/apis/forge-decision-records-api.md) · [All operations](https://skmtc.dev/forgeorbital/apis/forge-decision-records-api/llms.txt) · [OpenAPI document](https://skmtc.dev/forgeorbital/apis/forge-decision-records-api/revisions/4410e0e5c86a?raw)