Control Studio Run

POST

/v1/admin/studio/runs/{run_id}/control

curl --request POST \
  --url 'https://example.com/v1/admin/studio/runs/example/control?tenant_id=' \
  --header 'Content-Type: application/json' \
  --data '{ "verb": "", "target_agent_id": "", "handoff_target": "", "thread_id": "", "task_card_id": "", "reason": "", "controller_message": "", "message_body": "", "message_kind": "", "task_subject": "", "task_description": "", "verify_scope": "", "proof_target_url": "", "issue_url": "", "github_issue_url": "", "pr_url": "", "github_pr_url": "", "handoff_intent": "", "required_result": "", "wall_code": "", "required_evidence": [ "example" ], "posthog_session_url": "", "posthog_event_id": "", "otel_trace_id": "", "observed_route": "", "observed_event_name": "", "workspace_tool_mode": "", "required_first_tool_name": "", "agent_process_provider": "", "agent_process_model": "", "agent_process_effort": "", "agent_process_speed": "", "force_fresh_workspace": false, "force_restart_execution_process": false, "wake_target": true, "yolo": false, "yolo_loop_break": false }'

Parameters

Path Parameters

run_id

required

Run Id

string

>= 1 characters

Query Parameters

tenant_id

Tenant Id

string

""

Header Parameters

x-pomerium-jwt-assertion

Any of:

string

string

null

null

X-Api-Key

Any of:

string

string

null

null

X-FractalOps-Tenant-Id

Any of:

string

string

null

null

Request Body^required

Media typeapplication/json

StudioControlIntentIn

object

verb

Verb

string

""

target_agent_id

Target Agent Id

string

""

handoff_target

Handoff Target

string

""

thread_id

Thread Id

string

""

task_card_id

Task Card Id

string

""

reason

Reason

string

""

controller_message

Controller Message

string

""

message_body

Message Body

string

""

message_kind

Message Kind

string

""

task_subject

Task Subject

string

""

task_description

Task Description

string

""

verify_scope

Verify Scope

string

""

proof_target_url

Proof Target Url

string

""

issue_url

Issue Url

string

""

github_issue_url

Github Issue Url

string

""

pr_url

Pr Url

string

""

github_pr_url

Github Pr Url

string

""

handoff_intent

Handoff Intent

string

""

required_result

Required Result

string

""

wall_code

Wall Code

string

""

required_evidence

Required Evidence

Array<string>

posthog_session_url

Posthog Session Url

string

""

posthog_event_id

Posthog Event Id

string

""

otel_trace_id

Otel Trace Id

string

""

observed_route

Observed Route

string

""

observed_event_name

Observed Event Name

string

""

workspace_tool_mode

Workspace Tool Mode

string

""

required_first_tool_name

Required First Tool Name

string

""

agent_process_provider

Agent Process Provider

string

""

agent_process_model

Agent Process Model

string

""

agent_process_effort

Agent Process Effort

string

""

agent_process_speed

Agent Process Speed

string

""

force_fresh_workspace

Force Fresh Workspace

boolean

force_restart_execution_process

Force Restart Execution Process

boolean

wake_target

Wake Target

boolean

default: true

yolo

Yolo

boolean

yolo_loop_break

Yolo Loop Break

boolean

Responses

200

Successful Response

Media typeapplication/json

StudioControlIntentOut

object

run_id

Run Id

string

""

session_id

Session Id

string

""

agent_id

Agent Id

string

""

verb

Verb

string

""

status

Status

string

""

detail

Detail

string

""

intervention_id

Intervention Id

string

""

audit_event_type

Audit Event Type

string

""

updated_controller_state

Updated Controller State

string

""

followup_task_id

Followup Task Id

string

""

followup_task_url

Followup Task Url

string

""

thread_id

Thread Id

string

""

message_id

Message Id

string

""

task_card_id

Task Card Id

string

""

mailbox_entry_id

Mailbox Entry Id

string

""

updated_verify_status

StudioVerificationOut

object

status

Status

string

default: idle

scope

Scope

string

default: run

detail

Detail

string

""

requested_at

Requested At

string

""

updated_at

Updated At

string

""

requested_by

Requested By

string

""

target_session_id

Target Session Id

string

""

target_agent_id

Target Agent Id

string

""

proof_target_url

Proof Target Url

string

""

artifact_refs

Artifact Refs

Array<string>

screenshot_refs

Screenshot Refs

Array<string>

video_refs

Video Refs

Array<string>

trace_refs

Trace Refs

Array<string>

Example

{
  "run_id": "",
  "session_id": "",
  "agent_id": "",
  "verb": "",
  "status": "",
  "detail": "",
  "intervention_id": "",
  "audit_event_type": "",
  "updated_controller_state": "",
  "followup_task_id": "",
  "followup_task_url": "",
  "thread_id": "",
  "message_id": "",
  "task_card_id": "",
  "mailbox_entry_id": "",
  "updated_verify_status": {
    "status": "idle",
    "scope": "run",
    "detail": "",
    "requested_at": "",
    "updated_at": "",
    "requested_by": "",
    "target_session_id": "",
    "target_agent_id": "",
    "proof_target_url": ""
  }
}

422

Validation Error

Media typeapplication/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

input

Input

ctx

Context

object

Example^generated

{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}