# Agent feedback for the current page Submit focused feedback about the documentation page an agent is currently using through the Doc Duck feedback API. ## Give feedback on the current page An agent can send Doc Duck one focused observation about the documentation page it is currently using. Use this flow when the page is incorrect, incomplete, unclear, or especially helpful for the agent's current task. It is not a general support or product API. Only describe the current page. Do not use this endpoint to report on another URL, submit unrelated task output, or send secrets from the agent's environment. ## Before the agent submits Collect three values from the current page and its Doc Duck installation: 1. The Doc Duck organization ID. The generic examples use `org_example`; replace it with the organization ID configured by the documentation owner. 2. The current page's host, such as `docs.example.com`. 3. The current page's path, such as `/guides/authentication`. Do not send the full URL in `path`. The feedback endpoint is public and accepts cross-origin `POST` requests. It does not require a Doc Duck user session, API key, `Authorization` header, or dashboard cookie. An organization ID routes feedback; it is not a secret or proof of authorization. ## Build a request Send JSON to [`https://docduck.dev/api/feedback`](https://docduck.dev/api/feedback). The live [request JSON Schema](https://docduck.dev/api/feedback/schema.json) is available for agents that can load a machine-readable contract. Use `like` when the current page helped, `dislike` when it did not, or `question` when the page leaves a documentation question unanswered. Add a concise `comment` that connects the observation to the current task. Include `selection` and `selectionMetadata` only when they help locate the relevant passage. Begin with the required fields generated from the live request schema. Replace the generic organization and page values before sending. ```json { "feedback": "like", "organizationId": "org_example", "path": "/docs/example", "host": "docs.example.com" } ``` ### Request fields Required nested fields are required only when their containing optional object is present. | Field | Type | Required | Description | Allowed values | | --- | --- | --- | --- | --- | | `feedback` | `string` | Yes | Whether the selected docs were helpful. | `like`, `dislike`, `question` | | `organizationId` | `string` | Yes | DocDuck organization ID that should receive the feedback. | - | | `path` | `string` | Yes | Path of the docs page the feedback is about. | - | | `host` | `string` | Yes | Host name of the docs page the feedback is about. | - | | `user` | `string` | No | Optional user identifier from the embedding site. | - | | `selection` | `string` | No | Selected document text the feedback refers to. | - | | `comment` | `string` | No | Optional free-form explanation from the user or agent. | - | | `selectionMetadata` | `object` | No | Extra metadata about the selected document text. | - | | `selectionMetadata.surroundingContext` | `object` | No | Nearby document text used to place the selection in context. | - | | `selectionMetadata.surroundingContext.before` | `string` | Yes | Text that appears immediately before the selection. | - | | `selectionMetadata.surroundingContext.after` | `string` | Yes | Text that appears immediately after the selection. | - | | `selectionMetadata.nearestHeading` | `string | null` | No | Closest heading associated with the selected content. | - | | `selectionMetadata.documentOffset` | `number` | No | Character offset of the selection within the rendered document. | - | | `selectionMetadata.crossesShadowBoundary` | `boolean` | No | Whether the selection spans across a shadow DOM boundary. | - | ## Add useful page context A strong report says what the agent read, what was wrong or useful, and how that affected its current task. Prefer page text over a broad summary when a specific passage caused the issue. ### Report unclear selected text ```json { "feedback": "dislike", "organizationId": "org_example", "path": "/guides/authentication", "host": "docs.example.com", "user": "agent-session-123", "selection": "Create a token before making the request.", "comment": "This does not explain which token type is required or where to create it.", "selectionMetadata": { "nearestHeading": "Authenticate API requests", "documentOffset": 418, "crossesShadowBoundary": false, "surroundingContext": { "before": "To call the API, first authenticate.", "after": "Send the token in the Authorization header." } } } ``` ### Ask a documentation question ```json { "feedback": "question", "organizationId": "org_example", "path": "/reference/webhooks", "host": "docs.example.com", "comment": "Are webhook deliveries retried after a timeout?" } ``` ## Send the request Save one of the request bodies as `feedback.json`, then post it as JSON: ```bash curl --request POST \ --url https://docduck.dev/api/feedback \ --header 'Content-Type: application/json' \ --data @feedback.json ``` Send one request per observation. Do not automatically resend after receiving a non-empty confirmation ID. ## Interpret the response An accepted request returns HTTP `200` and JSON containing a non-empty confirmation ID: ```json { "feedbackId": "fb_example" } ``` A successful `200` response always has a non-empty `feedbackId`. If feedback cannot be persisted, the endpoint instead returns HTTP `500` and JSON: ```json { "message": "Unable to save feedback." } ``` Handle failures conservatively: | Result | Meaning | Agent action | | -------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `400 Bad Request` | The body is malformed JSON or does not match the request schema. | Correct the body against the live schema; do not retry it unchanged. | | Network or CORS failure | No response was available, so acceptance is unknown. | Keep the current page context and retry only when connectivity is restored. Avoid rapid retries. | | `500 Internal Server Error` | Doc Duck could not persist the feedback. | Retry later with bounded backoff, preserving the same observation. | | `200` with a non-empty confirmation ID | The feedback was accepted. | Stop. Do not submit the same observation again. | The confirmation ID acknowledges this submission. For one-shot current-page feedback, an agent does not need to store or use it; stop after the successful response. ## Keep the report scoped Before sending, verify that `host`, `path`, `selection`, and `comment` all refer to the page the agent is viewing now. Remove credentials, private prompts, personal data, and unrelated application content. If the issue belongs to another page, navigate there and reassess it in that page's own context instead of reusing the current request.