From 700f3286c178dc100d9364f96b268302c3006865 Mon Sep 17 00:00:00 2001
From: "firecrawl-spring[bot]"
 <254786068+firecrawl-spring[bot]@users.noreply.github.com>
Date: Wed, 8 Apr 2026 13:22:21 +0000
Subject: [PATCH] fix(openapi): add prompt parameter and response fields to
 interact endpoint

The OpenAPI spec for POST /v2/scrape/{scrapeId}/interact was missing the
prompt parameter and marked code as required, making it appear that only
code execution was supported. This caused SDK-generated clients and
auto-generated API reference pages to hide the prompt-based AI agent
capability.

Changes:
- Remove required: ["code"] constraint (either prompt or code is needed)
- Add prompt request parameter with description and max length
- Add output, liveViewUrl, interactiveLiveViewUrl response fields
- Update result field description to cover both prompt and code modes

Co-Authored-By: micahstairs <micah@sideguide.dev>
---
 api-reference/v2-openapi.json | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/api-reference/v2-openapi.json b/api-reference/v2-openapi.json
index 719a6f0f..89ee21d8 100644
--- a/api-reference/v2-openapi.json
+++ b/api-reference/v2-openapi.json
@@ -159,13 +159,18 @@
             "application/json": {
               "schema": {
                 "type": "object",
-                "required": ["code"],
                 "properties": {
+                  "prompt": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 10000,
+                    "description": "Natural language task for the AI agent. Required if `code` is not set."
+                  },
                   "code": {
                     "type": "string",
                     "minLength": 1,
                     "maxLength": 100000,
-                    "description": "Code to execute in the scrape-bound browser sandbox"
+                    "description": "Code to execute in the scrape-bound browser sandbox. Required if `prompt` is not set."
                   },
                   "language": {
                     "type": "string",
@@ -191,7 +196,7 @@
         },
         "responses": {
           "200": {
-            "description": "Code executed successfully",
+            "description": "Interaction executed successfully",
             "content": {
               "application/json": {
                 "schema": {
@@ -200,6 +205,21 @@
                     "success": {
                       "type": "boolean"
                     },
+                    "output": {
+                      "type": "string",
+                      "nullable": true,
+                      "description": "The agent's natural language answer. Only present when using `prompt`."
+                    },
+                    "liveViewUrl": {
+                      "type": "string",
+                      "nullable": true,
+                      "description": "Read-only live view URL for the browser session"
+                    },
+                    "interactiveLiveViewUrl": {
+                      "type": "string",
+                      "nullable": true,
+                      "description": "Interactive live view URL where viewers can control the browser"
+                    },
                     "stdout": {
                       "type": "string",
                       "nullable": true,
@@ -208,7 +228,7 @@
                     "result": {
                       "type": "string",
                       "nullable": true,
-                      "description": "Standard output (alias for stdout)"
+                      "description": "Raw return value from the sandbox. For `code`: the last expression evaluated. For `prompt`: the raw page snapshot the agent used."
                     },
                     "stderr": {
                       "type": "string",