> ## Documentation Index
> Fetch the complete documentation index at: https://docs.case.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute

> Run a one-shot agent task in a single API call

The execute endpoint is the fastest way to run an agent task without creating a persistent agent or managing a queued run lifecycle.

By default, execute uses the lighter `linc`-based runtime in a Vercel Sandbox and returns the final result in the same HTTP response.

```bash title="Endpoint" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /agent/v1/execute
```

## Default behavior

The default execute flow is synchronous:

* create an ephemeral agent and run record
* boot a Vercel Sandbox with `linc` and the `casedev` CLI
* execute the task immediately
* return the final output, logs, and runtime metadata in the same response

## Request shape

```json title="Request body" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "prompt": "Review the NDA in vault vault_xxx and return the top 5 issues.",
  "instructions": "You are a contract reviewer. Focus on indemnity, liability, term, and confidentiality.",
  "model": "anthropic/claude-sonnet-4.6",
  "vaultIds": ["vault_xxx"],
  "objectIds": ["obj_123"],
  "guidance": "Keep the answer under 10 bullets.",
  "enabledTools": ["vault.search", "legal-research.search"],
  "sandbox": {
    "cpu": 2,
    "memoryMiB": 4096
  }
}
```

### Fields

| Field           | Type      | Required | Description                                                       |
| --------------- | --------- | -------- | ----------------------------------------------------------------- |
| `prompt`        | string    | yes      | The task to execute                                               |
| `instructions`  | string    | no       | System instructions for the ephemeral agent                       |
| `model`         | string    | no       | Model override for this execution                                 |
| `vaultIds`      | string\[] | no       | Limit the execution to specific vaults                            |
| `objectIds`     | string\[] | no       | Limit the execution to specific vault objects                     |
| `guidance`      | string    | no       | Extra run-specific guidance                                       |
| `enabledTools`  | string\[] | no       | Allowlist of tools                                                |
| `disabledTools` | string\[] | no       | Denylist of tools                                                 |
| `sandbox`       | object    | no       | Runtime sizing hints such as CPU and memory                       |
| `agentRuntime`  | boolean   | no       | Set to `true` to opt into the legacy Daytona-backed agent runtime |

`enabledTools` and `disabledTools` are mutually exclusive.

## Response shape

The default response is synchronous and includes the final result directly.

```json title="Response body" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "runId": "run_abc123",
  "agentId": "agent_abc123",
  "status": "completed",
  "provider": "vercel",
  "runtimeId": "sandbox_abc123",
  "runtimeState": "ended",
  "output": "Top issues: 1. Broad indemnity ...",
  "error": null,
  "logs": {
    "runner": "sandbox bootstrap logs...",
    "linc": "agent execution logs..."
  },
  "usage": {
    "model": "anthropic/claude-sonnet-4.6",
    "inputTokens": 4200,
    "outputTokens": 1800,
    "toolCalls": 4,
    "durationMs": 18743
  }
}
```

## Legacy agent runtime

If you need the older Daytona-backed runtime behavior, set `agentRuntime: true`.

```json title="Legacy request body" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "prompt": "Review the NDA in vault vault_xxx and return the top 5 issues.",
  "agentRuntime": true
}
```

That legacy mode returns a queued/running-style response instead of the final output:

```json title="Legacy response body" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "runId": "run_abc123",
  "agentId": "agent_abc123",
  "status": "running",
  "provider": "daytona",
  "runtimeState": "running",
  "message": "Run started. Poll /agent/v1/run/:id/status for progress, or GET /agent/v1/run/:id/details for results."
}
```

## When to use execute

* You want the smallest possible integration surface.
* You do not need a persistent chat session.
* You prefer a blocking request that returns the final answer directly.
* You want the lighter `linc`-based runtime by default.

## When to use runs instead

* You need queued execution and polling semantics.
* You need separate create-run and exec-run steps.
* You want the broader run lifecycle APIs.

See [Execute Runs](/agents/runs) for the full run lifecycle.