---
title: "submit_feedback"
description: "Generated reference for the management action submit_feedback: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/submit-feedback
order: 77
visibility: public
redirects_from: []
---

# submit\_feedback

Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources).

A script calls this action over HTTPS at `POST https://turnzero.ai/api/v1/submit_feedback`, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool `submit_feedback`.

OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts ([Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/)).

**Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

## Contract description

File feedback about Turn Zero: bugs, gaps, refusals, missing pages, workarounds or praise\.

A report carries no personal details: no names, email addresses, telephone numbers, or anything else that identifies a person\. A tool quotes the person's content in a report only if that person files it\.

A repeated `problem_key` joins the same issue\. The result includes your report, issue state and up to three possible duplicates\. A call with `report` and `repeat_of` confirms a duplicate\.

Details: read\_documentation /cloud/guides/feedback/\.

## More about this action

Your report is filed with your acting account as its actor\. The `kind` is one of `bug`, `gap`, `docs`, `friction`, `question`, `task`, `praise`, and `idea`\. Some older words are still read as one of them: `missing_capability`, `documentation_gap`, `refusal_not_understood`, `usability`, and `problem`, `error`, and `mistake` for a `bug`\. `body` aliases `text`, and `key` aliases `problem_key`\. The older `severity` spelling maps `critical` and `high` to `blocked`, `medium` to `worked_around`, and `low` to `annoyed`\. Pass one spelling of each\. With `recovered: true`, pass the legacy `key` and no filing members to settle your open filing\.

Every form requires `source`: `agent` for your own feedback, `person` for a report the person dictated, or `system` for a program's or company harness's feedback\. Only `agent` takes `provider` and `session`\. Supply both or neither\. Under a minted token, `person` is written as `agent`\. For a filing, give a `title`, the feedback in `text`, its `impact` on the reporter or the person whose experience they describe, and any `workaround`\. Keep the filer's own words, including dictated feedback\.

Where the reference in `evidence` identifies one of your own refused calls, the platform stamps the action, the refusal, the code site, and the build from its own record on either of two grounds\. The kind is `bug`; or the impact is `blocked`, the kind is neither `praise` nor `idea`, and the action is one the target space lists as critical\. The latter ground needs the space's configuration; a failed read admits no critical action\. Where that call was not refused, it writes the action and the build and leaves the evidence as you claimed it\. A report about a refused call that meets neither ground also gets the refusal, still marked as claimed and with no code site\.

Without a `problem_key`, the service derives one from the kind, the title, and the evidence's action and refusal\. Praise is kept apart: praise and a report of another kind under one key go to two issues\. A filing under your earlier key is answered `retried`, with that report and nothing stored, only where its evidence and its words both equal the earlier report's\. One whose words differ adds a report to the same issue\.

To confirm that a report repeats an issue, pass `repeat_of`\. In the platform space, use a candidate your filing returned or an issue already linked to one of your reports\. In your account's or application's own space, `repeat_of` may name any issue there\. For an issue closed `duplicate`, confirm its master instead\. On a new filing, the report joins that issue at once\.

With `report`, use the earlier report's number, never an issue's\. It links that report to the issue\. The earlier issue closes as a duplicate only if that report opened it, it has no other report link, and its state is new, open or waiting\. Otherwise it keeps its state and the report links to both\. The answer's `outcome` is `confirmed` when linked or `related` when only a relation is made\. Where one of the two is praise and the other is not, nothing is linked and the answer reads `related`\.

To correct or withdraw a report of your own, call again with `amends`, the report's number and never an issue's, and the corrected words or `withdraws: true`\. The call accepts `withdraws`, `title`, `text`, `impact`, `workaround`, `proposed_resolution`, `kind`, `labels`, and `product` alone\. Each of those you leave out keeps the report's value\. Null on `text`, `workaround`, or `proposed_resolution` clears that member; an empty `text` still clears the text\. The correction is filed beside the report, which stays as filed and keeps its evidence, and joins every issue the report belongs to\. The call returns `amended`\. Another account's report is refused `not_found`\.

To attach screenshots, store each with `mint_upload_grant` and its put line, then list it in `files` as `{ application, area, name, environment }`\. List at most 4, each a PNG, JPEG, or WebP file of at most 524,288 bytes\. An image is stored exactly as sent; the platform removes nothing from it\. An item's `environment`, if omitted, is the deploy target\.

The `evidence` argument says what the report is about: the action, the refusal name, the reference the refusal or the answer gave, and the code site\. Give both `environment` and `version` to record the reported product's build, rather than an application's deploy target\. One without the other is accepted but not recorded\. The `context` member has at most 20 short string members whose names use lowercase letters, digits, and underscores\.

Pass `space` to file into an issue space your acting account has, given by its identifier, a lowercase UUID\. It is the account's own space, an application's own space as `submit_manifest`'s receipt gives it, or one space of an application's per\-environment pair\. The report goes into that space under the space's own token, with your acting account as its actor\. A request that passes `application` or `environment` is refused `invalid_request`, and the refusal gives `space`\.

