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

# Remote Dispatch

> Execute automation tasks remotely via the Narada API

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://api.narada.ai/fast/v2/remote-dispatch' \
    -H 'Content-Type: application/json' \
    -H 'x-api-key: YOUR_API_KEY' \
    -d '{
      "prompt": "/Operator click on Insurance header",
      "browserWindowId": "your-browser-window-id",
      "clearChat": true
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.narada.ai/fast/v2/remote-dispatch", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.NARADA_API_KEY,
    },
    body: JSON.stringify({
      prompt: "/Operator click on Insurance header",
      browserWindowId: "your-browser-window-id",
      clearChat: true,
    }),
  });

  const data = await response.json();
  console.log(data); // { "requestId": "req_abc123def456" }
  ```

  ```python Python theme={null}
  import requests
  import os

  response = requests.post(
    'https://api.narada.ai/fast/v2/remote-dispatch',
    headers={
      'Content-Type': 'application/json',
      'x-api-key': os.getenv('NARADA_API_KEY')
    },
    json={
      'prompt': '/Operator click on Insurance header',
      'browserWindowId': 'your-browser-window-id',
      'clearChat': True
    }
  )

  data = response.json()
  print(data) # { "requestId": "req_abc123def456" }
  ```
</RequestExample>

<ResponseExample>
  ```json 202 Accepted theme={null}
  {
    "requestId": "req_abc123def456"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid API key"
  }
  ```

  ```json 404 Browser Window Not Found theme={null}
  {
    "error": "Browser Window Not Found",
    "message": "The specified browser window ID is not available"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "Invalid Request",
    "message": "The prompt field is required and must start with /Operator"
  }
  ```
</ResponseExample>

The Remote Dispatch API allows you to execute automation tasks remotely on browser windows with the Narada Chrome Extension installed, or in serverless [Cloud Browser Sessions](/documentation/cloud-browser-sessions). This endpoint returns immediately with a request ID for tracking, while the actual automation runs asynchronously.

## Authorization

<ParamField header="x-api-key" type="string" required>
  Your Narada API key for authentication. See [Authentication](/documentation/authentication) for how to obtain your key.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json`.
</ParamField>

## Body

<ParamField body="prompt" type="string" required>
  The natural language instruction for the task to execute.

  <Note>
    When using the Python SDK's `Agent.run()` method with the default Operator agent, the `/Operator` prefix is added automatically. When calling the REST API directly, prefix your prompt with `/Operator` to use the web automation agent, or omit it for the Generalist agent.
  </Note>
</ParamField>

<ParamField body="browserWindowId" type="string">
  Unique identifier for the specific browser window to target. Required for `"client"` execution mode. See [Authentication](/documentation/authentication) for more information.
</ParamField>

<ParamField body="executionMode" type="string" default="client">
  How the task should be executed. Possible values:

  * `"client"`: Runs in a browser window with the Narada extension installed (requires `browserWindowId`)
  * `"cloud"`: Runs server-side without a browser
  * `"cloud_browser"`: Creates a fresh [Cloud Browser Session](/documentation/cloud-browser-sessions) and runs the task in it (no extension needed)
</ParamField>

<ParamField body="clearChat" type="boolean" default="true">
  Whether to clear the chat history before executing the command. Set to `false` to continue a previous conversation.
</ParamField>

<ParamField body="previousRequestId" type="string">
  Link this request to a previous one for conversation continuity. When set, the agent retains context from the previous request.
</ParamField>

<ParamField body="generateGif" type="boolean" default="false">
  Whether to capture an animated GIF of the automation process. When enabled, the GIF is automatically saved to the `Narada Downloads` directory. Learn more about [Action Trace](/documentation/action-trace).
</ParamField>

<ParamField body="responseFormat" type="object">
  Specify structured output format using JSON Schema. See [Structured Output documentation](/documentation/structured-output) for detailed examples.

  <Expandable title="Response Format Properties">
    <ParamField body="type" type="string" required>
      Must be set to `"jsonSchema"`.
    </ParamField>

    <ParamField body="jsonSchema" type="object" required>
      A valid JSON Schema object defining the expected response structure.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="attachments" type="array">
  File attachments to provide to the agent. Each attachment is an object with a `key` field (obtained from the file upload endpoint).

  ```json theme={null}
  "attachments": [{"key": "uploads/abc123/report.pdf"}]
  ```
