---
title: "Commit an event and wake its sandbox driver"
method: POST
path: "/v1/sandboxes/{id}/agent-events"
tags: ["Sandboxes"]
---

# Commit an event and wake its sandbox driver

`POST /v1/sandboxes/{id}/agent-events`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/v1/sandboxes/{id}/agent-events`
- Auth: HTTP bearer

Account authentication is required. Receipt, immutable run, driver exec and normal lifecycle wake intent commit atomically. Exact source and event ID replay returns the same logical run. Changed command or payload conflicts. Normal billing, deadline, capacity and cleanup gates still apply. Queued events expire after seven days. Lost drivers have at most three attempts and unknown external effects block automatic restart.

## Path parameters

- `id` string, required

## Request body

- AgentEventRequest
  - `source` string, required
  - `event_id` string, required
  - `run` AgentRunRequest, required
    - `run_id` string, required
    - `name` string, required
    - `version` string, required
    - `image_digest` string, required
    - `encoding` 'json-v1', required
    - `input` string, byte, required: Base64 of exact UTF-8 json-v1 bytes, at most 256 KiB decoded. Objects use sorted keys and compact encoding. Nonfinite numbers, duplicate keys and non-JSON values are refused.
  - `command` string[], required: Explicit driver argv, validated with normal exec bounds. No environment or stdin fields are accepted. Include the run identity in the command as required by your driver.

## Response `202`

Success

- AgentEvent
  - `source` string, required
  - `event_id` string, required
  - `run_id` string, required
  - `exec_id` string, required
  - `state` 'queued' | 'running' | 'blocked' | 'handled' | 'expired', required
  - `reason` string, required
  - `created_at` string, date-time, required
  - `expires_at` string, date-time, required

## Other responses

- `default`: Request refused

---

[API](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api.md) - [All operations](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/revisions/a59210899d95?raw)