CreateRunRequest

POST /v1/runs. The client mints the run id, so a retried request is the same run (§7.1); the executing device is the worker's own and is not a field a caller supplies.

Type object

Shape

Field	Type	Description
runrequired	RunId
workspacerequired	WorkspaceId	The workspace the Run document is registered in.
requested_byrequired	ActorRef
objectiverequired	Objective	What a person asked the agent to do (D9). The one field of a run that is a prompt, and therefore the one field that must never be reported.
agentrequired	SessionProfileKey	Stable identity for a launch profile. Built-ins remain readable across machines; user-created profiles are opaque UUIDs.
requested_model	DelegateModelName or null	Explicit model intent. New clients use the v2 create route when present.
scoperequired	WorkspaceScope	The working folder a run is admitted to (P1.5) and started in. Identity is a [`ProjectId`] rather than a path: the project already carries a canonical root the host validates at launch, and an id is what a second device can name without being able to resolve it (D15, D16). The folder inside it is text a person chose, and is redacted like every path. `None` is unreachable at admission. It exists so a request can be built before a scope is chosen and so the modal has a state to refuse; P1.5 makes it impossible to start a run with it. M4 adds git shapes - a worktree per run - as new variants, which is why this is an enum.
context	array of RunContextItem	Default `[]`
grants	array of WorkspaceId	The workspaces the run's tools may reach (D28). Empty denies all workspace access. Default `[]`

Example

{
  "run": "00000000-0000-4000-8000-000000000000",
  "workspace": {},
  "requested_by": {
    "profile": "00000000-0000-4000-8000-000000000000",
    "kind": "person"
  },
  "objective": "string",
  "agent": {
    "kind": "built_in",
    "value": "string"
  },
  "requested_model": "string",
  "scope": {
    "kind": "none"
  },
  "context": [],
  "grants": []
}

The contract has no example values, so example bodies are generated from each schema: every field is shown with a placeholder of its type.

Used by

Generated from contract version 1. Last updated November 12, 2026.