---
title: "Upload a validated contiguous batch of remote agent events"
method: POST
path: "/api/v1/agent-environments/{environmentId}/events"
tags: ["Agent environments"]
---

# Upload a validated contiguous batch of remote agent events

`POST /api/v1/agent-environments/{environmentId}/events`

## Path parameters

- `environmentId` string, required

## Request body

- object
  - `protocolVersion` 1, required
  - `environmentId` string, required
  - `runId` string, required
  - `events` union[], required
    - union
      - object
        - `protocolVersion` 1, required
        - `eventId` string, required
        - `environmentId` string, required
        - `runId` string, required
        - `sourceSequence` integer, required
        - `occurredAt` integer, required
        - `type` 'session_started', required
        - `payload` object, required
          - `remoteSessionId` string, required
          - `adapterId` string, required
      - object
        - `protocolVersion` 1, required
        - `eventId` string, required
        - `environmentId` string, required
        - `runId` string, required
        - `sourceSequence` integer, required
        - `occurredAt` integer, required
        - `type` 'text_checkpoint', required
        - `payload` object, required
          - `text` string, required
          - `final` boolean
      - object
        - `protocolVersion` 1, required
        - `eventId` string, required
        - `environmentId` string, required
        - `runId` string, required
        - `sourceSequence` integer, required
        - `occurredAt` integer, required
        - `type` 'action', required
        - `payload` object, required
          - `actionId` string, required
          - `title` string, required
          - `status` 'started' | 'updated' | 'completed' | 'failed', required
          - `detail` string
      - object
        - `protocolVersion` 1, required
        - `eventId` string, required
        - `environmentId` string, required
        - `runId` string, required
        - `sourceSequence` integer, required
        - `occurredAt` integer, required
        - `type` 'approval_requested', required
        - `payload` object, required
          - `requestKey` string, required
          - `prompt` string, required
          - `options` object[], required
            - `id` string, required
            - `label` string, required
          - `context` object
      - object
        - `protocolVersion` 1, required
        - `eventId` string, required
        - `environmentId` string, required
        - `runId` string, required
        - `sourceSequence` integer, required
        - `occurredAt` integer, required
        - `type` 'elicitation_requested', required
        - `payload` object, required
          - `requestKey` string, required
          - `prompt` string, required
          - `requestedSchema` object, required
          - `context` object
      - object
        - `protocolVersion` 1, required
        - `eventId` string, required
        - `environmentId` string, required
        - `runId` string, required
        - `sourceSequence` integer, required
        - `occurredAt` integer, required
        - `type` 'plan', required
        - `payload` object, required
          - `entries` object[], required
            - `id` string, required
            - `title` string, required
            - `status` 'pending' | 'in_progress' | 'completed' | 'failed', required
      - object
        - `protocolVersion` 1, required
        - `eventId` string, required
        - `environmentId` string, required
        - `runId` string, required
        - `sourceSequence` integer, required
        - `occurredAt` integer, required
        - `type` 'diff', required
        - `payload` object, required
          - `diffId` string, required
          - `title` string, required
          - `patch` string, required
          - `language` string
      - object
        - `protocolVersion` 1, required
        - `eventId` string, required
        - `environmentId` string, required
        - `runId` string, required
        - `sourceSequence` integer, required
        - `occurredAt` integer, required
        - `type` 'terminal', required
        - `payload` object, required
          - `terminalId` string, required
          - `title` string, required
          - `summary` string, required
          - `exitCode` integer
          - `status` 'running' | 'completed' | 'failed', required
      - object
        - `protocolVersion` 1, required
        - `eventId` string, required
        - `environmentId` string, required
        - `runId` string, required
        - `sourceSequence` integer, required
        - `occurredAt` integer, required
        - `type` 'artifact', required
        - `payload` object, required
          - `name` string, required
          - `mediaType` string, required
          - `size` integer, required
          - `sha256` string, required
          - `uploadReference` string, required
      - object
        - `protocolVersion` 1, required
        - `eventId` string, required
        - `environmentId` string, required
        - `runId` string, required
        - `sourceSequence` integer, required
        - `occurredAt` integer, required
        - `type` 'completed', required
        - `payload` object, required
          - `summary` string
          - `usage` object
      - object
        - `protocolVersion` 1, required
        - `eventId` string, required
        - `environmentId` string, required
        - `runId` string, required
        - `sourceSequence` integer, required
        - `occurredAt` integer, required
        - `type` 'failed', required
        - `payload` object, required
          - `code` string, required
          - `message` string, required
          - `retryable` boolean, required
      - object
        - `protocolVersion` 1, required
        - `eventId` string, required
        - `environmentId` string, required
        - `runId` string, required
        - `sourceSequence` integer, required
        - `occurredAt` integer, required
        - `type` 'cancelled', required
        - `payload` object, required
          - `reason` string

## Response `200`

Successful response. Stable response schemas are documented in workflow guides when available.

- unknown

## Other responses

- `400` — Invalid request.
- `401` — Missing or invalid authentication.
- `500` — Unexpected server error.

## Changes

- **2026-08-27** `e9bf9a73b28a` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/layernorm/apis/overlay-web-api/changes/api/v1/agent-environments/:environmentId/events/post.md)

---

[API](https://skmtc.dev/layernorm/apis/overlay-web-api.md) · [All operations](https://skmtc.dev/layernorm/apis/overlay-web-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/layernorm/overlay-web-api/revisions/a64546f5bde3/schema)