> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.airtop.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.airtop.ai/_mcp/server.

# Fill a form synchronously using a form-filler automation

POST https://api.airtop.ai/api/v1/sessions/{sessionId}/windows/{windowId}/fill-form
Content-Type: application/json

Fill a form of a browser window synchronously using a form-filler automation

Reference: https://docs.airtop.ai/api-reference/airtop-api/windows/fill-form

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `sessionId` (string, required) — The session id for the window.
- `windowId` (string, required) — The Airtop window id of the browser window.

### Body (application/json)

This endpoint expects an object.

- `automationId` (string, required) — The ID of the automation to execute
- `async` (AsyncConfig, optional) — Async configuration options.
- `clientRequestId` (string, optional)
- `costThresholdCredits` (long, optional) — 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).
- `parameters` (map from string to any, optional) — Optional parameters to pass to the automation execution
- `timeThresholdSeconds` (long, optional) — 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.

## Response

### 201

Created

- `data` (AiResponseEnvelope, required)
- `meta` (ExternalSessionAiResponseMetadata, required)
- `errors` (list of Issue, optional)
- `warnings` (list of Issue, optional)

## Types

### AsyncConfig

- `webhookUrl` (string, optional) — The URL to send the response to when the request is complete.

### AiResponseEnvelope

- `modelResponse` (string, required)

### ExternalSessionAiResponseMetadata

- `status` (enum, required) — Outcome of the operation.
  - Allowed values: `success`, `partial`, `failure`
- `usage` (ExternalSessionAiResponseMetadataUsage, required)
- `clientProvided` (ClientProvidedResponseMetadata, optional)
- `requestId` (string, optional)
- `screenshots` (list of ScreenshotMetadata, optional) — Array containing any requested screenshots from the operation.

### Issue

- `message` (string, required) — Message describing the issue.
- `code` (string, optional) — Issue code.
- `details` (map from string to any, optional) — Any associated details.
- `reason` (string, optional) — Underlying reason for the issue.

### ExternalSessionAiResponseMetadataUsage

- `credits` (long, required) — The credit usage for this request
- `id` (string, required) — The id of the request

### ClientProvidedResponseMetadata

- `clientRequestId` (string, optional)

### ScreenshotMetadata

- `dataUrl` (string, optional) — Base64 encoded data URL of screenshot image data
- `fileId` (string, optional) — Unique identifier for the uploaded file
- `fileName` (string, optional) — Name of the screenshot file
- `format` (enum, optional) — Format of the screenshot data
  - Allowed values: `base64`, `url`
- `scrollPosition` (ScreenshotScrollPosition, optional) — Scroll position where the screenshot was taken
- `signedDownloadUrl` (string, optional) — Signed URL for downloading the screenshot (when format is 'url')
- `urlExpiry` (string, optional) — Expiration time for the signed URL in ISO format
- `viewportDimensions` (ScreenshotViewportDimensions, optional) — Viewport dimensions of the screenshot

### ScreenshotScrollPosition

- `left` (long, required) — Horizontal scroll position in pixels
- `top` (long, required) — Vertical scroll position in pixels

### ScreenshotViewportDimensions

- `height` (long, required) — Height of the viewport in pixels
- `width` (long, required) — Width of the viewport in pixels

## Examples

**Request**

```json
{
  "automationId": "automationId"
}
```

**Response**

```json
{
  "data": {
    "modelResponse": "modelResponse"
  },
  "meta": {
    "status": "success",
    "usage": {
      "credits": 1000000,
      "id": "id"
    },
    "clientProvided": {
      "clientRequestId": "clientRequestId"
    },
    "requestId": "requestId",
    "screenshots": [
      {}
    ]
  },
  "errors": [
    {
      "message": "message",
      "code": "code",
      "details": {
        "key": "value"
      },
      "reason": "reason"
    }
  ],
  "warnings": [
    {
      "message": "message",
      "code": "code",
      "details": {
        "key": "value"
      },
      "reason": "reason"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.airtop.ai/api/v1/sessions/6aac6f73-bd89-4a76-ab32-5a6c422e8b0b/windows/0334da2a-91b0-42c5-6156-76a5eba87430/fill-form"

payload = { "automationId": "automationId" }
headers = {
    "Authorization": "Bearer <apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```typescript
import { AirtopClient } from "@airtop/sdk";

const client = new AirtopClient({ apiKey: "YOUR_API_KEY" });
await client.windows.fillForm("6aac6f73-bd89-4a76-ab32-5a6c422e8b0b", "0334da2a-91b0-42c5-6156-76a5eba87430", {
    automationId: "automationId"
});

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.airtop.ai/api/v1/sessions/6aac6f73-bd89-4a76-ab32-5a6c422e8b0b/windows/0334da2a-91b0-42c5-6156-76a5eba87430/fill-form"

	payload := strings.NewReader("{\n  \"automationId\": \"automationId\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.airtop.ai/api/v1/sessions/6aac6f73-bd89-4a76-ab32-5a6c422e8b0b/windows/0334da2a-91b0-42c5-6156-76a5eba87430/fill-form")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"automationId\": \"automationId\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.airtop.ai/api/v1/sessions/6aac6f73-bd89-4a76-ab32-5a6c422e8b0b/windows/0334da2a-91b0-42c5-6156-76a5eba87430/fill-form")
  .header("Authorization", "Bearer <apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"automationId\": \"automationId\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.airtop.ai/api/v1/sessions/6aac6f73-bd89-4a76-ab32-5a6c422e8b0b/windows/0334da2a-91b0-42c5-6156-76a5eba87430/fill-form', [
  'body' => '{
  "automationId": "automationId"
}',
  'headers' => [
    'Authorization' => 'Bearer <apiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.airtop.ai/api/v1/sessions/6aac6f73-bd89-4a76-ab32-5a6c422e8b0b/windows/0334da2a-91b0-42c5-6156-76a5eba87430/fill-form");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"automationId\": \"automationId\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["automationId": "automationId"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.airtop.ai/api/v1/sessions/6aac6f73-bd89-4a76-ab32-5a6c422e8b0b/windows/0334da2a-91b0-42c5-6156-76a5eba87430/fill-form")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```