---
title: "Create run"
method: POST
path: "/agent/v1/run"
tags: ["Agents"]
---

# Create run

`POST /agent/v1/run`

Creates a run in queued state. Call POST /agent/v1/run/:id/exec to start execution.

## Request body

- object
  - `agentId` string, required — ID of the agent to run
  - `prompt` string, required — Task prompt for the agent
  - `guidance` string, nullable — Additional guidance for this run
  - `model` string, nullable — Override the agent default model for this run
  - `objectIds` string[], nullable — Scope this run to specific vault object IDs. The agent will only be able to access these objects during execution.
  - `callbackUrl` string, uri, nullable — HTTPS callback URL to receive a notification when the run completes. Registered atomically with the run — eliminates the race condition of calling /watch after /exec. Additional watchers can still be added via POST /run/:id/watch.

## Response `200`

Run created in queued state

- object
  - `id` string
  - `agentId` string
  - `status` 'queued'
  - `objectIds` string[], nullable
  - `createdAt` string, date-time

## Other responses

- `400` — Missing required fields (agentId, prompt)
- `401` — Invalid API key
- `403` — No agent access
- `404` — Agent not found

---

[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)