Skip to main content
POST
/
task
curl -X POST "https://api.smooth.sh/api/v1/task" \
     -H "Content-Type: application/json" \
     -H "apikey: YOUR_API_KEY" \
     -d '{
       "task": "Go to hacker news and get the top 5 stories.",
       "device": "desktop",
       "max_steps": 32,
       "enable_recording": true
     }'
{
  "r": {
    "id": "<string>",
    "status": "waiting",
    "output": "<unknown>",
    "credits_used": 123,
    "device": "desktop",
    "live_url": "<string>",
    "recording_url": "<string>",
    "downloads_url": "<string>",
    "created_at": 123,
    "events": [
      {
        "name": "<string>",
        "payload": {},
        "id": "<string>",
        "timestamp": 123
      }
    ]
  }
}

Authorizations

​
apikey
string
header
required

Body

application/json

Request model for submitting a task.

​
task
string | null

The task to run. If null, opens a browser session that waits for actions via the Event endpoint.

​
response_model
Response Model · object

JSON schema describing the desired output structure. If provided, the agent will return structured data matching this schema.

​
url
string<uri> | null

The starting URL for the task. If not provided, the agent will infer it from the task.

​
metadata
Metadata · object

Variables or parameters passed to the agent. Max 16 keys, max 2048 chars per value.

​
files
string[] | null

List of file IDs (from Upload File endpoint) to pass to the agent.

​
agent
enum<string>
default:smooth

The agent to use for the task.

Available options:
smooth,
smooth-lite
​
max_steps
integer
default:32

Maximum number of steps the agent can take.

Required range: 2 <= x <= 128
​
device
enum<string>
default:desktop

Device type for the task.

Available options:
desktop,
mobile,
desktop-lg
​
allowed_urls
string[] | null

List of allowed URL patterns using wildcard syntax (e.g., https://*example.com/*). If not provided, all URLs are allowed.

​
enable_recording
boolean
default:true

Enable video recording of the task execution.

​
profile_id
string | null

Browser profile ID to use. Each profile maintains its own cookies and login credentials.

​
profile_read_only
boolean
default:false

If true, changes made during the task will not be saved to the profile.

​
stealth_mode
boolean
default:false

Run the browser in stealth mode to avoid detection.

​
proxy_server
string | null

Proxy server URL (e.g., http://proxy.example.com:8080 or socks5://proxy.example.com:1080). Use self to route through your own IP.

​
proxy_username
string | null

Proxy server username for authentication.

​
proxy_password
string | null

Proxy server password for authentication.

​
certificates
Certificate · object[] | null

List of client certificates for accessing secure websites.

​
use_adblock
boolean | null
default:true

Enable ad-blocking in the browser.

​
additional_tools
Additional Tools · object

Additional built-in tools to enable. Supported: screenshot, hover, print_page. Use null for default config.

​
custom_tools
ToolSignature · object[] | null

Custom tool definitions that the agent can call during execution.

​
experimental_features
Experimental Features · object

Experimental features to enable.

​
extensions
string[] | null

List of extension IDs (from Upload Extension endpoint) to load in the browser.

​
show_cursor
boolean
default:false

Show mouse cursor in the browser.

Response

Task successfully submitted. The initial response will have a status of 'waiting'.

​
r
TaskResponse · object
required

Response model for task operations.