Skip to main content

​
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

​
x-api-key
string
required
Your workspace ID from Browsepilot Settings → Advanced
​
Content-Type
string
required
Must be application/json

​
Request Body

​
prompt
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"
​
profileId
string
ID of the browser profile to use for this conversation. If not provided, uses the default profile.
​
modelId
string
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)

​
Response

​
success
boolean
Indicates if the conversation was created successfully
​
conversationId
string
Unique ID of the created conversation. Use this to track the conversation status or send additional messages.
​
message
string
Human-readable confirmation message
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"
  }'

{
  "success": true,
  "conversationId": "conv_1234567890abcdef",
  "message": "Conversation created successfully"
}

​
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
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.)

​
Error Handling

Status CodeErrorDescription
400Invalid requestMissing or invalid parameters in request body
401UnauthorizedMissing or invalid x-api-key header
404UnauthorizedWorkspace not found for provided API key
500Internal server errorUnexpected server error occurred
⌘I