---
title: "File Input"
method: POST
path: "/v1/sessions/{sessionId}/windows/{windowId}/file-input"
tags: ["windows"]
---

# File Input

`POST /v1/sessions/{sessionId}/windows/{windowId}/file-input`

Execute a file input interaction in a specific browser window.
		includeHiddenElements defaults to true and considers hidden file input elements.
		If there is only one file input element, it will be used directly.
		If there are multiple file input elements, the elementDescription will be used by AI to
		select among them.
		If no file input elements are found by inspecting the page structure, elementDescription
		will be used by AI to try to find a match visually.

## Path parameters

- `sessionId` string, required
- `windowId` string, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `clientRequestId` string
  - `configuration` TypeMicroInteractionConfigWithExperimental
    - `experimental` TypeMicroInteractionExperimentalConfig
      - `scrollWithin` string — A natural language description of the scrollable area on the web page. This identifies the container or region that should be scrolled. If missing, the entire page will be scrolled. You can also describe a visible reference point inside the container. Note: This is different from elementDescription, which specifies the target element to interact with. The target may be located inside the scrollable area defined by scrollWithin.
    - `visualAnalysis` TypeVisualAnalysisConfig
      - `maxScanScrolls` integer — Scan mode only: The maximum number of scrolls to perform. Defaults to 50.
      - `overlapPercentage` integer — The percentage of overlap between screenshot chunks. Defaults to 30 (percent).
      - `partitionDirection` 'vertical' | 'horizontal' | 'bidirectional' — The direction to partition the screenshot into chunks: 'vertical', 'horizontal', or 'bidirectional'. Defaults to 'vertical', which is recommended for most web pages. For optimal results when partitioning in a single direction, ensure the perpendicular dimension does not exceed 1920 pixels.
      - `resultSelectionStrategy` 'first' | 'bestMatch' | 'auto' — [Experimental] The strategy to use for selecting the match using visual analysis. Can be 'auto', 'first' or 'bestMatch'. Defaults to 'auto'. Use 'auto' to let the system decide the best strategy. Use 'first' to select the first visual element that matches the element description. This will favor results that appear higher on the page in the event of multiple matches. Use 'bestMatch' to analyze the complete page and apply judgement to select the best candidate from all potential matches.
      - `scanScrollDelay` integer — Scan mode only: The delay between scrolls in milliseconds. Defaults to 1000 (milliseconds).
      - `scope` 'viewport' | 'page' | 'scan' | 'auto' — Whether to analyze the current viewport or the whole page. Can be 'viewport', 'page', 'scan' or 'auto'. Defaults to 'auto', which provides the simplest out-of-the-box experience for most web pages. Use 'viewport' for analysis of the current browser view only. Use 'page' for a full page analysis. Use 'scan' for a full page analysis on sites that have compatibility or accuracy issues with 'page' mode.
    - `waitForNavigationConfig` TypeBrowserWaitNavigationConfig
      - `timeoutSeconds` integer — The maximum time to wait for the navigation to complete, in seconds. Defaults to 30 (30 seconds).
      - `waitUntil` 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2' — The condition to wait for the navigation to complete. Defaults to 'load'.
  - `costThresholdCredits` integer — A credit threshold that, once exceeded, will cause the operation to be cancelled. Note that this is *not* a hard limit, but a threshold that is checked periodically during the course of fulfilling the request. A default threshold is used if not specified, but you can use this option to increase or decrease as needed. Set to 0 to disable this feature entirely (not recommended).
  - `elementDescription` string — A natural language description of the file input to interact with (e.g. 'the file input', 'file upload selection box'). The interaction will be aborted if the target element cannot be found.
  - `fileId` string, uuid — The id of the file to upload. 'fileId' or 'fileName' is required.
  - `fileName` string — The name of the file to upload, not including the path. 'fileId' or 'fileName' is required.
  - `includeHiddenElements` boolean — If true, Airtop AI will find hidden file input elements and interact with them.
  - `timeThresholdSeconds` integer — A time threshold in seconds that, once exceeded, will cause the operation to be cancelled. Note that this is *not* a hard limit, but a threshold that is checked periodically during the course of fulfilling the request. A default threshold is used if not specified, but you can use this option to increase or decrease as needed. Set to 0 to disable this feature entirely (not recommended). This setting does not extend the maximum session duration provided at the time of session creation.
  - `waitForNavigation` boolean — If true, Airtop AI will wait for the navigation to complete after clicking the element.

## Response `201`

Created

- TypeAiPromptResponse
  - `data` TypeAiResponseEnvelope, required
    - `modelResponse` string, required
  - `errors` TypeIssue[]
    - `code` string — Issue code.
    - `details` object — Any associated details.
    - `message` string, required — Message describing the issue.
    - `reason` string — Underlying reason for the issue.
  - `meta` TypeExternalSessionAiResponseMetadata, required
    - `clientProvided` TypeClientProvidedResponseMetadata
      - `clientRequestId` string
    - `requestId` string
    - `screenshots` TypeScreenshotMetadata[] — Array containing any requested screenshots from the operation.
      - `dataUrl` string — Base64 encoded data URL of screenshot image data
      - `fileId` string — Unique identifier for the uploaded file
      - `fileName` string — Name of the screenshot file
      - `format` 'base64' | 'url' — Format of the screenshot data
      - `scrollPosition` TypeScreenshotScrollPosition
        - `left` integer, required — Horizontal scroll position in pixels
        - `top` integer, required — Vertical scroll position in pixels
      - `signedDownloadUrl` string — Signed URL for downloading the screenshot (when format is 'url')
      - `urlExpiry` string — Expiration time for the signed URL in ISO format
      - `viewportDimensions` TypeScreenshotViewportDimensions
        - `height` integer, required — Height of the viewport in pixels
        - `width` integer, required — Width of the viewport in pixels
    - `status` 'success' | 'partial' | 'failure', required — Outcome of the operation.
    - `usage` TypeExternalSessionAiResponseMetadataUsage, required
      - `credits` integer, required — The credit usage for this request
      - `id` string, required — The id of the request
  - `warnings` TypeIssue[]
    - `code` string — Issue code.
    - `details` object — Any associated details.
    - `message` string, required — Message describing the issue.
    - `reason` string — Underlying reason for the issue.

---

[API](https://skmtc.net/airtop/apis/airtop-api.md) · [All operations](https://skmtc.net/airtop/apis/airtop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/airtop/airtop-api/versions/77d6e0f03453/schema)