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

# Start Conversation

> Create a new AI browser automation conversation

## POST /api/chat

Starts a new conversation with your AI browser agent. This creates both a conversation record and sends the initial user message to begin the automation task.

### Headers

<ParamField header="x-api-key" type="string" required>
  Your workspace ID from Browsepilot Settings → Advanced
</ParamField>

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

### Request Body

<ParamField body="prompt" type="string" required>
  The initial instruction for your AI browser agent. Be specific about what you
  want to accomplish. **Examples:** - `"Go to Amazon and find the best-rated
      wireless headphones under $100"` - `"Fill out the contact form on example.com
      with my business information"` - `"Search for software engineer jobs in San
      Francisco on LinkedIn"`
</ParamField>

<ParamField body="profileId" type="string" optional>
  ID of the browser profile to use for this conversation. If not provided, uses
  the default profile.
</ParamField>

<ParamField body="modelId" type="string" optional>
  AI model to use for this conversation. Defaults to `"gemini-2.5-flash"` if not
  specified. **Supported models:** - `"gpt-4.1-2025-04-14"` - GPT-4.1 (OpenAI) -
  `"gpt-5-2025-08-07"` - GPT-5 (OpenAI) - `"claude-sonnet-4-20250514"` - Claude
  Sonnet 4 (Anthropic) - `"grok-4-0709"` - Grok 4 (xAI) - `"gemini-2.5-flash"` -
  Gemini 2.5 Flash (Google) *Default* - `"gemini-2.5-pro"` - Gemini 2.5 Pro
  (Google)
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates if the conversation was created successfully
</ResponseField>

<ResponseField name="conversationId" type="string">
  Unique ID of the created conversation. Use this to track the conversation
  status or send additional messages.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable confirmation message
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://browsepilot.ai/api/chat" \
    -H "x-api-key: your-workspace-id" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Go to Google and search for the latest AI news",
      "profileId": "profile_abc123",
      "modelId": "gemini-2.5-flash"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://browsepilot.ai/api/chat", {
    method: "POST",
    headers: {
      "x-api-key": process.env.BROWSEPILOT_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "Find the top 5 trending repositories on GitHub",
      profileId: "profile_xyz789",
    }),
  });

  const data = await response.json();
  console.log("Conversation ID:", data.conversationId);
  ```

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

  response = requests.post(
      'https://browsepilot.ai/api/chat',
      headers={
          'x-api-key': 'your-workspace-id',
          'Content-Type': 'application/json'
      },
      json={
          'prompt': 'Check the price of Bitcoin on CoinGecko',
          'modelId': 'gemini-2.5-flash'
      }
  )

  data = response.json()
  print(f"Conversation created: {data['conversationId']}")
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "success": true,
    "conversationId": "conv_1234567890abcdef",
    "message": "Conversation created successfully"
  }
  ```

  ```json Error Response theme={null}
  {
    "error": "Invalid request",
    "details": "prompt is required"
  }
  ```
</ResponseExample>

## What Happens Next?

After creating a conversation:

1. **AI Agent Activation**: Your browser agent receives the prompt and begins planning the task
2. **Browser Session**: A new browser session starts (or uses your specified profile)
3. **Real-time Execution**: The agent begins navigating and interacting with websites
4. **Conversation Updates**: You can monitor progress through the Browsepilot dashboard

<Tip>
  **Best Practices:** - Be specific in your prompts for better results - Use
  browser profiles for tasks requiring login or specific settings - Include
  desired output format ("save as CSV", "create a summary", etc.)
</Tip>

## Error Handling

| Status Code | Error                 | Description                                   |
| ----------- | --------------------- | --------------------------------------------- |
| `400`       | Invalid request       | Missing or invalid parameters in request body |
| `401`       | Unauthorized          | Missing or invalid `x-api-key` header         |
| `404`       | Unauthorized          | Workspace not found for provided API key      |
| `500`       | Internal server error | Unexpected server error occurred              |