> ## 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 the answer of an earlier Stophy call with its request id. A bad rating refunds what the call cost, up to $0.10 a day. Free for agents and developers.

Feedback tells Stophy that an answer was good, partly right or wrong, in one free call. A bad rating also refunds what that call cost, up to \$0.10 a day. An agent or a developer can send it. It needs an API key.

## When to report

Report an answer that is wrong or incomplete, or a search that missed what you needed. Send one rating for each call, with the call's `requestId` as `jobId`. Do not report errors you can fix by changing the request.

## Make a request

This request rates a search as good. `jobId` is the `requestId` from the search answer.

```bash cURL 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": "good",
    "note": "The first result is the project'"'"'s own repository, as expected.",
    "tags": ["docs-example"]
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/feedback", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    jobId: "31fb1c5e-c206-443e-9274-c8d0bf75002c",
    endpoint: "search",
    rating: "good",
    note: "The first result is the project's own repository, as expected.",
    tags: ["docs-example"],
  }),
});
console.log(await response.json());
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.stophy.dev/v1/feedback",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "jobId": "31fb1c5e-c206-443e-9274-c8d0bf75002c",
        "endpoint": "search",
        "rating": "good",
        "note": "The first result is the project's own repository, as expected.",
        "tags": ["docs-example"],
    },
)
print(response.json())
```

## Read the response

```json theme={null}
{
  "success": true,
  "feedbackId": "806ff505-bc18-457c-8e25-193e22d0d331",
  "refundedUsd": 0,
  "alreadySubmitted": false,
  "dailyCapReached": false,
  "refundedTodayUsd": 0,
  "dailyRefundCapUsd": 0.1,
  "costUsd": 0,
  "requestId": "179d33be-cac3-4874-9734-784a75a69205"
}
```

`feedbackId` names your report. `refundedUsd` is what this rating gave back, and `refundedTodayUsd` is what has been refunded today out of `dailyRefundCapUsd`. `dailyCapReached` is `true` once the cap is used.

Rating the same `jobId` again returns the first `feedbackId` with `alreadySubmitted: true` and refunds nothing.

```json theme={null}
{
  "success": true,
  "feedbackId": "806ff505-bc18-457c-8e25-193e22d0d331",
  "refundedUsd": 0,
  "alreadySubmitted": true,
  "dailyCapReached": false,
  "dailyRefundCapUsd": 0.1,
  "costUsd": 0
}
```

## Rate a search

`POST /v1/search/{jobId}/feedback` rates a search and takes the search's `requestId` in the path. Use it to say which results helped and what was missing.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/search/0664204e-ff95-4cc1-92f6-b346f6fbbd30/feedback \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": "partial",
    "valuableResults": [{ "source": "web", "position": 2, "reason": "Official runtime docs." }],
    "missingContent": [{ "topic": "Bun release notes" }],
    "querySuggestions": "bun runtime release notes",
    "origin": "docs-example"
  }'
```

The answer has the same fields as above. This call saved with `alreadySubmitted: false`.

## Options

Both calls take these fields. `rating` is required.

| Field | Type | What it does |
| - | - | - |
| `rating` | `string` | `good`, `partial` or `bad`. `bad` refunds the call. |
| `valuableSources` | `array of object` | Up to 50 pages that helped, each a `url` and an optional `reason` of up to 1,000 characters |
| `valuableResults` | `array of object` | Up to 50 search results that helped, each a `source` (`web`, `images` or `news`), a `position` from 1 to 100 and an optional `reason` |
| `missingContent` | `array of object` | Up to 50 topics the answer lacked, each a `topic` of up to 200 characters |
| `querySuggestions` | `string` | A better query, up to 2,000 characters |
| `origin` | `string` | Which client sent it, up to 80 characters. `api` by default. |
| `integration` | `string` | Which integration sent it, up to 80 characters |

`POST /v1/feedback` also takes these:

| Field | Type | What it does |
| - | - | - |
| `jobId` | `string` | The `requestId` of the call you rate. Required. |
| `endpoint` | `string` | Which endpoint made the call: `search`, `scrape`, `parse` or `map` |
| `issues` | `array of string` | Up to 20 things that went wrong, each a short lowercase label such as `missing_content` |
| `tags` | `array of string` | Up to 20 labels of your own, in the same form as `issues` |
| `note` | `string` | What went wrong and what you expected, up to 4,000 characters. Keep keys and personal data out. |
| `url` | `string` | The URL of the page the report is about |
| `pageNumbers` | `array of number` | Up to 100 page numbers the report is about |
| `metadata` | `object` | Anything else you want kept with the report |

## Refunds

A `bad` rating refunds what the rated call cost, back into your balance. The refunds add up to at most \$0.10 a day. After that the rating is still saved and `dailyCapReached` is `true`. A call that cost nothing, or one that was not billed to your account, has nothing to refund. Each call can be rated once.

## Limits and errors

| Case | Answer |
| - | - |
| No API key | `401 apiKeyRequired` |
| A `jobId` with characters other than letters, digits, `_` and `-`, a `jobId` over 100 characters, or a value over a limit above | `400 invalidRequest` |
| The same `jobId` rated again | `200` with `alreadySubmitted: true` |
| A `jobId` that is not one of your billed calls | `200`, saved with nothing refunded |

## Tell your agent

Add a line like this to your agent's instructions file, such as `AGENTS.md` or `CLAUDE.md`.

```text theme={null}
If a Stophy answer is wrong or differs from the docs, rate it once with POST https://api.stophy.dev/v1/feedback. Send the requestId as jobId, and never include secrets.
```

## Related

* [Troubleshooting](https://docs.stophy.dev/production/troubleshooting.md)
* [Usage and logs](https://docs.stophy.dev/production/usage-and-logs.md)
* [Pricing](https://docs.stophy.dev/account/pricing.md)


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