> ## 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. # Open Browser Session (Deprecated) > **Deprecated**: Use `POST /task` with `task=null` instead, and send actions via `POST /task/{task_id}/event`. Opens an interactive browser instance for 5 minutes. ## OpenAPI ````yaml /api-reference/openapi.json post /browser/session openapi: 3.1.0 info: title: Smooth version: 0.4.1 description: >- # Introduction The Smooth API allows for programmatic browser automation and task execution. You can run simple one-shot tasks, or create interactive browser sessions for multi-step workflows. This documentation provides a guide to using the API directly, as well as through our Python SDK. # Authentication To use the API, you need an API key. The API key must be sent in the `apikey` header with every request. Example: `apikey: YOUR_API_KEY` If you are using the Python SDK, you can provide the API key in two ways: 1. **Directly in the client constructor**: ```python from smooth import SmoothClient client = SmoothClient(api_key="YOUR_API_KEY") ``` 2. **As an environment variable**: Set the `CIRCLEMIND_API_KEY` environment variable, and the client will automatically use it. ```bash export CIRCLEMIND_API_KEY="YOUR_API_KEY" ``` # Python SDK The Smooth Python SDK provides a convenient way to interact with the Smooth API. ## Installation You can install the Smooth Python SDK using pip: ```bash pip install smooth-py ``` ## Features * **Synchronous and Asynchronous Clients**: Choose between `SmoothClient` for traditional sequential programming and `SmoothAsyncClient` for high-performance asynchronous applications. * **Simple Tasks**: Run one-shot browser automation tasks with `client.run()`. * **Session Workflows**: Create browser sessions for multi-step workflows with `client.session()`. * **Custom Tools**: Register Python functions that the agent can call during execution. ## Usage ### Simple Task Run a one-shot task and wait for the result: ```python from smooth import SmoothClient client = SmoothClient(api_key="YOUR_API_KEY") task_handle = client.run( task="Go to https://www.google.com and search for 'Smooth SDK'" ) print(f"Task started with ID: {task_handle.id()}") print(f"Live view: {task_handle.live_url()}") result = task_handle.result() # Blocks until task is done if result.status == 'done': print("Task Output:", result.output) else: print("Task Failed:", result.output) ``` ### Session Workflow For multi-step workflows, create a session and run multiple actions: ```python from smooth import SmoothClient client = SmoothClient(api_key="YOUR_API_KEY") with client.session(url="https://example.com") as session: # Run a task within the session result = session.run_task("Search for flights from NYC to LA") print(f"Task output: {result.output}") # Extract structured data flights = session.extract( schema={"type": "array", "items": {"type": "object", "properties": {"price": {"type": "number"}}}}, prompt="Extract the first 3 flight prices" ) print(f"Flights: {flights.output}") # Navigate to a URL session.goto("https://example.com/checkout") # Execute JavaScript title = session.evaluate_js("document.title") print(f"Page title: {title.output}") ``` ### Asynchronous Client For async applications: ```python import asyncio from smooth import SmoothAsyncClient async def main(): async with SmoothAsyncClient(api_key="YOUR_API_KEY") as client: task_handle = await client.run( task="Go to Github and search for 'smooth-sdk'" ) print(f"Task started with ID: {task_handle.id()}") result = await task_handle.result() print("Task Output:", result.output) asyncio.run(main()) ``` servers: - url: https://api.smooth.sh/api/v1 security: - APIKeyHeader: [] tags: - name: Task description: Operations for running and managing browser automation tasks - name: Event description: >- Operations for sending events to running tasks (session actions, custom tool responses) - name: Profile description: >- Operations for managing browser profiles (persistent cookies and authentication) - name: File description: Operations for uploading and managing files - name: Extension description: Operations for managing browser extensions paths: /browser/session: post: tags: - Profile summary: Open Browser Session (Deprecated) description: >- **Deprecated**: Use `POST /task` with `task=null` instead, and send actions via `POST /task/{task_id}/event`. Opens an interactive browser instance for 5 minutes. operationId: open_browser_session requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BrowserSessionRequest' responses: '200': description: Session opened. content: application/json: schema: $ref: '#/components/schemas/ApiResponse_BrowserSessionResponse' '403': description: Access to premium features is not available on the free plan. deprecated: true x-codeSamples: - lang: python label: Python (Recommended) source: |- # Use the new session() method instead from smooth import SmoothClient client = SmoothClient(api_key="YOUR_API_KEY") with client.session(url="https://example.com") as session: session.run_task("Click the login button") session.close() components: schemas: BrowserSessionRequest: type: object properties: profile_id: anyOf: - type: string - type: 'null' description: >- The profile ID to use. If not provided, a new profile will be created. title: Profile ID live_view: type: boolean description: Request a live URL to interact with the browser. default: true title: Live View device: anyOf: - type: string enum: - desktop - mobile - type: 'null' description: Device type for the browser session. default: desktop title: Device url: anyOf: - type: string format: uri - type: 'null' description: Starting URL to open. title: URL proxy_server: anyOf: - type: string - type: 'null' description: Proxy server address. title: Proxy Server proxy_username: anyOf: - type: string - type: 'null' description: Proxy server username. title: Proxy Username proxy_password: anyOf: - type: string - type: 'null' description: Proxy server password. title: Proxy Password extensions: anyOf: - type: array items: type: string - type: 'null' description: List of extension IDs to load. title: Extensions title: BrowserSessionRequest description: Request model for opening a browser session (deprecated). ApiResponse_BrowserSessionResponse: type: object properties: r: $ref: '#/components/schemas/BrowserSessionResponse' required: - r BrowserSessionResponse: type: object properties: profile_id: type: string description: The ID of the browser profile. title: Profile ID live_id: anyOf: - type: string - type: 'null' description: The ID of the live browser session. title: Live ID live_url: anyOf: - type: string - type: 'null' description: URL to interact with the browser session. title: Live URL required: - profile_id title: BrowserSessionResponse description: Response model for browser session (deprecated). securitySchemes: APIKeyHeader: type: apiKey in: header name: apikey ````