---
title: "Register immutable durable agent input"
method: POST
path: "/v1/sandboxes/{id}/agent-runs"
tags: ["Sandboxes"]
---

# Register immutable durable agent input

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

## Request

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

Requires an enabled durable-agent deployment. Repeating an identical run ID replays registration. Changed input, name, version or image conflicts. Registration does not start compute.

## Path parameters

- `id` string, required

## Request body

- AgentRunRequest
  - `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.

## Response `201`

Success

- AgentRun
  - `run_id` string, required
  - `name` string, required
  - `version` string, required
  - `image_digest` string, required
  - `status` 'active' | 'blocked' | 'completed' | 'cancelled' | 'expired', required
  - `input` string, byte: 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.
  - `result` string, byte: 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.
  - `epoch` integer, required

## Other responses

- `default`: Operation refused. Unavailable capability is reported while durable agents are disabled.

---

[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)