Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.smooth.sh/llms.txt

Use this file to discover all available pages before exploring further.

We recommend using one of our SDKs instead of calling the API directly. The SDKs handle authentication, polling, and error handling automatically, making integration much simpler.If we don’t support your language yet, reach out at support@circlemind.co and we’ll be happy to support your implementation.
The Smooth API enables programmatic browser automation through REST endpoints. You can run AI-powered tasks, create interactive browser sessions, and extend agent capabilities with custom tools.

​
Quick Start

Get your API key and start running tasks in minutes.

Get your free API key

Unlock your free welcome credits. No credit card required.

​
Authentication

All API endpoints require authentication via the apikey header: 
curl -X POST "https://api.smooth.sh/api/v1/task" \
     -H "apikey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"task": "Go to hacker news and get the top story"}'

​
Two Ways to Use the API

​
1. Simple Tasks

Run one-shot tasks that execute and return results: 
# Submit a task
curl -X POST "https://api.smooth.sh/api/v1/task" \
     -H "apikey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"task": "Go to hacker news and get the top 5 stories"}'

# Response: {"r": {"id": "task_abc123", "status": "running", ...}}

# Poll for results
curl -X GET "https://api.smooth.sh/api/v1/task/task_abc123" \
     -H "apikey: YOUR_API_KEY"

# Response: {"r": {"id": "task_abc123", "status": "done", "output": "..."}}

​
2. Session Workflows

For multi-step workflows, create a session and send actions: 
# Create a session (task=null)
curl -X POST "https://api.smooth.sh/api/v1/task" \
     -H "apikey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"task": null, "url": "https://example.com"}'

# Response: {"r": {"id": "task_abc123", "status": "running", "live_url": "..."}}

# Send actions via the Event endpoint
curl -X POST "https://api.smooth.sh/api/v1/task/task_abc123/event" \
     -H "apikey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "session_action",
       "payload": {"name": "run_task", "input": {"task": "Click the login button"}},
       "id": "evt_001"
     }'

# Poll for the result
curl -X GET "https://api.smooth.sh/api/v1/task/task_abc123?event_t=0" \
     -H "apikey: YOUR_API_KEY"

Session Workflow

Learn how to create sessions, send actions, and poll for results

Polling Mechanism

Understand how to efficiently poll for task results and events

​
Core Endpoints

EndpointMethodDescription
/taskPOSTSubmit a task or create a session (task=null)
/taskGETList all tasks
/task/{id}GETGet task status and results
/task/{id}DELETECancel a running task
/task/{id}/eventPOSTSend an event to a running task/session

​
Session Actions

When using sessions, send actions via POST /task/{id}/event:
ActionEvent TypeDescription
Navigatebrowser_actionGo to a URL
Extractbrowser_actionExtract structured data from the page
JavaScriptbrowser_actionExecute JavaScript in the browser
Run Tasksession_actionRun an AI-powered task within the session
Closesession_actionClose the session

Session Actions Reference

See complete examples of all session actions

​
Custom Tools

Extend agent capabilities by registering custom tools: 
curl -X POST "https://api.smooth.sh/api/v1/task" \
     -H "apikey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "task": "Look up the weather and send it to Slack",
       "custom_tools": [
         {
           "name": "get_weather",
           "description": "Get weather for a city",
           "inputs": {"type": "object", "properties": {"city": {"type": "string"}}},
           "output": "Weather data"
         },
         {
           "name": "send_slack",
           "description": "Send a Slack message",
           "inputs": {"type": "object", "properties": {"message": {"type": "string"}}},
           "output": "Success boolean"
         }
       ]
     }'
When the agent calls a tool, you receive a tool_call event. Execute the tool locally and respond via the Event endpoint.

Custom Tools Guide

Complete guide to implementing custom tools with the API

​
Additional Features

​
Browser Profiles

Persist cookies and authentication across tasks: 
# Create a profile
curl -X POST "https://api.smooth.sh/api/v1/profile" \
     -H "apikey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"id": "my-profile"}'

# Use the profile in a task
curl -X POST "https://api.smooth.sh/api/v1/task" \
     -H "apikey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"task": "Check my account balance", "profile_id": "my-profile"}'

​
Structured Output

Get structured data matching a JSON schema: 
curl -X POST "https://api.smooth.sh/api/v1/task" \
     -H "apikey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "task": "Get the top 3 stories from Hacker News",
       "response_model": {
         "type": "array",
         "items": {
           "type": "object",
           "properties": {
             "title": {"type": "string"},
             "url": {"type": "string"},
             "points": {"type": "number"}
           }
         }
       }
     }'

​
File Uploads

Pass files to tasks: 
# Upload a file
curl -X POST "https://api.smooth.sh/api/v1/file" \
     -H "apikey: YOUR_API_KEY" \
     -F "file=@invoice.pdf"

# Response: {"r": {"id": "file_xyz789"}}

# Use in a task
curl -X POST "https://api.smooth.sh/api/v1/task" \
     -H "apikey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"task": "Extract the total from this invoice", "files": ["file_xyz789"]}'

​
Response Format

All responses are wrapped in an r field: 
{
  "r": {
    "id": "task_abc123",
    "status": "done",
    "output": "...",
    "credits_used": 15
  }
}

​
Task Status Values

StatusDescription
waitingTask is queued
runningTask is executing
doneTask completed successfully
failedTask failed
cancelledTask was cancelled

​
Error Handling

HTTP CodeMeaning
400Invalid request parameters
403Premium feature not available on your plan
404Resource not found
422Validation error
429Rate limit exceeded or credits exhausted
Error responses include a detail message: 
{
  "detail": "API credits exhausted. Please upgrade your plan."
}

​
Next Steps

Session Workflow

Create interactive sessions for multi-step workflows

Custom Tools

Extend agent capabilities with your own tools

Polling Guide

Best practices for polling task results

Python SDK

Use the SDK for automatic polling and easier integration