Execute ad-hoc agent

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.

POST /agent/v1/execute

Execute ad-hoc agent

cURL

curl --request POST \
  --url https://api.case.dev/agent/v1/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "instructions": "<string>",
  "model": "<string>",
  "vaultIds": [
    "<string>"
  ],
  "objectIds": [
    "<string>"
  ],
  "guidance": "<string>",
  "enabledTools": [
    "<string>"
  ],
  "disabledTools": [
    "<string>"
  ],
  "sandbox": {
    "cpu": 123,
    "memoryMiB": 123
  }
}
'

200

{
  "runId": "<string>",
  "agentId": "<string>",
  "status": "running",
  "message": "<string>"
}

Authorizations

Authorization · string · header · required

API key starting with sk_case_

Body

application/json

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[] | null

Restrict agent to specific vault IDs

objectIds · string[] | null

Scope this run to specific vault object IDs. The agent will only access these objects.

guidance · string | null

Additional context or constraints for this run

enabledTools · string[] | null

Allowlist of tools the agent can use. Mutually exclusive with disabledTools — set one or the other, not both.

disabledTools · string[] | null

Denylist of tools the agent cannot use. Mutually exclusive with enabledTools — set one or the other, not both.

sandbox · object

Custom sandbox resources (cpu, memoryMiB)

Show child attributes

Response

200

application/json

Run started

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 · enum<string>

Available options: running

message · string