Send an agent prompt

POST

sandboxes

{id}

prompt

curl --request POST \
  --url "https://api.bead.run/sandboxes/$SANDBOX_ID/prompt" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "requestId": "fe1593e7-c31e-4cdd-96df-80ef26fa1275",
  "prompt": "List the files in this workspace and explain the project.",
  "cwd": "/root",
  "approvalPolicy": "untrusted"
}
JSON

# sandbox is returned by Sandbox.create or Sandbox.connect.
for event in sandbox.agent.prompt("Explain this project.", cwd="/root"):
    print(event)

// sandbox is returned by Sandbox.create or Sandbox.connect.
for await (const event of sandbox.agent.prompt("Explain this project.", { cwd: "/root" })) {
  console.log(event);
}

{
  "turnId": "<string>",
  "state": "<string>",
  "cursor": 123
}

Authentication

Send your scoped bearer token in the Authorization: Bearer <BEAD_TOKEN> header, or send your API key in X-API-Key.

Parameters

string

required

Machine identifier returned by creation.

Request body

The JSON body is required.

boolean

default:false

Consent to allow this conversation’s delivered credentials in a later memory snapshot.

string

default:"untrusted"

Native agent approval policy; untrusted asks for approval for untrusted operations and never disables approval prompts. Allowed values: "untrusted", "never".

string

required

Existing absolute working directory inside the machine; create it before submitting the prompt.

string

Optional native agent model identifier.

string

UUID of the credential profile to deliver to this conversation.

string

required

Instruction sent to the native agent. Must contain non-whitespace text and be at most 32768 bytes. Minimum length: 1. Maximum length: 32768.

string

required

Caller-generated UUID for prompt deduplication; reuse it only with the same prompt and options.

curl --request POST \
  --url "https://api.bead.run/sandboxes/$SANDBOX_ID/prompt" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "requestId": "fe1593e7-c31e-4cdd-96df-80ef26fa1275",
  "prompt": "List the files in this workspace and explain the project.",
  "cwd": "/root",
  "approvalPolicy": "untrusted"
}
JSON

# sandbox is returned by Sandbox.create or Sandbox.connect.
for event in sandbox.agent.prompt("Explain this project.", cwd="/root"):
    print(event)

// sandbox is returned by Sandbox.create or Sandbox.connect.
for await (const event of sandbox.agent.prompt("Explain this project.", { cwd: "/root" })) {
  console.log(event);
}

Response

200

Prompt accepted or replayed from its existing request ID.

string

required

Prompt request UUID; reused when replaying the same request.

string

required

The prompt has been accepted. Allowed values: "accepted".

integer

required

Journal sequence number of the acceptance event.

Errors

Status	Meaning
400	Invalid request values, unsupported bounds, or malformed JSON.
401	Authentication credential is missing or rejected.
403	The credential lacks the required scope.
404	The requested resource does not exist or is outside your organization.
409	The machine must be resumed, a conversation binding changed, or a request UUID was reused for different prompt content.
410	Execution memory was lost (`machine_lost`).
413	Request body exceeds the route limit.
429	Request admission or the 32-prompt queue is full (`admission_limit`; limit runner_prompt_queue).
502	The runner returned an invalid response.
503	Machine wake or native agent recovery is required, or the runner is unavailable.

curl --request POST \
  --url "https://api.bead.run/sandboxes/$SANDBOX_ID/prompt" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "requestId": "fe1593e7-c31e-4cdd-96df-80ef26fa1275",
  "prompt": "List the files in this workspace and explain the project.",
  "cwd": "/root",
  "approvalPolicy": "untrusted"
}
JSON

# sandbox is returned by Sandbox.create or Sandbox.connect.
for event in sandbox.agent.prompt("Explain this project.", cwd="/root"):
    print(event)

// sandbox is returned by Sandbox.create or Sandbox.connect.
for await (const event of sandbox.agent.prompt("Explain this project.", { cwd: "/root" })) {
  console.log(event);
}

{
  "turnId": "<string>",
  "state": "<string>",
  "cursor": 123
}

Start here

Endpoints

Send an agent prompt

Authentication

Parameters

Request body

Response

200

Errors

​Authentication

​Parameters

​Request body

​Response

​200

​Errors

Authentication

Parameters

Request body

Response

200

Errors