---
title: "Dispatch an agent run"
method: POST
path: "/api/orgs/{org}/agents/dispatch"
tags: ["Agents"]
---

# Dispatch an agent run

`POST /api/orgs/{org}/agents/dispatch`

Dispatches a new AgentDispatchRun against the named stack. The agent will
process the prompt in the context of the specified repository and branch.

## Path parameters

- `org` string, required

## Request body

- union
  - object
    - `agentDefinition` string, required — Name of the AgentDefinition to dispatch
    - `definitionRef` string — Alias for agentDefinition
    - `stackRef` string — Name of the legacy AgentStack to dispatch
    - `agentStack` string — Alias for stackRef
    - `repository` string — Repository name for the agent run context
    - `branch` string — Git branch the agent should operate on
    - `prompt` string — Initial prompt or task for the agent
    - `context` object — Additional context passed to the agent
  - object
    - `agentDefinition` string — Name of the AgentDefinition to dispatch
    - `definitionRef` string, required — Alias for agentDefinition
    - `stackRef` string — Name of the legacy AgentStack to dispatch
    - `agentStack` string — Alias for stackRef
    - `repository` string — Repository name for the agent run context
    - `branch` string — Git branch the agent should operate on
    - `prompt` string — Initial prompt or task for the agent
    - `context` object — Additional context passed to the agent
  - object
    - `agentDefinition` string — Name of the AgentDefinition to dispatch
    - `definitionRef` string — Alias for agentDefinition
    - `stackRef` string, required — Name of the legacy AgentStack to dispatch
    - `agentStack` string — Alias for stackRef
    - `repository` string — Repository name for the agent run context
    - `branch` string — Git branch the agent should operate on
    - `prompt` string — Initial prompt or task for the agent
    - `context` object — Additional context passed to the agent
  - object
    - `agentDefinition` string — Name of the AgentDefinition to dispatch
    - `definitionRef` string — Alias for agentDefinition
    - `stackRef` string — Name of the legacy AgentStack to dispatch
    - `agentStack` string, required — Alias for stackRef
    - `repository` string — Repository name for the agent run context
    - `branch` string — Git branch the agent should operate on
    - `prompt` string — Initial prompt or task for the agent
    - `context` object — Additional context passed to the agent

## Response `201`

Agent run dispatched

- object
  - `run` KradleResource — A Kradle (Kubernetes-style) resource object
    - `apiVersion` string, required
    - `kind` string, required — Resource kind (e.g. Repository, AgentStack)
    - `metadata` object, required
      - `name` string, required
      - `namespace` string
      - `labels` object
      - `annotations` object
      - `creationTimestamp` string, date-time
    - `spec` object — Resource spec (kind-specific fields)
    - `status` object — Resource status (set by controller)
  - `runName` string — Name of the created AgentDispatchRun
  - `status` string

## Other responses

- `400` — Bad request — invalid input or malformed JSON
- `500` — Internal server error

---

[API](https://skmtc.dev/a5c-ai/apis/kradle-api.md) · [All operations](https://skmtc.dev/a5c-ai/apis/kradle-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/a5c-ai/kradle-api/revisions/b5eadb2ecd8b/schema)