fix(openapi): add prompt parameter and response fields to interact endpoint#754
fix(openapi): add prompt parameter and response fields to interact endpoint#754firecrawl-spring[bot] wants to merge 1 commit intomainfrom
Conversation
…dpoint
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>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
| "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", |
There was a problem hiding this comment.
🟡 OpenAPI schema allows requests with neither prompt nor code
The old schema had "required": ["code"], enforcing that code must be provided. The new schema removes this required constraint without adding an equivalent oneOf/anyOf to enforce that at least one of prompt or code is present. The field descriptions state "Required if code is not set" and "Required if prompt is not set", but the schema itself permits a request body with neither field, which would be invalid per the documented intent. Tools and clients that generate code or validation from this OpenAPI spec will not enforce the mutual-requirement constraint.
(Refers to lines 162-192)
Prompt for agents
In api-reference/v2-openapi.json, around line 161-192 in the request body schema for the /scrape/{jobId}/interact endpoint, the old `required: ["code"]` was removed but no replacement constraint was added. The descriptions on `prompt` and `code` say one is required if the other is not set, but the schema doesn't enforce this.
To fix this in OpenAPI 3.0, add a `oneOf` (or `anyOf`) at the schema level that requires at least one of the two fields. For example:
"schema": {
"type": "object",
"anyOf": [
{ "required": ["prompt"] },
{ "required": ["code"] }
],
"properties": { ... }
}
This ensures code-generated clients and validators correctly reject requests missing both fields.
Was this helpful? React with 👍 or 👎 to provide feedback.
|
@devhims review comment looks actionable |
Summary
POST /v2/scrape/{scrapeId}/interactwas missing thepromptrequest parameter and markedcodeas required, making it appear that only code execution mode was supportedpromptparameter, removed therequired: ["code"]constraint, and addedoutput,liveViewUrl,interactiveLiveViewUrlto the response schemafeatures/interact.mdxwhich already correctly documents both modesWhat changed
api-reference/v2-openapi.json— interact endpoint (POST /scrape/{jobId}/interact):Request body:
"required": ["code"](eitherpromptorcodeis needed, not justcode)promptstring parameter (max 10,000 chars) for natural language AI agent tasksResponse (200):
output— the agent's natural language answer (prompt mode only)liveViewUrl— read-only live view URL for the browser sessioninteractiveLiveViewUrl— interactive live view URLresultdescription to cover both prompt and code modesRelated Pylon Ticket
https://app.usepylon.com/issues?issueNumber=23922
Test plan
promptparametercode)output,liveViewUrl,interactiveLiveViewUrl