> ## 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. # Upload File > Upload a file to be used by tasks. Files can be passed to tasks via the `files` parameter. ## OpenAPI ````yaml /api-reference/openapi.json post /file 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: /file: post: tags: - File summary: Upload File description: >- Upload a file to be used by tasks. Files can be passed to tasks via the `files` parameter. operationId: upload_file requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: The file to upload. file_purpose: type: string description: >- Optional description of the file's purpose (max 64 characters). required: - file responses: '200': description: File successfully uploaded. content: application/json: schema: $ref: '#/components/schemas/ApiResponse_UploadFileResponse' '400': description: Invalid file or filename. x-codeSamples: - lang: curl label: cURL source: |- curl -X POST "https://api.smooth.sh/api/v1/file" \ -H "apikey: YOUR_API_KEY" \ -F "file=@/path/to/your/file.pdf" \ -F "file_purpose=invoice document" - lang: python label: Python source: |- from smooth import SmoothClient client = SmoothClient(api_key="YOUR_API_KEY") with open("/path/to/your/file.pdf", "rb") as f: response = client.upload_file(f, purpose="invoice document") print(f"File ID: {response.id}") # Use the file in a task task = client.run( task="Process this invoice", files=[response.id] ) components: schemas: ApiResponse_UploadFileResponse: type: object properties: r: $ref: '#/components/schemas/UploadFileResponse' required: - r UploadFileResponse: type: object properties: id: type: string description: The ID assigned to the uploaded file. title: ID required: - id title: UploadFileResponse description: Response model for file upload. securitySchemes: APIKeyHeader: type: apiKey in: header name: apikey ````