---
title: Create an agent run
description: "Creates a sandbox-backed run in the caller's workspace."
api_method: POST
api_path: "/v1/agent-runs"
canonical_url: https://wiblo.app/docs/developers/api/agent-runs/create-agent-run
last_updated: 2026-07-28T17:31:44+02:00
md_url: https://wiblo.app/docs/developers/api/agent-runs/create-agent-run.md
---

# Create an agent run

`POST /v1/agent-runs`

Creates a sandbox-backed run in the caller's workspace. Optionally seeds a default thread (provider/model/mode) and, when its `message` is present, a first turn — recording the opening event log (`run.started`, `turn.started`, `message.user`) so simple chat clients create-and-talk in one call. Returns a run snapshot plus `defaultThreadId` (when seeded), `latestSeq`, and `eventsUrl`; the client then subscribes to `GET {eventsUrl}?after=<latestSeq>`. The run progresses independently of any stream — a v1 fake provider emits deterministic deltas; a turn ending leaves the run `idle` (not `ended`). Per-user rate-limited at 30/60s.

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `workspaceId` | `string` | Yes |  |
| `siteId` | `string` | No |  |
| `target` | `CreateAgentRunTarget` | No |  |
| `sandbox` | `CreateAgentRunSandbox` | No |  |
| `source` | `CreateAgentRunSource` | No |  |
| `additionalRepos` | `array<CreateAgentRunAdditionalRepo>` | No |  |
| `mode` | `"default" \| "plan" \| "auto-accept-edits" \| "full-access"` | No |  |
| `credentialRole` | `"admin" \| "member"` | No |  |
| `thread` | `CreateAgentRunThreadSeed` | No |  |
| `metadata` | `object` | No | Defaults to `{}`. |

### The CreateAgentRunTarget object

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `"cloud" \| "local"` | No |  |
| `runtime` | `"vercel-sandbox" \| "desktop-sidecar"` | No |  |
| `deviceId` | `string` | No |  |
| `syncMode` | `"write-through" \| "offline-buffered"` | No |  |

### The CreateAgentRunSandbox object

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `runtime` | `"node26" \| "node24" \| "node22" \| "python3.13"` | No |  |
| `vcpus` | `integer` | No |  |
| `timeoutMs` | `integer` | No |  |

### The CreateAgentRunAdditionalRepo object

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `repoId` | `string` | Yes |  |
| `folder` | `RepoFolderName` | Yes |  |
| `ref` | `string` | No |  |

### The CreateAgentRunThreadSeed object

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | `"claude-code" \| "codex"` | Yes |  |
| `model` | `string \| null` | No | Defaults to `null`. |
| `mode` | `"ask" \| "edit"` | No |  |
| `title` | `string \| null` | No | Defaults to `null`. |
| `message` | `CreateAgentRunMessage` | No |  |

### The CreateAgentRunMessage object

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | No |  |
| `content` | `array<AgentUserContent>` | Yes |  |

## Request

**curl**

```bash
curl https://api.wiblo.app/v1/agent-runs \
  -X POST \
  -H "Authorization: Bearer $WIBLO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "workspaceId": "..."
}'
```

**TypeScript**

```ts
import { createSdk, createAgentRun } from "@workspace/sdk"

const sdk = createSdk({ baseUrl: "https://api.wiblo.app" })

const { data, error } = await createAgentRun({
  client: sdk,
  body: {
    "workspaceId": "..."
  },
})
```

## Responses

**`201`** — The run was created and its initial events recorded. Returns `AgentRunResponse`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `run` | `AgentRun` | Yes |  |
| `defaultThreadId` | `string \| null` | No | Defaults to `null`. |
| `latestSeq` | `integer` | Yes |  |
| `eventsUrl` | `string` | Yes |  |
| `usage` | `AgentRunUsageSummary` | No |  |

**`400`** — Request body failed Zod validation (`VALIDATION_FAILED`). Returns `ApiErrorEnvelope`.

**`401`** — No valid session cookie or `wbl_*` bearer was present. Returns `ApiErrorEnvelope`.

**`404`** — Caller has no active membership in the target workspace, or it does not exist (`WORKSPACE_NOT_FOUND`). Both collapse to one envelope to avoid leaking existence. Returns `ApiErrorEnvelope`.

**`422`** — A `local` execution target was requested. Desktop execution is not yet available (`AGENT_LOCAL_TARGET_UNSUPPORTED`); omit `target` or pass `cloud`. Returns `ApiErrorEnvelope`.

**`429`** — Rate limit exceeded. The body's `error.code` is `RATE_LIMITED` and `error.details.retry_after` is the same number of seconds as the `Retry-After` header. Returns `ApiErrorEnvelope`.

### The AgentRun object

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes |  |
| `workspaceId` | `string` | Yes |  |
| `siteId` | `string \| null` | Yes |  |
| `provider` | `object` | Yes |  |
| `status` | `"pending" \| "running" \| "idle" \| "awaiting_approval" \| "awaiting_input" \| "completed" \| ...` | Yes |  |
| `model` | `string \| null` | Yes |  |
| `branch` | `string \| null` | Yes |  |
| `source` | `AgentRunSource` | No |  |
| `createdBy` | `string` | Yes |  |
| `createdAt` | `string` | Yes |  |
| `updatedAt` | `string` | Yes |  |
| `completedAt` | `string \| null` | Yes |  |

### The AgentRunUsageSummary object

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `inputTokens` | `integer` | Yes |  |
| `cachedInputTokens` | `integer` | Yes |  |
| `cacheCreationInputTokens` | `integer` | Yes |  |
| `outputTokens` | `integer` | Yes |  |
| `reasoningTokens` | `integer` | Yes |  |
| `totalCostUsd` | `number \| null` | Yes |  |
| `turns` | `integer` | Yes |  |

### The AgentRunSource object

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `"scratch" \| "template" \| "repo" \| "github"` | Yes |  |
| `repoId` | `string \| null` | No | Defaults to `null`. |
| `repo` | `string \| null` | No | Defaults to `null`. |
| `ref` | `string \| null` | No | Defaults to `null`. |
| `folder` | `string \| null` | No | Defaults to `null`. |
| `lastSyncedSha` | `string \| null` | No | Defaults to `null`. |