> ## 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.

# Submit Task

> Submits a task to be executed by the Smooth agent. If `task` is `null`, opens a browser session that waits for actions via the Event endpoint.



## OpenAPI

````yaml /api-reference/openapi.json post /task
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:
  /task:
    post:
      tags:
        - Task
      summary: Submit Task
      description: >-
        Submits a task to be executed by the Smooth agent. If `task` is `null`,
        opens a browser session that waits for actions via the Event endpoint.
      operationId: submit_task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskRequest'
            examples:
              simple_task:
                summary: Simple task
                value:
                  task: Go to hacker news and get the top 5 stories.
                  device: desktop
                  max_steps: 32
              session_mode:
                summary: Open session (task=null)
                description: >-
                  Opens a browser session that waits for actions via the Event
                  endpoint
                value:
                  task: null
                  url: https://example.com
                  device: desktop
      responses:
        '200':
          description: >-
            Task successfully submitted. The initial response will have a status
            of 'waiting'.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_TaskResponse'
        '400':
          description: Invalid Request
        '403':
          description: >-
            Access to a premium feature was requested, but it is not available
            on the current plan.
        '422':
          description: Validation Error
        '429':
          description: API credits exhausted or concurrent session limit reached.
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            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
                 }'
        - lang: python
          label: Python (sync)
          source: |-
            from smooth import SmoothClient

            client = SmoothClient(api_key="YOUR_API_KEY")

            task_handle = client.run(
                task="Go to hacker news and get the top 5 stories.",
                device="desktop",
                max_steps=32
            )

            print(f"Task ID: {task_handle.id()}")
            print(f"Live URL: {task_handle.live_url()}")

            # Wait for the result
            result = task_handle.result()
            print(f"Output: {result.output}")
        - lang: python
          label: Python (async)
          source: |-
            import asyncio
            from smooth import SmoothAsyncClient

            async def run_task():
                async with SmoothAsyncClient(api_key="YOUR_API_KEY") as client:
                    task_handle = await client.run(
                        task="Go to hacker news and get the top 5 stories.",
                        device="desktop",
                        max_steps=32
                    )
                    print(f"Task ID: {task_handle.id()}")
                    
                    result = await task_handle.result()
                    print(f"Output: {result.output}")

            asyncio.run(run_task())
        - lang: javascript
          label: JavaScript
          source: |-
            const apiKey = 'YOUR_API_KEY';
            const url = 'https://api.smooth.sh/api/v1/task';

            const payload = {
              task: 'Go to hacker news and get the top 5 stories.',
              device: 'desktop',
              max_steps: 32,
              enable_recording: true
            };

            async function runTask() {
              const response = await fetch(url, {
                method: 'POST',
                headers: {
                  'Content-Type': 'application/json',
                  'apikey': apiKey
                },
                body: JSON.stringify(payload)
              });

              const data = await response.json();
              console.log('Task ID:', data.r.id);
              // Poll GET /task/{id} for results
            }

            runTask();
