---
title: "Report a Candor bug, friction, or idea to the Candor team."
method: POST
path: "/v1/feedback"
---

# Report a Candor bug, friction, or idea to the Candor team.

`POST /v1/feedback`

## Request

- Base URL: `https://api.candor.money`
- URL: `https://api.candor.money/v1/feedback`
- Auth: HTTP bearer

Send one product report about Candor's software. Candor's feedback endpoint stores it and delivers it to the Candor team; it leaves the workspace and does not change any record, note, or approved state. After Candor misbehaves or needs a workaround, the agent offers the report to the user once their task is finished and sends it only when the user agrees or asks for it; it never blocks the user's work. Strip financial and personal data first and describe Candor's behavior with operation names and error codes.

## Headers

- `Idempotency-Key` string, required

## Request body

- FeedbackSubmitRequest: One product report about Candor's software for the Candor team, sent when the user agrees to it or asks for it. Candor's feedback endpoint stores it and delivers it to the team; it does not enter the workspace and creates no record the user or agent can read back. Write it after removing account numbers, balances, amounts, merchant names, people, and other financial or personal data from the title and body; describe what Candor did with operation names and error codes.
  - `kind` 'bug' | 'friction' | 'idea', required: `bug` when an operation did not work as documented or the agent had to work around Candor. `friction` when something works but took more steps, retries, or guesswork than it should. `idea` for a capability or change that would have made the user's task easier.
  - `title` string, required: One trimmed summary line without line breaks and with at least one non-space character, such as "notes.update rejects a null revisit_at after resolve". It becomes the report's subject.
  - `body` string, required: Markdown detail with at least one non-space character. State what was attempted, what was expected, and what happened instead, with operation names, error codes, and the workaround used. No financial data.
  - `about_operation` string: The Candor operation id the report concerns, such as `notes.update`, as listed by `candor commands`. Omitting it costs triage the exact surface.
  - `about_action_id` string: The action id of the request where the problem occurred, from that response's envelope `action.id`. It lets triage read the exact operating context; omit it when the report is not about one request.

## Response `200`

Stored feedback receipt envelope.

- ResponseEnvelope
  - `schema_version` string, required
  - `generated_at` string, date-time, required
  - `request_id` string, required
  - `status` 'success' | 'partial_success' | 'action_required' | 'error', required
  - `user_message` string: Optional concise user-safe message the calling agent may adapt.
  - `data_freshness` DataFreshness
    - `balances_last_synced_at` string
    - `coverage` 'complete' | 'partial' | 'stale' | 'unavailable', required
    - `holdings_last_synced_at` string
    - `transactions_last_synced_at` string
  - `metadata` object: Response-level protocol metadata such as package compatibility and workspace opening identity or timing. It is not financial workspace data and must not be treated as attention.
    - `view_url` string, uri: Authenticated dashboard destination related to this response. May open a section rather than reproduce the returned records or filters. Per-record view_url values identify exact supported record views. Use returned URLs instead of constructing paths.
  - `warnings` object[], required
  - `errors` AgentError[], required
    - `code` string, required
    - `expires_at` string
    - `idempotency_key` string: Stable key to reuse when retrying this identical logical operation.
    - `message` string, required
    - `recovery_url` string, uri
    - `required_capability` string
    - `retry_after_seconds` integer: Machine-actionable delay before retrying the identical logical operation.
    - `retryable` boolean, required
    - `suggested_command` string
  - `next_actions` AgentAction[], required
    - `intent` string, required
    - `command` string, required
    - `args` object, required
    - `shell` string, required
  - `action` WorkspaceAction
    - `id` string, required
    - `operation` string, required
    - `reason` string, required
    - `root_action_id` string, required
    - `parent_action_id` string
    - `task_key` string
    - `status` 'started' | 'succeeded' | 'refused' | 'failed', required
    - `created_at` string, date-time, required
    - `completed_at` string, date-time
  - `data` object, nullable, required: Operation-specific result data, or null when the request ends in an error.

## Other responses

- `default`: Structured Candor error envelope with machine-readable codes, recovery guidance, and retry timing when applicable.

---

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