</ParamField>

<ParamField body="timeZone" type="string" default="America/Los_Angeles">
  The timezone for any time-related operations in the automation task.
</ParamField>

<ParamField body="mcpServers" type="array">
  MCP (Model Context Protocol) servers to connect during task execution. Each server provides additional tools the agent can use. See [A2A and MCP](/documentation/a2a-and-mcp).
</ParamField>

<ParamField body="secretVariables" type="object">
  Variables for secure substitution in prompts. Use `${variable_name}` syntax in your prompt. Values are substituted **after** the LLM plans its actions, so the LLM never sees the actual values. Ideal for passwords, API keys, and sensitive data.

  ```json theme={null}
  {
    "prompt": "Log in with username ${user} and password ${pass}",
    "secretVariables": {"user": "john@company.com", "pass": "s3cret"}
  }
  ```
</ParamField>

<ParamField body="inputVariables" type="object">
  Input variables passed to custom agents. These are visible to the agent and accessible in custom agent workflows via the `variables` dictionary. See [Input Variables](/documentation/input-variables).
</ParamField>

<ParamField body="callbackUrl" type="string">
  Webhook URL to receive the response asynchronously when the task completes. See [Webhooks documentation](/documentation/webhooks).
</ParamField>

<ParamField body="callbackSecret" type="string">
  A secret key included in the webhook payload body for verification. Use this to validate that webhook requests are genuinely from Narada.
</ParamField>

<ParamField body="callbackHeaders" type="object">
  HTTP headers to include when sending the webhook POST request to your `callbackUrl`.

  ```json theme={null}
  {
    "callbackHeaders": {
      "Authorization": "Bearer <token>",
      "X-Custom-Header": "value"
    }
  }
  ```

  <Warning>
    Only `Authorization` and headers starting with `x-` (case-insensitive) are allowed. Other headers will be rejected with a 422 error for security reasons.
  </Warning>
</ParamField>

<ParamField body="wait" type="boolean" default="false">
  If `true`, the API blocks until the task completes and returns the full response inline (instead of returning just a `requestId`). Useful for simple scripts. Returns 408 if the task times out.
</ParamField>

<ParamField body="cloudBrowserSessionName" type="string">
  Optional label for the cloud browser session. Only used when `executionMode` is `"cloud_browser"`.
</ParamField>

## Response

<ResponseField name="requestId" type="string" required>
  Unique identifier for tracking the request. Use this ID for: - Polling the
  status via [GET /responses/{requestId}](/api-reference/get-task-status) -
  Correlating webhook responses - Debug and monitoring purposes
</ResponseField>

The API returns `202 ACCEPTED` immediately while the automation task runs in the background. Use the `requestId` to track progress through polling or webhooks.

## Example Commands

```bash theme={null}
# Simple navigation
/Operator navigate to the reports section

# Data extraction
/Operator extract customer information from the current table

# Multi-step workflow
/Operator 1) Navigate to customer database, 2) Search overdue accounts, 3) Export to CSV

# Conditional logic
/Operator if error messages exist, screenshot them, otherwise extract user count

# Cloud browser (no extension needed)
# Set executionMode to "cloud_browser", no browserWindowId required
```

## Best Practices

<Tip>
  **Command Prefix**: Prefix automation commands with `/Operator` to invoke the web agent. When using the Python SDK's `Agent.run()` method with the default Operator agent, this prefix is added automatically.
</Tip>

<Tip>
  **Descriptive Prompts**: Be specific about your intentions. Instead of
  `/Operator click button`, use `/Operator click the Submit button in the
      contact form`.
</Tip>

* **Use Browser Window IDs** to target specific browser contexts when working with multiple windows
* **Implement timeouts** for long-running automation tasks
* **Use webhooks** for better performance with asynchronous processing
* **Test with simple commands** before implementing complex workflows
* **Enable GIF generation** for debugging complex automation sequences

## Rate Limiting

API requests are subject to rate limiting based on your subscription plan. For high-volume usage or custom rate limits, contact [support@narada.ai](mailto:support@narada.ai).