> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Send an agent prompt

> Queue a prompt in a machine conversation with an optional credential profile.

## Authentication

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

## Parameters

**id** `string` *required*

Machine identifier returned by creation.

## Request body

The JSON body is required.

**allowCredentialSnapshot** `boolean` (default: false)

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

**approvalPolicy** `string` (default: untrusted)

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

**cwd** `string` *required*

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

**model** `string`

Optional native agent model identifier.

**profileId** `string`

UUID of the credential profile to deliver to this conversation.

**prompt** `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`.

**requestId** `string` *required*

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

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
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
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
# sandbox is returned by Sandbox.create or Sandbox.connect.
for event in sandbox.agent.prompt("Explain this project.", cwd="/root"):
    print(event)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
// 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.

**turnId** `string` *required*

Prompt request UUID; reused when replaying the same request.

**state** `string` *required*

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

**cursor** `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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.