---
title: "Submit feedback"
method: POST
path: "/v1/tools/betteroff_submit_feedback"
tags: ["tools"]
---

# Submit feedback

`POST /v1/tools/betteroff_submit_feedback`

## Request

- Base URL: `https://api.betteroff.finance`
- URL: `https://api.betteroff.finance/v1/tools/betteroff_submit_feedback`
- Auth: one of:
  - OpenID Connect (`https://app.betteroff.finance/api/auth/.well-known/openid-configuration`, scopes: `feedback:submit`)
  - HTTP bearer

Send a diagnostic report to BetterOff support only when the user requests or approves sending it. Creates a support case, not a financial correction. Never send conversation history, balances, transactions, tool payloads, or credentials. Reuse the idempotency key when retrying. Returns a receipt, not a promise of resolution.

## Request body

- object
  - `category` 'bug' | 'confusing_result' | 'missing_capability' | 'suggestion', required
  - `description` string, required: User-approved diagnostic summary. Exclude financial data, credentials, conversation history, and tool payloads.
  - `toolName` string
  - `requestId` string
  - `client` string
  - `clientVersion` string
  - `idempotencyKey` string, uuid, required: Generate once per report; reuse for every retry.
  - `userApproved` true, required: True only after the user requests or approves sending this report.

## Response `200`

Tool result

- union
  - object
    - `ok` false, required
    - `requestId` string
    - `code` 'INVALID_INPUT' | 'RATE_LIMITED' | 'ACCESS_DENIED', required
    - `error` string, required
    - `retryable` false, required
    - `nextStep` string, required
  - object
    - `ok` true, required
    - `requestId` string
    - `schemaVersion` '4', required
    - `receiptId` string, uuid, required
    - `status` 'submitted', required
    - `duplicate` boolean, required

## Other responses

- `400`: INVALID_INPUT (a missing, unknown, or invalid argument, named in `fields`), TOOL_CALL_REJECTED, or a body that is not JSON.
- `401`: AGENT_TOKEN_INVALID: the token is missing, expired, or revoked.
- `402`: AGENT_SUBSCRIPTION_INACTIVE or FEATURE_NOT_INCLUDED: needs BetterOff Core.
- `403`: INSUFFICIENT_SCOPE, ACCESS_DENIED, or AGENT_GRANT_REVOKED.
- `404`: TOOL_NOT_FOUND, or NOT_FOUND for a record the org does not have.
- `409`: CONFLICT: the record's state rules this call out. Read it again.
- `422`: INCOMPLETE_DATA or RESULT_TOO_LARGE. Narrow the request; don't retry as is.
- `429`: RATE_LIMITED. Retry after Retry-After seconds.
- `503`: DATA_UNAVAILABLE, DEPENDENCY_UNAVAILABLE (including the 25-second tool deadline), or AGENT_AUTHZ_UNAVAILABLE. Retryable.
- `default`: Problem details

---

[API](https://skmtc.dev/betteroff/apis/betteroff-api.md) · [All operations](https://skmtc.dev/betteroff/apis/betteroff-api/llms.txt) · [OpenAPI document](https://skmtc.dev/betteroff/apis/betteroff-api/revisions/bc858c8d428d?raw)