docs: document keyless feedback in the v2 API reference

api-reference/endpoint/feedback.mdx

@@ -1,14 +1,16 @@
 ---
-title: 'Endpoint Feedback'
-description: 'Submit feedback for a completed v2 endpoint job.'
+title: 'Feedback'
+description: 'Submit feedback for a Firecrawl job.'
 openapi: '/api-reference/v2-openapi.json POST /feedback'
 ---
 
-Use endpoint feedback to tell Firecrawl whether a completed job result was useful, partial, or bad. This is for endpoint-level output quality on jobs such as `scrape`, `parse`, `map`, and `search`.
+Submit feedback on the quality of a job's output, including useful results, missing content, or incorrect data.
 
-The generic feedback schema can carry search-style fields too, but [Search Feedback](/api-reference/endpoint/search-feedback) is the preferred search-specific entry point because it is scoped to a search job ID and highlights valuable sources, missing content, query suggestions, and refund behavior.
+For jobs created with an API key, include your key and use the Authenticated request format. For keyless jobs, omit `Authorization` and use the Search, Scrape, or Parse request format.
 
-### Example Request
+For authenticated Search jobs, [Search Feedback](/api-reference/endpoint/search-feedback) remains the preferred search-specific entry point for valuable sources, missing content, query suggestions, and refund behavior.
+
+### Authenticated example
 
 ```bash
 curl -X POST "https://api.firecrawl.dev/v2/feedback" \
@@ -23,3 +25,59 @@ curl -X POST "https://api.firecrawl.dev/v2/feedback" \
     "url": "https://example.com/pricing"
   }'
 ```
+
+### Keyless example
+
+```bash
+curl -X POST "https://api.firecrawl.dev/v2/feedback" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "endpoint": "search",
+    "jobId": "550e8400-e29b-41d4-a716-446655440000",
+    "rating": "good",
+    "task": "Find the documented retry behavior",
+    "assessment": "The API reference answered the retry question.",
+    "observations": [
+      {
+        "kind": "useful",
+        "source": "web",
+        "position": 1,
+        "detail": "The reference specifies the retry intervals.",
+        "basis": "output"
+      }
+    ]
+  }'
+```
+
+### Keyless feedback
+
+Feedback is optional and does not affect continued keyless access or consume operation allowance. It remains available after the operation allowance is exhausted. The API invitation says:
+
+> Consider submitting feedback to POST /v2/feedback, especially if this result is wrong, incomplete, blocked, or an error. Include specific evidence to help improve Firecrawl.
+
+Use evidence already available from the task; no extra investigation or user interview is required.
+
+Eligible keyless Search, Scrape, and Parse responses include a job ID and a feedback invitation. Search returns them in `metadata`; successful Scrape and Parse calls return them in `data.metadata`. Failed jobs return them in `metadata`. The invitation includes `jobId`, `endpoint`, and `expiresAt`. Submit from the same IP address used for the job before the invitation's `expiresAt` deadline, which provides a 24-hour feedback window for the job. Each job accepts one submission; retrying returns the original feedback ID. If you receive a `429`, wait for `retry_after_seconds` before retrying.
+
+Keyless requests require `endpoint`, `jobId`, `rating` (`good`, `partial`, or `bad`), `task`, `assessment`, and 1-20 `observations`. Each observation requires `kind`, `detail`, and `basis` (`output`, `source_comparison`, or `expectation`). Source comparisons also require `comparison: {reference, detail}`, describing the correct content from a source already inspected. Parse additionally requires `docClass`: `born_digital`, `scanned`, `mixed`, or `unknown`.
+
+`task`, `assessment`, and each `detail` must contain 10-2000 characters after trimming leading and trailing whitespace. For Scrape and Parse observations other than failures, `format` must name a requested format. Include it when multiple formats were requested and the basis is `output` or `source_comparison`.
+
+Keep observations concise and avoid copying full results. Stored feedback must fit within 8 KiB (8192 UTF-8 bytes), including server defaults and verification flags. The [OpenAPI schema](/api-reference/v2-openapi.json) lists each endpoint's observation kinds and reason codes.
+
+Keyless Parse feedback does not automatically retain the document, extracted output, page images, or layout blocks. Submitted observations and corrections are retained.
+
+For Search, `position` starts at 1 within the returned `web`, `images`, or `news` results. Set `source` for `images`, `news`, or a search with multiple sources; otherwise it defaults to `web`. Report positions that appear in the response.
+
+If a failed response includes a feedback invitation, use the reported error in a `failure` observation:
+
+```json
+{
+  "kind": "failure",
+  "reason": "timeout",
+  "basis": "output",
+  "detail": "The operation returned a timeout before producing a result."
+}
+```
+
+For failures, omit result-specific fields such as `position`, `format`, or `page`. Parse still requires `docClass`, which may be `unknown`. Requests rejected before execution, such as invalid input or exhausted operation quota, have no feedback job.

api-reference/endpoint/parse.mdx

@@ -22,3 +22,5 @@ Use `/parse` when the source document is **a local file** or **not publicly acce
 <Tip>
 **Using Firecrawl through MCP?** Use `firecrawl_parse` for local files. Local MCP can read the file directly when configured with `FIRECRAWL_API_URL`. Remote hosted MCP returns a short-lived upload command first, then parses the returned `uploadRef`. Public document URLs should still use `/scrape`.
 </Tip>
+
+Keyless responses may include an invitation to submit [feedback](/api-reference/endpoint/feedback) about the result.

api-reference/endpoint/scrape.mdx

@@ -16,3 +16,5 @@ See the [Interact documentation](/features/interact) for full details and exampl
 Optionally you can also use the `actions` parameter, although it's not recommended to use it for complex interactions.
 
 > Are you an AI agent that needs a Firecrawl API key? See [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) for automated onboarding instructions.
+
+Keyless responses may include an invitation to submit [feedback](/api-reference/endpoint/feedback) about the result.

api-reference/endpoint/search.mdx

@@ -124,3 +124,5 @@ Each result includes a `category` field indicating its source:
 Use the `tbs` parameter to filter results by time periods, including custom date ranges. See the [Search Feature documentation](https://docs.firecrawl.dev/features/search#time-based-search) for detailed examples and supported formats.
 
 > Are you an AI agent that needs a Firecrawl API key? See [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) for automated onboarding instructions.
+
+Keyless responses may include an invitation to submit [feedback](/api-reference/endpoint/feedback) about the result.