Cloud-Browser für KI-Agenten

                            1
                            # Floppydata Cloud Browser — reference and operating rules
                        
                            2
                             
                        
                            3
                            You are working with the Floppydata Cloud Browser API. Use only the facts
                        
                            4
                            below: never guess endpoints or fields, and never invent page content —
                        
                            5
                            report only what the browser actually returned.
                        
                            6
                             
                        
                            7
                            ## Step 0 — is there an API key?
                        
                            8
                            Read the key from FLOPPY_API_KEY in the environment. If it is missing, do
                        
                            9
                            not attempt a session and do not ask for the key in chat. Walk the user
                        
                            10
                            through this instead:
                        
                            11
                             
                        
                            12
                              1. Create an account, or sign in to an existing one:
                        
                            13
                                 https://app.floppydata.com/account/signup
                        
                            14
                              2. Open API keys, copy the key that is already there or generate a new
                        
                            15
                                 one: https://app.floppydata.com/api-keys
                        
                            16
                              3. Buy traffic: https://app.floppydata.com/proxies/buy?type=rotating
                        
                            17
                                 Sessions themselves are free, but every page a session loads goes
                        
                            18
                                 out through Floppydata proxies, and proxy traffic is billed per GB.
                        
                            19
                                 With no traffic on the account a session has no network to run on.
                        
                            20
                              4. Put the key in the environment as FLOPPY_API_KEY — not in code, not
                        
                            21
                                 in a chat message — then run the task again.
                        
                            22
                             
                        
                            23
                            ## Step 1 — with a key, start the session straight away
                        
                            24
                            Do not interview the user about settings. Start on these defaults and
                        
                            25
                            change them only when the task actually calls for it.
                        
                            26
                             
                        
                            27
                            POST https://api.floppydata.net/v2/browser/sessions
                        
                            28
                            X-Api-Key: $FLOPPY_API_KEY
                        
                            29
                            {
                        
                            30
                              "proxy": {
                        
                            31
                                "type": "residential",            // residential | mobile | datacenter
                        
                            32
                                "location": { "countryCode": "DE" },
                        
                            33
                                "rotation": { "mode": "sticky" }  // one IP for the whole session
                        
                            34
                              },
                        
                            35
                              "browser": { "fingerprint": { "strategy": "auto", "os": "windows" } },
                        
                            36
                              "runtime": { "timeoutSeconds": 1800, "keepAlive": true }
                        
                            37
                            }
                        
                            38
                             
                        
                            39
                            Every field is optional: {} also works — residential proxy, sticky
                        
                            40
                            rotation, 600 second timeout.
                        
                            41
                             
                        
                            42
                            201 Created returns:
                        
                            43
                              id           session id
                        
                            44
                              status       running | stopped | timedOut | failed
                        
                            45
                              connectUrl   signed wss:// CDP endpoint — treat it like a password
                        
                            46
                              settings.id  reuse it to restore this identity and cookie jar
                        
                            47
                              expiresAt    when the session ends on its own
                        
                            48
                             
                        
                            49
                            A 401 means the key is wrong or revoked: back to Step 0. If the call is
                        
                            50
                            refused because the account has no traffic left, send the user to the buy
                        
                            51
                            page above rather than retrying.
                        
                            52
                             
                        
                            53
                            ## Step 2 — drive the page
                        
                            54
                            Connect over CDP and work in the tab that is already open:
                        
                            55
                             
                        
                            56
                              const browser = await chromium.connectOverCDP(connectUrl);
                        
                            57
                              const page = browser.contexts()[0].pages()[0];
                        
                            58
                              await page.goto(url, { waitUntil: "domcontentloaded" });
                        
                            59
                             
                        
                            60
                            One session keeps cookies and page state between steps, so navigate,
                        
                            61
                            fill, click and read inside it instead of starting a session per action.
                        
                            62
                             
                        
                            63
                            ## Step 3 — hand a step to a human
                        
                            64
                            Some checks only a person can clear. Request a live view for the session,
                        
                            65
                            let someone finish that step, then reconnect and carry on:
                        
                            66
                             
                        
                            67
                              POST /v2/browser/sessions/{id}/live-view  -> { liveViewUrl }
                        
                            68
                              GET  /v2/browser/sessions/{id}            -> fresh connectUrl
                        
                            69
                             
                        
                            70
                            ## Step 4 — reuse the identity on the next run
                        
                            71
                            Send back the settings id you were given:
                        
                            72
                             
                        
                            73
                              { "settings": { "id": "<settings-id>" } }
                        
                            74
                             
                        
                            75
                            ## Step 5 — stop when the task is done
                        
                            76
                            POST https://api.floppydata.net/v2/browser/sessions/{id}/stop
                        
                            77
                             
                        
                            78
                            ## Rules
                        
                            79
                            - Report values you actually read; if a selector is missing, say so.
                        
                            80
                            - Never print the API key, connectUrl or liveViewUrl in your output.
                        
                            81
                            - Keep one session per task; do not open a new one for every step.
                        
                            82
                            - Ask before spending traffic on pages the task does not need.