Agent feedback for the current page

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. The live request JSON Schema 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.

{
  "feedback": "like",
  "organizationId": "org_example",
  "path": "/docs/example",
  "host": "docs.example.com"
}

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

{
	"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

{
	"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:

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:

{
	"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:

{
	"message": "Unable to save feedback."
}

Handle failures conservatively:

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.