components:
  schemas:
    TaskRequest:
      type: object
      properties:
        task:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The task to run. If `null`, opens a browser session that waits for
            actions via the Event endpoint.
          title: Task
        response_model:
          anyOf:
            - type: object
            - type: 'null'
          description: >-
            JSON schema describing the desired output structure. If provided,
            the agent will return structured data matching this schema.
          title: Response Model
        url:
          anyOf:
            - type: string
              format: uri
            - type: 'null'
          description: >-
            The starting URL for the task. If not provided, the agent will infer
            it from the task.
          title: URL
        metadata:
          anyOf:
            - type: object
              additionalProperties:
                anyOf:
                  - type: string
                  - type: number
                  - type: boolean
            - type: 'null'
          description: >-
            Variables or parameters passed to the agent. Max 16 keys, max 2048
            chars per value.
          title: Metadata
        files:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          description: List of file IDs (from Upload File endpoint) to pass to the agent.
          title: Files
        agent:
          type: string
          enum:
            - smooth
            - smooth-lite
          description: The agent to use for the task.
          default: smooth
          title: Agent
        max_steps:
          type: integer
          minimum: 2
          maximum: 128
          description: Maximum number of steps the agent can take.
          default: 32
          title: Max Steps
        device:
          type: string
          enum:
            - desktop
            - mobile
            - desktop-lg
          description: Device type for the task.
          default: desktop
          title: Device
        allowed_urls:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          description: >-
            List of allowed URL patterns using glob syntax on the domain and
            path. If not provided, all URLs are allowed. To match everything on
            example.com, use `https://**.example.com/**`.
          title: Allowed URLs
        enable_recording:
          type: boolean
          description: Enable video recording of the task execution.
          default: true
          title: Enable Recording
        profile_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Browser profile ID to use. Each profile maintains its own cookies
            and login credentials.
          title: Profile ID
        profile_read_only:
          type: boolean
          description: >-
            If true, changes made during the task will not be saved to the
            profile.
          default: false
          title: Profile Read Only
        stealth_mode:
          type: boolean
          description: Run the browser in stealth mode to avoid detection.
          default: false
          title: Stealth Mode
        proxy_server:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Proxy server URL (e.g., `http://proxy.example.com:8080` or
            `socks5://proxy.example.com:1080`). Use `self` to route through your
            own IP.
          title: Proxy Server
        proxy_username:
          anyOf:
            - type: string
            - type: 'null'
          description: Proxy server username for authentication.
          title: Proxy Username
        proxy_password:
          anyOf:
            - type: string
            - type: 'null'
          description: Proxy server password for authentication.
          title: Proxy Password
        certificates:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/Certificate'
            - type: 'null'
          description: List of client certificates for accessing secure websites.
          title: Certificates
        use_adblock:
          anyOf:
            - type: boolean
            - type: 'null'
          description: Enable ad-blocking in the browser.
          default: true
          title: Use Adblock
        additional_tools:
          anyOf:
            - type: object
              additionalProperties:
                anyOf:
                  - type: object
                  - type: 'null'
            - type: 'null'
          description: >-
            Additional built-in tools to enable. Supported: `screenshot`,
            `hover`, `print_page`. Use `null` for default config.
          title: Additional Tools
        custom_tools:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/ToolSignature'
            - type: 'null'
          description: Custom tool definitions that the agent can call during execution.
          title: Custom Tools
        experimental_features:
          anyOf:
            - type: object
            - type: 'null'
          description: Experimental features to enable.
          title: Experimental Features
        extensions:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          description: >-
            List of extension IDs (from Upload Extension endpoint) to load in
            the browser.
          title: Extensions
        show_cursor:
          type: boolean
          description: Show mouse cursor in the browser.
          default: false
          title: Show Cursor
      title: TaskRequest
      description: Request model for submitting a task.
    ApiResponse_TaskResponse:
      type: object
      properties:
        r:
          $ref: '#/components/schemas/TaskResponse'
      required:
        - r
    Certificate:
      type: object
      properties:
        file:
          type: string
          description: Base64-encoded p12 certificate file.
          title: File
        password:
          anyOf:
            - type: string
            - type: 'null'
          description: Password for the certificate file.
          title: Password
      required:
        - file
      title: Certificate
      description: Client certificate for secure websites.
    ToolSignature:
      type: object
      properties:
        name:
          type: string
          description: The name of the tool.
          title: Name
        description:
          type: string
          description: A description of what the tool does and when to use it.
          title: Description
        inputs:
          type: object
          description: JSON schema describing the tool's input parameters.
          title: Inputs
        output:
          type: string
          description: Description of the tool's output type.
          title: Output
      required:
        - name
        - description
        - inputs
        - output
      title: ToolSignature
      description: Custom tool definition.
    TaskResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique ID of the task.
          title: ID
        status:
          type: string
          enum:
            - waiting
            - running
            - done
            - failed
            - cancelled
          description: The current status of the task.
          title: Status
        output:
          anyOf:
            - {}
            - type: 'null'
          description: >-
            The output of the task. If `response_model` was provided, this
            matches the specified schema.
          title: Output
        credits_used:
          anyOf:
            - type: integer
            - type: 'null'
          description: Number of credits used. 1 credit = $0.01.
          title: Credits Used
        device:
          anyOf:
            - type: string
              enum:
                - desktop
                - mobile
                - desktop-lg
            - type: 'null'
          description: The device type used for the task.
          title: Device
        live_url:
          anyOf:
            - type: string
            - type: 'null'
          description: URL to view the task execution in real-time.
          title: Live URL
        recording_url:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            URL to download the video recording (available after task
            completes).
          title: Recording URL
        downloads_url:
          anyOf:
            - type: string
            - type: 'null'
          description: URL to download files created during the task.
          title: Downloads URL
        created_at:
          anyOf:
            - type: integer
            - type: 'null'
          description: Unix timestamp when the task was created.
          title: Created At
        events:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/TaskEvent'
            - type: 'null'
          description: >-
            List of new events fired since last poll (when using `event_t`
            parameter).
          title: Events
      required:
        - id
        - status
      title: TaskResponse
      description: Response model for task operations.
    TaskEvent:
      type: object
      properties:
        name:
          type: string
          description: 'Event type: `browser_action`, `session_action`, or `tool_call`.'
          title: Name
        payload:
          type: object
          description: >-
            Event payload. For actions: `{name, input}`. For tool responses:
            `{code, output}`.
          title: Payload
        id:
          anyOf:
            - type: string
            - type: 'null'
          description: Unique event ID. Used to match responses to requests.
          title: ID
        timestamp:
          anyOf:
            - type: integer
            - type: 'null'
          description: Unix timestamp of the event.
          title: Timestamp
      required:
        - name
        - payload
      title: TaskEvent
      description: Event model for sending actions to running tasks.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: apikey

````