---
title: "Start an isolated Banger internal-agent run."
method: POST
path: "/v1/workspaces/{workspaceId}/agent-runs"
---

# Start an isolated Banger internal-agent run.

`POST /v1/workspaces/{workspaceId}/agent-runs`

## Request

- Base URL: `https://api.bangermail.com`
- URL: `https://api.bangermail.com/v1/workspaces/{workspaceId}/agent-runs`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `task` string, required
  - `model` string
  - `max_steps` integer
  - `max_runtime_seconds` integer
  - `connection_tools` object[]
    - `connection_id` string, uuid, required
    - `adapter_key` string, required
    - `operations` string[], required
  - `action_tools` string[]

## Response `200`

Idempotent replay of the existing run.

- object
  - `data` AgentRun, required
    - `id` string, uuid, required
    - `execution_job_id` string, uuid
    - `requested_by_actor_id` string, required
    - `task` string, required
    - `model` string, required
    - `capability_scopes` string[], required
    - `resource_scope` object, required
    - `status` 'queued' | 'running' | 'waiting_approval' | 'waiting_external' | 'succeeded' | 'failed' | 'cancelled', required
    - `max_steps` integer, required
    - `max_runtime_seconds` integer, required
    - `current_generation` integer, required
    - `latest_checkpoint` object, nullable
    - `latest_checkpoint_sequence` integer, required
    - `result` object, nullable
    - `error_code` string, nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `started_at` string, date-time, nullable
    - `completed_at` string, date-time, nullable
    - `replayed` boolean, required
    - `steps` AgentRunStep[]
      - `sequence` integer, required
      - `attempt_generation` integer, required
      - `kind` 'model' | 'tool' | 'checkpoint' | 'approval' | 'output' | 'system', required
      - `status` 'started' | 'succeeded' | 'failed' | 'waiting_approval' | 'waiting_external', required
      - `name` string, nullable
      - `input` unknown
      - `output` unknown
      - `error_code` string, nullable
      - `input_tokens` integer, nullable
      - `output_tokens` integer, nullable
      - `created_at` string, date-time, required
      - `completed_at` string, date-time, nullable

## Other responses

- `202`: Agent run durably accepted and queued.

---

[API](https://skmtc.dev/bangermail/apis/banger-api.md) · [All operations](https://skmtc.dev/bangermail/apis/banger-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bangermail/apis/banger-api/revisions/a149909267f9?raw)