---
title: "Execute ad-hoc agent"
method: POST
path: "/agent/v1/execute"
tags: ["Agents"]
---

# Execute ad-hoc agent

`POST /agent/v1/execute`

Creates an ephemeral agent and immediately executes a run. Returns the run ID for polling status and results. This is the fastest way to run an agent without managing agent lifecycle.

**Ephemeral agent lifecycle:** The agent created by this endpoint is automatically soft-deleted and its scoped API key revoked when the run completes (whether it succeeds, fails, or times out). Ephemeral agents do not appear in GET /agent/v1/agents listings. The returned agentId is valid only for the duration of the run — do not store it for reuse. For persistent, reusable agents, use POST /agent/v1/agents instead.

## Request body

- object
  - `prompt` string, required — Task prompt for the agent
  - `instructions` string — System instructions. Defaults to a general-purpose legal assistant prompt if not provided.
  - `model` string — LLM model identifier. Defaults to anthropic/claude-sonnet-4.6
  - `vaultIds` string[], nullable — Restrict agent to specific vault IDs
  - `objectIds` string[], nullable — Scope this run to specific vault object IDs. The agent will only access these objects.
  - `guidance` string, nullable — Additional context or constraints for this run
  - `enabledTools` string[], nullable — Allowlist of tools the agent can use. Mutually exclusive with disabledTools — set one or the other, not both.
  - `disabledTools` string[], nullable — Denylist of tools the agent cannot use. Mutually exclusive with enabledTools — set one or the other, not both.
  - `sandbox` object, nullable — Custom sandbox resources (cpu, memoryMiB)
    - `cpu` integer — Number of CPUs
    - `memoryMiB` integer — Memory in MiB

## Response `200`

Run started

- object
  - `runId` string — Run ID — poll /agent/v1/run/:id/status
  - `agentId` string — Ephemeral agent ID (auto-created). This agent is soft-deleted when the run completes and should not be stored for reuse.
  - `status` 'running'
  - `message` string

## Other responses

- `400` — Missing required fields (prompt)
- `401` — Invalid API key
- `403` — No agent access

---

[API](https://skmtc.net/casemark/apis/case-dev-api.md) · [All operations](https://skmtc.net/casemark/apis/case-dev-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/casemark/case-dev-api/versions/5b7e64e6d6f9/schema)