API Overview

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

Endpoint	Method	Description
`/task`	POST	Submit a task or create a session (`task=null`)
`/task`	GET	List all tasks
`/task/{id}`	GET	Get task status and results
`/task/{id}`	DELETE	Cancel a running task
`/task/{id}/event`	POST	Send an event to a running task/session

Session Actions

When using sessions, send actions via POST /task/{id}/event:

Action	Event Type	Description
Navigate	`browser_action`	Go to a URL
Extract	`browser_action`	Extract structured data from the page
JavaScript	`browser_action`	Execute JavaScript in the browser
Run Task	`session_action`	Run an AI-powered task within the session
Close	`session_action`	Close 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

Status	Description
`waiting`	Task is queued
`running`	Task is executing
`done`	Task completed successfully
`failed`	Task failed
`cancelled`	Task was cancelled

Error Handling

HTTP Code	Meaning
400	Invalid request parameters
403	Premium feature not available on your plan
404	Resource not found
422	Validation error
429	Rate 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

Getting Started

Guides

Endpoints

Quick Start

Get your free API key

Authentication

Two Ways to Use the API

1. Simple Tasks

2. Session Workflows

Session Workflow

Polling Mechanism

Core Endpoints

Session Actions

Session Actions Reference

Custom Tools

Custom Tools Guide

Additional Features

Browser Profiles

Structured Output

File Uploads

Response Format

Task Status Values

Error Handling

Next Steps

Session Workflow

Custom Tools

Polling Guide

Python SDK

​Quick Start

Get your free API key

​Authentication

​Two Ways to Use the API

​1. Simple Tasks

​2. Session Workflows

Session Workflow

Polling Mechanism

​Core Endpoints

​Session Actions

Session Actions Reference

​Custom Tools

Custom Tools Guide

​Additional Features

​Browser Profiles

​Structured Output

​File Uploads

​Response Format

​Task Status Values

​Error Handling

​Next Steps

Session Workflow

Custom Tools

Polling Guide

Python SDK

Quick Start

Authentication

Two Ways to Use the API

1. Simple Tasks

2. Session Workflows

Core Endpoints

Session Actions

Custom Tools

Additional Features

Browser Profiles

Structured Output

File Uploads

Response Format

Task Status Values

Error Handling

Next Steps