---
title: "Append Run Event"
method: POST
path: "/api/v1/runs/{id}/events"
tags: ["Run Internals"]
---

# Append Run Event

`POST /api/v1/runs/{id}/events`

Appends a validated event to the run event log. Intended for trusted internal callers.

## Path parameters

- `id` string, required

## Request body

- RunEvent — Internal RunEvent-compatible JSON payload. The server validates this body by deserializing into the typed RunEvent struct.
  - `id` string, required
  - `ts` string, date-time, required
  - `run_id` string, required
  - `node_id` string, nullable
  - `node_label` string, nullable
  - `stage_id` string, nullable — Stage execution identity, formatted as "{node_id}@{visit}".
  - `parallel_group_id` string, nullable — Durable identity of one execution of a parallel node, formatted as "{node_id}@{visit}".
  - `parallel_branch_id` string — Durable identity of one branch within a parallel execution, in `{parallel_group_id}:{index}` form.
  - `session_id` string, nullable
  - `parent_session_id` string, nullable
  - `tool_call_id` string, nullable — Stable identifier for a tool call, present on agent.tool.* events and other durable events that directly describe the same tool call.
  - `actor` union
    - PrincipalUser
      - `kind` 'user', required
      - `identity` IdpIdentity, required
        - `issuer` string, required
        - `subject` string, required
      - `login` string, required
      - `auth_method` 'github' | 'dev_token', required — Runtime user authentication method.
      - `avatar_url` string, nullable
    - PrincipalWorker
      - `kind` 'worker', required
      - `run_id` string, required
    - PrincipalWebhook
      - `kind` 'webhook', required
      - `delivery_id` string, required
    - PrincipalSlack
      - `kind` 'slack', required
      - `team_id` string, required
      - `user_id` string, required
      - `user_name` string, nullable
    - PrincipalAgent
      - `kind` 'agent', required
      - `session_id` string, nullable
      - `parent_session_id` string, nullable
      - `model` string, nullable
    - PrincipalSystem
      - `kind` 'system', required
      - `system_kind` 'engine' | 'watchdog' | 'timeout', required
  - `event` string, required — Event type discriminator.
  - `properties` object

## Response `200`

Event appended

- AppendEventResponse — Assigned sequence number for an appended event.
  - `seq` integer, required — Assigned event sequence number.

## Other responses

- `400` — Invalid event payload
- `404` — Run not found

## Changes

- **2026-07-28** `148f0a9eb912` — 2 breaking, 1 info
  - the request property `parallel_branch_id` became not nullable
  - the `parallel_branch_id` request property type/format changed from `string, null`/`` to ``/``
  - added `#/components/schemas/ParallelBranchId, subschema #2` to the `parallel_branch_id` request property `oneOf` list
- **2026-07-28** `3c01c6d3d31e` — 2 breaking, 1 info
  - removed `#/components/schemas/ParallelBranchId, subschema #2` from the `parallel_branch_id` request property `oneOf` list
  - the `parallel_branch_id` request property type/format changed from ``/`` to `string, null`/``
  - the request property `parallel_branch_id` became nullable
- **2026-07-28** `7fe7b6755799` — 2 breaking, 1 info
  - the request property `parallel_branch_id` became not nullable
  - the `parallel_branch_id` request property type/format changed from `string, null`/`` to ``/``
  - added `#/components/schemas/ParallelBranchId, subschema #2` to the `parallel_branch_id` request property `oneOf` list
- **2026-06-13** `de85d0556040` — 1 breaking, 1 info
  - removed `#/components/schemas/PrincipalAnonymous` from the `actor/oneOf[#/components/schemas/Principal]/` request property `oneOf` list
  - removed `anonymous` discriminator mapping keys from the `actor/oneOf[#/components/schemas/Principal]/` request property

[Change history](https://skmtc.dev/fabro-sh/apis/fabro-run-api/changes/api/v1/runs/:id/events/post.md)

---

[API](https://skmtc.dev/fabro-sh/apis/fabro-run-api.md) · [All operations](https://skmtc.dev/fabro-sh/apis/fabro-run-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fabro-sh/fabro-run-api/revisions/953c9d3ea979/schema)