> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent feedback

> Rate an earlier Stophy call by its request ID when the answer was wrong or incomplete. A bad rating refunds that call. Free for agents and developers.

Rate a result when it helped, missed something or was wrong. It needs a key and costs nothing. A `bad` rating refunds what that call cost, up to the daily cap in [Pricing](https://docs.stophy.dev/account/pricing.md#free). Send one rating per call. Do not report errors you can fix by changing the request.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/feedback \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jobId": "31fb1c5e-c206-443e-9274-c8d0bf75002c", "endpoint": "search", "rating": "bad", "note": "The first result is unrelated to the query."}'
```

`jobId` is the `X-Request-ID` header of the call you rate. The answer has `feedbackId`, `refundedUsd`, `refundedTodayUsd`, `dailyRefundCapUsd`, `dailyCapReached` and `alreadySubmitted`. Rating the same `jobId` again returns the first `feedbackId` with `alreadySubmitted: true` and refunds nothing. A call that cost nothing or is not billed to your account has nothing to refund, and the rating is still saved.

To rate specific search results, call `POST /v1/search/{jobId}/feedback` with the same rating and result fields. For example, add `{"source": "web", "position": 2}` to `valuableResults`.

## Fields

`rating` and, on `POST /v1/feedback`, `jobId` are required.

| Field | Type | Meaning |
| - | - | - |
| `rating` | `string` | `good`, `partial` or `bad` |
| `valuableSources` | `array` | Up to 50 pages that helped: `url` and an optional `reason` up to 1,000 characters |
| `valuableResults` | `array` | Up to 50 search results that helped: `source` (`web`, `images` or `news`), `position` 1 to 100, optional `reason` |
| `missingContent` | `array` | Up to 50 topics the answer lacked: `topic` up to 200 characters |
| `querySuggestions` | `string` | A better query, up to 2,000 characters |
| `origin`, `integration` | `string` | Which client or integration sent it, up to 80 characters. `origin` is `api` by default. |
| `endpoint` | `string` | `search`, `scrape`, `parse` or `map`. Only on `POST /v1/feedback`, as are the rest of the table. |
| `issues`, `tags` | `array of string` | Up to 20 short lowercase labels each, such as `missing_content` |
| `note` | `string` | What went wrong and what you expected, up to 4,000 characters. Keep keys and personal data out. |
| `url` | `string` | The page the report is about |
| `pageNumbers` | `array of number` | Up to 100 page numbers |
| `metadata` | `object` | Anything else to keep with the report |

## Errors

* No key: `401 apiKeyRequired`.
* A `jobId` over 100 characters or with characters other than letters, digits, `_` and `-`, or a value over a limit above: `400 invalidRequest`.
* A `jobId` that is not one of your billed calls: `200`, saved, nothing refunded.

## Tell your agent

Add a line like this to `AGENTS.md` or `CLAUDE.md`.

> If a Stophy answer is wrong or differs from the docs, rate it once with POST [https://api.stophy.dev/v1/feedback](https://api.stophy.dev/v1/feedback). Send the X-Request-ID header as jobId, and never include secrets.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.