## Access and action metadata

```json
{
  "name": "submit_feedback",
  "resource": "account",
  "tier": "reversible",
  "surface": "account",
  "addresses": [
    "tzcloud",
    "tztools"
  ],
  "admits": [
    "synthetic_estate",
    "tzmesh",
    "tztrack",
    "device_sign_in"
  ],
  "summary": "File a report into the platform's own space of the issue service as your own actor, under any bearer or account-scoped minted token, a token the synthetic_estate grant bounds among them. `source` gives the actor's kind, `person`, `agent`, or `system`, and an agent also gives its `provider` and `session`; under a minted token, `person` is written as `agent`. `kind` is one of the record's eight kinds, `idea` among them, or a word still accepted for one, `problem`, `error`, and `mistake` for a `bug` among them. The report comes with a `title`, an optional `text` (or `body`), `impact` (or `severity`), `workaround`, `proposed_resolution`, `labels`, `restricted`, and an `evidence` member. That member gives the action, the refusal, and the reference the report is about. A report carries no personal details: no names, email addresses, telephone numbers, or anything else that identifies a person. Where the reference identifies one of your own refused calls, the platform stamps the action, the refusal, the code site, and the build from its own record on either of two grounds. The kind is `bug`; or the impact is `blocked`, the kind is neither `praise` nor `idea`, and the action is one of the target space's `critical_actions`. It then marks the evidence stamped. Where that call was not refused, it writes the action and the build and leaves the evidence as claimed. A report about a refused call that meets neither ground also carries the refusal, still claimed and with no code site. `problem_key` (or `key`) identifies the problem among your own reports, a repeat with new evidence filing a new report linked to the same issue. Praise and a report of another kind under one key are filed on two issues. The answer carries your own report, the issue through the projection, the outcome (`filed`, `linked`, `retried`, `noted`, `confirmed`, `related`, or `amended`), up to three candidates it may be repeating, and the credential forms masked in its text. `repeat_of` beside a filing, or `report` with `repeat_of` alone, confirms a candidate. Across the praise kind it links nothing and the outcome reads `related`. `amends`, the number of one of your own reports and never an issue's, files an amendment. Beside it the call takes `withdraws`, `title`, `text` (or `body`), `impact` (or `severity`), `workaround`, and `proposed_resolution` alone. The report remains as filed, the amendment joins every issue the report belongs to, and the outcome is `amended`. Another account's report is refused `not_found`, as a number no report carries is. `files` attaches 1 to 4 images to a filing, each a PNG, JPEG, or WebP file of at most 524,288 bytes that `mint_upload_grant`'s put line stored in an area of the account's own application: the plane reads each under the call's credential before any call, refuses one it does not find `not_found` and one over the size `invalid_request`, and relays it as stored, serving no image on its own origin. With `key` and `recovered: true` and no member of a filing, the call is the 0.2.0 recovered mark. The plane bounds an account's filings and the relayed total per minute, refusing `feedback_rate_limited`, and refuses `issue_service_unreachable` where the service could not be reached. Registered while the issue service's origin is configured and unlisted, refusing `not_yet_provisioned`, before it. With `space`, the identifier of an issue space your account holds, the filing goes into that space. It is a space of the account's own, an application's own space, or one space of an application's per-environment pair. An identifier that matches no such space is refused `not_found` before any token is read. A token bounded to an application is refused `token_scope_refused`, its route to a space the egress gateway's.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": false
  }
}
```

## MCP catalog entry

```json
{
  "name": "submit_feedback",
  "title": "Send feedback",
  "tier": "reversible",
  "scenario": "CHI-L0-14",
  "summary": "File feedback about Turn Zero: bugs, gaps, refusals, missing pages, workarounds or praise.\n\nA report carries no personal details: no names, email addresses, telephone numbers, or anything else that identifies a person. A tool quotes the person's content in a report only if that person files it.\n\nA repeated `problem_key` joins the same issue. The result includes your report, issue state and up to three possible duplicates. A call with `report` and `repeat_of` confirms a duplicate.\n\nDetails: read_documentation /cloud/guides/feedback/.",
  "owners": [
    "API-L0-20"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["source"\]<br>Replaced members: application and environment were replaced by space<br>Retired members: personal and excerpt: A report has no personal option: file it again without it, leaving out anything you want excluded\. |
| /<wbr>properties/<wbr>source | Author: `agent` \(you\), `person` \(dictated\), or `system` \(program\)\. Only `agent` takes `provider` and `session`\.<br><br>Type: string<br>Allowed values: \["person","agent","system"\] |
| /<wbr>properties/<wbr>provider | AI provider name\.<br><br>Type: string<br>Pattern: ^\[a\-z\]\[a\-z0\-9\-\]\{0,31\}$ |
| /<wbr>properties/<wbr>session | Host session id; paired with `provider`\.<br><br>Type: string<br>Maximum length: 200 |
| /<wbr>properties/<wbr>kind | Required for filings; optional with `amends`, absent on confirmations; customer `question`/`task` refused\.<br><br>Type: string<br>Allowed values: \["bug","gap","docs","friction","question","task","praise","idea","missing\_capability","documentation\_gap","refusal\_not\_understood","problem","error","mistake","usability"\] |
| /<wbr>properties/<wbr>title | Required for filings; optional with `amends`; absent on confirmations and recovered marks\.<br><br>Type: string<br>Maximum length: 200 |
| /<wbr>properties/<wbr>text | Reporter's words, including dictated feedback\. It carries no personal details: no names, email addresses, telephone numbers, or anything else that identifies a person\.<br><br>Type: \["string","null"\]<br>Maximum length: 20000 |
| /<wbr>properties/<wbr>body | Alias of `text`\.<br><br>Type: \["string","null"\]<br>Maximum length: 20000 |
| /<wbr>properties/<wbr>impact | Effect on the reporter or the person described\.<br><br>Type: string<br>Allowed values: \["blocked","worked\_around","annoyed","none"\] |
| /<wbr>properties/<wbr>severity | Maps to `impact`; see reference\.<br><br>Type: string<br>Allowed values: \["critical","high","medium","low"\] |
| /<wbr>properties/<wbr>workaround | Workaround; null clears with `amends`\.<br><br>Type: \["string","null"\]<br>Maximum length: 4000 |
| /<wbr>properties/<wbr>proposed\_resolution | Proposed fix; null clears with `amends`\.<br><br>Type: \["string","null"\]<br>Maximum length: 4000 |
| /<wbr>properties/<wbr>labels | Letters `a-z`, digits or `-_.:`; first a letter or digit\.<br><br>Type: array<br>Maximum items: 20 |
| /<wbr>properties/<wbr>labels/<wbr>items | Type: string<br>Maximum length: 64 |
| /<wbr>properties/<wbr>evidence | Call identifiers\.<br><br>Type: object<br>Additional properties: false |
| /<wbr>properties/<wbr>evidence/<wbr>properties/<wbr>action | Action name without `tzcloud_`\.<br><br>Type: string<br>Maximum length: 200 |
| /<wbr>properties/<wbr>evidence/<wbr>properties/<wbr>refusal | Refusal name\.<br><br>Type: string<br>Maximum length: 200 |
| /<wbr>properties/<wbr>evidence/<wbr>properties/<wbr>reference | Call's `reference`\.<br><br>Type: string<br>Maximum length: 200 |
| /<wbr>properties/<wbr>evidence/<wbr>properties/<wbr>code\_site | Code location in the answer\.<br><br>Type: string<br>Maximum length: 200 |
| /<wbr>properties/<wbr>evidence/<wbr>properties/<wbr>environment | Build environment; recorded only with `version`\.<br><br>Type: string<br>Maximum length: 200 |
| /<wbr>properties/<wbr>evidence/<wbr>properties/<wbr>version | Build version; recorded only with `environment`\.<br><br>Type: string<br>Maximum length: 200 |
| /<wbr>properties/<wbr>evidence/<wbr>properties/<wbr>context | At most 20 short strings; keys: `a-z`, digits or `_`\.<br><br>Type: object<br>maxProperties: 20 |
| /<wbr>properties/<wbr>evidence/<wbr>properties/<wbr>context/<wbr>additionalProperties | Type: string<br>Maximum length: 500 |
| /<wbr>properties/<wbr>restricted | Hides a security report from other reporters\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>problem\_key | Your problem key\.<br><br>Type: string<br>Maximum length: 200 |
| /<wbr>properties/<wbr>key | Alias of `problem_key`\.<br><br>Type: string<br>Maximum length: 200 |
| /<wbr>properties/<wbr>repeat\_of | Repeated issue, e\.g\. `#92`\.<br><br>Type: string<br>Pattern: ^\#\[1\-9\]\[0\-9\]\*$ |
| /<wbr>properties/<wbr>report | Report for `repeat_of`, not an issue\.<br><br>Type: integer<br>Minimum: 1 |
| /<wbr>properties/<wbr>amends | Report to correct or withdraw\.<br><br>Type: integer<br>Minimum: 1 |
| /<wbr>properties/<wbr>withdraws | Withdraws the `amends` report; false reverses it\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>recovered | Legacy recovered mark; see reference\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>files | Screenshots uploaded with `mint_upload_grant`: PNG/JPEG/WebP, at most 524,288 bytes each\.<br><br>Type: array<br>Minimum items: 1<br>Maximum items: 4 |
| /<wbr>properties/<wbr>files/<wbr>items | Type: object<br>Required fields: \["application","area","name"\] |
| /<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>application | Screenshot's app id\.<br><br>Type: string |
| /<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>area | Screenshot storage area\.<br><br>Type: string |
| /<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>name | Stored path within the area\.<br><br>Type: string |
| /<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>environment | Upload environment; absent uses the app's deploy target\.<br><br>Type: string<br>Allowed values: \["development","production"\] |
| /<wbr>properties/<wbr>space | Issue space UUID; absent for platform\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{8\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{12\}$ |
| /<wbr>properties/<wbr>product | Turn Zero product; absent for platform, MCP or your app's issues\. In your space, only for that product\.<br><br>Type: string<br>Allowed values: \["tzcloud","tztrack","tzmesh"\] |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","issue","outcome"\] |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>reference | The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call's record row\. Quote it when you report the call\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{10\}$ |
| /<wbr>properties/<wbr>report | Your own report as filed: its `id`, the report's number; its origin; its text; its impact; its evidence and the basis of it \(`stamped`, `confirmed`, or `claimed`\); the builds it saw; and the images it carries\. The service's other members of a report may appear beside them\.<br><br>Type: object<br>Required fields: \["id"\] |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>id | The report's number, which you pass as `report` beside `repeat_of` to confirm a candidate\.<br><br>Type: integer<br>Minimum: 1 |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>origin | Where the report came from, which the platform gives it and you do not set: `field` for a filing about the platform, `beta` for a company harness's, and on an application's own space `person`, `workspace`, or `test`\.<br><br>Type: string<br>Allowed values: \["test","beta","field","person","workspace","platform"\] |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>text | What was attempted and what came back, as filed, the credential forms the service found masked\.<br><br>Type: string |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>impact | What the problem cost, or null where the filing gave none\.<br><br>Type: \["string","null"\]<br>Allowed values: \["blocked","worked\_around","annoyed","none",null\] |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>evidence | The evidence as the report holds it: the action, the refusal, the reference, the code site, and the context, the action and the refusal read from the platform's own record where the reference identified one of your own calls\.<br><br>Type: object |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>evidence\_basis | `stamped` for your refused call on either ground: the kind is `bug`; or the impact is `blocked`, the kind is neither `praise` nor `idea`, and the action is critical in the target space\. `confirmed` when the daily check verifies a refused or failed call and both report and issue kinds meet that rule for the platform space\. `claimed` otherwise\.<br><br>Type: string<br>Allowed values: \["stamped","confirmed","claimed"\] |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>seen\_in | The builds the report saw, each its release line or null, its version, and its environment\.<br><br>Type: array |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>seen\_in/<wbr>items | Type: object<br>Required fields: \["release\_line","version","environment"\] |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>seen\_in/<wbr>items/<wbr>properties/<wbr>release\_line | Type: \["string","null"\] |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>seen\_in/<wbr>items/<wbr>properties/<wbr>version | Type: string |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>seen\_in/<wbr>items/<wbr>properties/<wbr>environment | Type: string |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>amends | On an amendment, the number of the report it amends; null on any other report\.<br><br>Type: \["integer","null"\] |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>withdraws | On an amendment, true where it withdraws the report it amends; false on any other report\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>attachments | The images the report carries, each its `id`, its judged `media_type`, its size in `size_bytes`, and its `sha256`, `size_bytes` 0 and `sha256` null once it is removed\. The platform serves no image; `relay_issue_act`'s `attachment` fetches one from your own space\.<br><br>Type: array |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>attachments/<wbr>items | Type: object |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>attachments/<wbr>items/<wbr>properties/<wbr>id | Type: string |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>attachments/<wbr>items/<wbr>properties/<wbr>media\_type | Type: string<br>Allowed values: \["image/png","image/jpeg","image/webp"\] |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>attachments/<wbr>items/<wbr>properties/<wbr>size\_bytes | Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>report/<wbr>properties/<wbr>attachments/<wbr>items/<wbr>properties/<wbr>sha256 | Type: \["string","null"\] |
| /<wbr>properties/<wbr>issue | On a filing, an amendment, or a confirmation: the issue the report is linked to, through the projection, or null on the platform's space where that issue is restricted and the credential does not read the queue\. On the 0\.2\.0 recovered mark: the issue as that wire returns it to a credential that reads the queue or on a named space, and to any other credential its `id`, `status`, and `disposition` alone, or null\.<br><br>Type: \["object","null"\] |
| /<wbr>properties/<wbr>issue/<wbr>properties/<wbr>id | Type: string<br>Pattern: ^\#\[1\-9\]\[0\-9\]\*$ |
| /<wbr>properties/<wbr>issue/<wbr>properties/<wbr>state | Type: string<br>Allowed values: \["new","open","waiting","fixed","closed"\] |
| /<wbr>properties/<wbr>issue/<wbr>properties/<wbr>outcome | Type: \["string","null"\] |
| /<wbr>properties/<wbr>issue/<wbr>properties/<wbr>sentence | Type: string |
| /<wbr>properties/<wbr>issue/<wbr>properties/<wbr>workaround | Type: \["string","null"\] |
| /<wbr>properties/<wbr>issue/<wbr>properties/<wbr>note\_to\_reporters | The note written for everyone who reported the issue, 1 to 2,000 characters, or null\. The platform team writes a question or news there on any state, and a landed fix writes the line identifying its change\. Through the projection, a landed fix's note is returned only while the issue is `fixed`, or `closed` `done` or `verified`, and a reader of the queue reads the note as it is\. No filing sets it\. On the platform's own space it is null where the note carries a statement or decision identifier, read by its form\.<br><br>Type: \["string","null"\]<br>Minimum length: 1<br>Maximum length: 2000 |
| /<wbr>properties/<wbr>issue/<wbr>properties/<wbr>live\_in | Always null in this filing answer, even if the fix is released\. Call `read_feedback` to read the build the fix is live in\.<br><br>Type: \["object","null"\] |
| /<wbr>properties/<wbr>issue/<wbr>properties/<wbr>requirements | The identifiers of the statements that design the behaviour, strings, where the issue closed as designed in a team's own space; null otherwise, and always null on the platform's own space\.<br><br>Type: \["array","null"\] |
| /<wbr>properties/<wbr>outcome | What the call did: `filed` a new issue, `linked` the report to an existing one, `retried` an earlier identical filing, `noted` praise, `confirmed` a candidate, `related`, or `amended` a report of your own; the 0\.2\.0 recovered mark returns that wire's words\. The outcome reads `related` where `repeat_of` identifies an issue across the praise kind: nothing is linked, and the report keeps its own issue\.<br><br>Type: string<br>Allowed values: \["filed","linked","retried","noted","confirmed","related","amended","recovered","repeated","reopened"\] |
| /<wbr>properties/<wbr>candidates | Up to three issues the report may repeat: each title, summary, and workaround only where a trusted actor wrote them\. Each carries its issue's `kind` and `component`, and `matched_evidence` lists the members of your report's `evidence` that equal those of the standing reports whose evidence chose that issue, empty where only your title's words matched\. A candidate may be an issue closed `declined` or `as_designed`: its `outcome` and fixed `sentence` mean the request was considered and not taken, and filing it again does not reopen it\. A candidate's `outcome` is null while its issue is not closed\. On the platform's own space the list is empty except to the platform team, which links duplicates when it triages a report\. A null `title` means the platform team has not written that issue's title\. The report is already filed: confirm a candidate with `repeat_of` only where you know it is the same issue\. Otherwise nothing more is needed, since the platform's triage proposes duplicates itself\.<br><br>Type: array |
| /<wbr>properties/<wbr>candidates/<wbr>items | Type: object |
| /<wbr>properties/<wbr>candidates/<wbr>items/<wbr>properties/<wbr>issue | Type: string<br>Pattern: ^\#\[1\-9\]\[0\-9\]\*$ |
| /<wbr>properties/<wbr>candidates/<wbr>items/<wbr>properties/<wbr>title | Type: \["string","null"\] |
| /<wbr>properties/<wbr>candidates/<wbr>items/<wbr>properties/<wbr>state | Type: string<br>Allowed values: \["new","open","waiting","fixed","closed"\] |
| /<wbr>properties/<wbr>candidates/<wbr>items/<wbr>properties/<wbr>outcome | Type: \["string","null"\]<br>Allowed values: \["declined","as\_designed",null\] |
| /<wbr>properties/<wbr>candidates/<wbr>items/<wbr>properties/<wbr>sentence | Type: string |
| /<wbr>properties/<wbr>candidates/<wbr>items/<wbr>properties/<wbr>workaround | Type: \["string","null"\] |
| /<wbr>properties/<wbr>candidates/<wbr>items/<wbr>properties/<wbr>live\_in | Type: \["object","null"\] |
| /<wbr>properties/<wbr>candidates/<wbr>items/<wbr>properties/<wbr>summary | Type: \["string","null"\] |
| /<wbr>properties/<wbr>candidates/<wbr>items/<wbr>properties/<wbr>kind | Type: string<br>Allowed values: \["bug","gap","docs","friction","question","task","praise","idea"\] |
| /<wbr>properties/<wbr>candidates/<wbr>items/<wbr>properties/<wbr>component | Type: \["string","null"\] |
| /<wbr>properties/<wbr>candidates/<wbr>items/<wbr>properties/<wbr>matched\_evidence | Type: array |
| /<wbr>properties/<wbr>candidates/<wbr>items/<wbr>properties/<wbr>matched\_evidence/<wbr>items | Type: string<br>Allowed values: \["action","refusal","reference","code\_site"\] |
| /<wbr>properties/<wbr>masked | The credential forms the service masked in the filing: rotate each\.<br><br>Type: array |
| /<wbr>properties/<wbr>masked/<wbr>items | Type: string |
| /<wbr>properties/<wbr>personal\_removed | The personal details the platform removed from the report's words before storing it, each identified by its kind: an email address, a telephone number in international form, or a payment card number, in that order\. Empty where none was found\. The platform takes reasonable measures and guarantees nothing, so leave such details out of a report\.<br><br>Type: array |
| /<wbr>properties/<wbr>personal\_removed/<wbr>items | Type: string<br>Allowed values: \["email\_address","telephone\_number","card\_number"\] |
| /<wbr>properties/<wbr>stamped | True where the platform stamps your own refused call: the kind is `bug`; or the impact is `blocked`, the kind is neither `praise` nor `idea`, and the action is one of the target space's `critical_actions`\. False otherwise, including no matching call or reference\. A failed configuration read admits no critical action\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>repeat\_of | The issue a filing confirmed beside it, where one was given; absent where the answer reads `related`, where the filing itself already linked the report to that issue, and where the answer's `issue` is null\. On the platform's own space, for a credential that does not read the queue, it is the master where the issue given was merged as a duplicate; elsewhere it is the issue given\.<br><br>Type: string<br>Pattern: ^\#\[1\-9\]\[0\-9\]\*$ |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "required": [
      "source"
    ],
    "properties": {
      "source": {
        "type": "string",
        "enum": [
          "person",
          "agent",
          "system"
        ],
        "description": "Author: `agent` (you), `person` (dictated), or `system` (program). Only `agent` takes `provider` and `session`."
      },
      "provider": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9-]{0,31}$",
        "description": "AI provider name."
      },
      "session": {
        "type": "string",
        "maxLength": 200,
        "description": "Host session id; paired with `provider`."
      },
      "kind": {
        "type": "string",
        "enum": [
          "bug",
          "gap",
          "docs",
          "friction",
          "question",
          "task",
          "praise",
          "idea",
          "missing_capability",
          "documentation_gap",
          "refusal_not_understood",
          "problem",
          "error",
          "mistake",
          "usability"
        ],
        "description": "Required for filings; optional with `amends`, absent on confirmations; customer `question`/`task` refused."
      },
      "title": {
        "type": "string",
        "maxLength": 200,
        "description": "Required for filings; optional with `amends`; absent on confirmations and recovered marks."
      },
      "text": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 20000,
        "description": "Reporter's words, including dictated feedback. It carries no personal details: no names, email addresses, telephone numbers, or anything else that identifies a person."
      },
      "body": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 20000,
        "description": "Alias of `text`."
      },
      "impact": {
        "type": "string",
        "enum": [
          "blocked",
          "worked_around",
          "annoyed",
          "none"
        ],
        "description": "Effect on the reporter or the person described."
      },
      "severity": {
        "type": "string",
        "enum": [
          "critical",
          "high",
          "medium",
          "low"
        ],
        "description": "Maps to `impact`; see reference."
      },
      "workaround": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 4000,
        "description": "Workaround; null clears with `amends`."
      },
      "proposed_resolution": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 4000,
        "description": "Proposed fix; null clears with `amends`."
      },
      "labels": {
        "type": "array",
        "maxItems": 20,
        "items": {
          "type": "string",
          "maxLength": 64
        },
        "description": "Letters `a-z`, digits or `-_.:`; first a letter or digit."
      },
      "evidence": {
        "type": "object",
        "description": "Call identifiers.",
        "properties": {
          "action": {
            "type": "string",
            "maxLength": 200,
            "description": "Action name without `tzcloud_`."
          },
          "refusal": {
            "type": "string",
            "maxLength": 200,
            "description": "Refusal name."
          },
          "reference": {
            "type": "string",
            "maxLength": 200,
            "description": "Call's `reference`."
          },
          "code_site": {
            "type": "string",
            "maxLength": 200,
            "description": "Code location in the answer."
          },
          "environment": {
            "type": "string",
            "maxLength": 200,
            "description": "Build environment; recorded only with `version`."
          },
          "version": {
            "type": "string",
            "maxLength": 200,
            "description": "Build version; recorded only with `environment`."
          },
          "context": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "maxLength": 500
            },
            "maxProperties": 20,
            "description": "At most 20 short strings; keys: `a-z`, digits or `_`."
          }
        },
        "additionalProperties": false
      },
      "restricted": {
        "type": "boolean",
        "description": "Hides a security report from other reporters."
      },
      "problem_key": {
        "type": "string",
        "maxLength": 200,
        "description": "Your problem key."
      },
      "key": {
        "type": "string",
        "maxLength": 200,
        "description": "Alias of `problem_key`."
      },
      "repeat_of": {
        "type": "string",
        "pattern": "^#[1-9][0-9]*$",
        "description": "Repeated issue, e.g. `#92`."
      },
      "report": {
        "type": "integer",
        "minimum": 1,
        "description": "Report for `repeat_of`, not an issue."
      },
      "amends": {
        "type": "integer",
        "minimum": 1,
        "description": "Report to correct or withdraw."
      },
      "withdraws": {
        "type": "boolean",
        "description": "Withdraws the `amends` report; false reverses it."
      },
      "recovered": {
        "type": "boolean",
        "description": "Legacy recovered mark; see reference."
      },
      "files": {
        "type": "array",
        "minItems": 1,
        "maxItems": 4,
        "items": {
          "type": "object",
          "required": [
            "application",
            "area",
            "name"
          ],
          "properties": {
            "application": {
              "type": "string",
              "description": "Screenshot's app id."
            },
            "area": {
              "type": "string",
              "description": "Screenshot storage area."
            },
            "name": {
              "type": "string",
              "description": "Stored path within the area."
            },
            "environment": {
              "type": "string",
              "enum": [
                "development",
                "production"
              ],
              "description": "Upload environment; absent uses the app's deploy target."
            }
          }
        },
        "description": "Screenshots uploaded with `mint_upload_grant`: PNG/JPEG/WebP, at most 524,288 bytes each."
      },
      "space": {
        "type": "string",
        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
        "description": "Issue space UUID; absent for platform."
      },
      "product": {
        "type": "string",
        "enum": [
          "tzcloud",
          "tztrack",
          "tzmesh"
        ],
        "description": "Turn Zero product; absent for platform, MCP or your app's issues. In your space, only for that product."
      }
    },
    "x-renamed": {
      "application": "space",
      "environment": "space"
    },
    "x-retired": {
      "personal": "A report has no personal option: file it again without it, leaving out anything you want excluded.",
      "excerpt": "A report has no personal option: file it again without it, leaving out anything you want excluded."
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "issue",
      "outcome"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call's record row. Quote it when you report the call."
      },
      "report": {
        "type": "object",
        "description": "Your own report as filed: its `id`, the report's number; its origin; its text; its impact; its evidence and the basis of it (`stamped`, `confirmed`, or `claimed`); the builds it saw; and the images it carries. The service's other members of a report may appear beside them.",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1,
            "description": "The report's number, which you pass as `report` beside `repeat_of` to confirm a candidate."
          },
          "origin": {
            "type": "string",
            "enum": [
              "test",
              "beta",
              "field",
              "person",
              "workspace",
              "platform"
            ],
            "description": "Where the report came from, which the platform gives it and you do not set: `field` for a filing about the platform, `beta` for a company harness's, and on an application's own space `person`, `workspace`, or `test`."
          },
          "text": {
            "type": "string",
            "description": "What was attempted and what came back, as filed, the credential forms the service found masked."
          },
          "impact": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "blocked",
              "worked_around",
              "annoyed",
              "none",
              null
            ],
            "description": "What the problem cost, or null where the filing gave none."
          },
          "evidence": {
            "type": "object",
            "description": "The evidence as the report holds it: the action, the refusal, the reference, the code site, and the context, the action and the refusal read from the platform's own record where the reference identified one of your own calls."
          },
          "evidence_basis": {
            "type": "string",
            "enum": [
              "stamped",
              "confirmed",
              "claimed"
            ],
            "description": "`stamped` for your refused call on either ground: the kind is `bug`; or the impact is `blocked`, the kind is neither `praise` nor `idea`, and the action is critical in the target space. `confirmed` when the daily check verifies a refused or failed call and both report and issue kinds meet that rule for the platform space. `claimed` otherwise (MAPI-18)."
          },
          "seen_in": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "release_line",
                "version",
                "environment"
              ],
              "properties": {
                "release_line": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "version": {
                  "type": "string"
                },
                "environment": {
                  "type": "string"
                }
              }
            },
            "description": "The builds the report saw, each its release line or null, its version, and its environment."
          },
          "amends": {
            "type": [
              "integer",
              "null"
            ],
            "description": "On an amendment, the number of the report it amends; null on any other report."
          },
          "withdraws": {
            "type": "boolean",
            "description": "On an amendment, true where it withdraws the report it amends; false on any other report."
          },
          "attachments": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "media_type": {
                  "type": "string",
                  "enum": [
                    "image/png",
                    "image/jpeg",
                    "image/webp"
                  ]
                },
                "size_bytes": {
                  "type": "integer",
                  "minimum": 0
                },
                "sha256": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            },
            "description": "The images the report carries, each its `id`, its judged `media_type`, its size in `size_bytes`, and its `sha256`, `size_bytes` 0 and `sha256` null once it is removed. The platform serves no image; `relay_issue_act`'s `attachment` fetches one from your own space."
          }
        }
      },
      "issue": {
        "type": [
          "object",
          "null"
        ],
        "description": "On a filing, an amendment, or a confirmation: the issue the report is linked to, through the projection, or null on the platform's space where that issue is restricted and the credential does not read the queue. On the 0.2.0 recovered mark: the issue as that wire returns it to a credential that reads the queue or on a named space, and to any other credential its `id`, `status`, and `disposition` alone, or null.",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^#[1-9][0-9]*$"
          },
          "state": {
            "type": "string",
            "enum": [
              "new",
              "open",
              "waiting",
              "fixed",
              "closed"
            ]
          },
          "outcome": {
            "type": [
              "string",
              "null"
            ]
          },
          "sentence": {
            "type": "string"
          },
          "workaround": {
            "type": [
              "string",
              "null"
            ]
          },
          "note_to_reporters": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 2000,
            "description": "The note written for everyone who reported the issue, 1 to 2,000 characters, or null. The platform team writes a question or news there on any state, and a landed fix writes the line identifying its change. Through the projection, a landed fix's note is returned only while the issue is `fixed`, or `closed` `done` or `verified`, and a reader of the queue reads the note as it is. No filing sets it. On the platform's own space it is null where the note carries a statement or decision identifier, read by its form."
          },
          "live_in": {
            "type": [
              "object",
              "null"
            ],
            "description": "Always null in this filing answer, even if the fix is released. Call `read_feedback` to read the build the fix is live in."
          },
          "requirements": {
            "type": [
              "array",
              "null"
            ],
            "description": "The identifiers of the statements that design the behaviour, strings, where the issue closed as designed in a team's own space; null otherwise, and always null on the platform's own space."
          }
        }
      },
      "outcome": {
        "type": "string",
        "enum": [
          "filed",
          "linked",
          "retried",
          "noted",
          "confirmed",
          "related",
          "amended",
          "recovered",
          "repeated",
          "reopened"
        ],
        "description": "What the call did: `filed` a new issue, `linked` the report to an existing one, `retried` an earlier identical filing, `noted` praise, `confirmed` a candidate, `related`, or `amended` a report of your own; the 0.2.0 recovered mark returns that wire's words. The outcome reads `related` where `repeat_of` identifies an issue across the praise kind: nothing is linked, and the report keeps its own issue."
      },
      "candidates": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "issue": {
              "type": "string",
              "pattern": "^#[1-9][0-9]*$"
            },
            "title": {
              "type": [
                "string",
                "null"
              ]
            },
            "state": {
              "type": "string",
              "enum": [
                "new",
                "open",
                "waiting",
                "fixed",
                "closed"
              ]
            },
            "outcome": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "declined",
                "as_designed",
                null
              ]
            },
            "sentence": {
              "type": "string"
            },
            "workaround": {
              "type": [
                "string",
                "null"
              ]
            },
            "live_in": {
              "type": [
                "object",
                "null"
              ]
            },
            "summary": {
              "type": [
                "string",
                "null"
              ]
            },
            "kind": {
              "type": "string",
              "enum": [
                "bug",
                "gap",
                "docs",
                "friction",
                "question",
                "task",
                "praise",
                "idea"
              ]
            },
            "component": {
              "type": [
                "string",
                "null"
              ]
            },
            "matched_evidence": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "action",
                  "refusal",
                  "reference",
                  "code_site"
                ]
              }
            }
          }
        },
        "description": "Up to three issues the report may repeat: each title, summary, and workaround only where a trusted actor wrote them. Each carries its issue's `kind` and `component`, and `matched_evidence` lists the members of your report's `evidence` that equal those of the standing reports whose evidence chose that issue, empty where only your title's words matched. A candidate may be an issue closed `declined` or `as_designed`: its `outcome` and fixed `sentence` mean the request was considered and not taken, and filing it again does not reopen it. A candidate's `outcome` is null while its issue is not closed. On the platform's own space the list is empty except to the platform team, which links duplicates when it triages a report. A null `title` means the platform team has not written that issue's title. The report is already filed: confirm a candidate with `repeat_of` only where you know it is the same issue. Otherwise nothing more is needed, since the platform's triage proposes duplicates itself."
      },
      "masked": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "The credential forms the service masked in the filing: rotate each."
      },
      "personal_removed": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "email_address",
            "telephone_number",
            "card_number"
          ]
        },
        "description": "The personal details the platform removed from the report's words before storing it, each identified by its kind: an email address, a telephone number in international form, or a payment card number, in that order. Empty where none was found. The platform takes reasonable measures and guarantees nothing, so leave such details out of a report."
      },
      "stamped": {
        "type": "boolean",
        "description": "True where the platform stamps your own refused call: the kind is `bug`; or the impact is `blocked`, the kind is neither `praise` nor `idea`, and the action is one of the target space's `critical_actions`. False otherwise, including no matching call or reference. A failed configuration read admits no critical action."
      },
      "repeat_of": {
        "type": "string",
        "pattern": "^#[1-9][0-9]*$",
        "description": "The issue a filing confirmed beside it, where one was given; absent where the answer reads `related`, where the filing itself already linked the report to that issue, and where the answer's `issue` is null. On the platform's own space, for a credential that does not read the queue, it is the master where the issue given was merged as a duplicate; elsewhere it is the issue given."
      }
    }
  }
}
```

## Shared contracts

- [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)
