Feedback #

View this page as Markdown

On this page

Prompt:

That refusal made no sense to me. File it with the platform.

Also works:

  • "File feedback with Turn Zero describing what friction, gaps, or issues you found. Make suggestions on how they could improve their service."
  • "Report that the storage guide never says how big a transfer can be."
  • "Tell the platform we had to work around an unclear error."
  • "What happened to the report we filed yesterday?"

What your AI tool does #

Your AI tool does each of these with no browser approval:

  • Files a report with submit_feedback. The report is the tool's own, or yours when you dictated it and the tool works under your signed-in session. It attaches the evidence: the action, the refusal name, and the refusal's reference.
  • Files one whenever something got in its way: an unexpected refusal, a workaround it needed, a missing capability, or a missing page. The platform welcomes these reports.
  • Quotes nothing of your own content and puts no personal details in a report. The text says what was attempted and what came back.
  • Reads a report's status later with read_feedback, by the id the filing returned. Once the platform says the fix is live, it tries the refused call again.
  • Adds to a report you filed, or answers a question the platform asked about it, by calling submit_feedback again with the same problem_key and the new text. The filing joins the same issue as a further report. A reporter has no comment action on the platform's space, so its reports are the channel.
  • Corrects or withdraws a report you filed by calling submit_feedback with amends, the report's number, and the corrected words, or withdraws: true (step 3).

What you need #

  • The refusal you want to report, exactly as your AI tool showed it to you. A management action's refusal includes a ten-character reference code. Keep a copy of it.

Before your AI starts #

For the AI tool: Check the following before starting.

  • A signed-in session in your connected tool, or an account-scoped minted token (Connect your AI assistant). A token scoped to one application is refused token_scope_refused on every feedback action. That application's backend reaches its own issue space through the egress gateway instead.
  • The refused call's action, refusal name, and reference, read from the refusal itself.

Steps #

The platform keeps feedback as issues and reports. An issue records one problem. A report is one filing about an issue, in the filer's own words, and is never edited. Several reports can belong to one issue.

The platform's issue service stores issues in issue spaces. Unless you name another space, your reports go to the platform's own space, where the platform team reads them.

1. File a report #

A report carries no personal details: no names, email addresses, telephone numbers, or anything else that identifies a person. Leave out of a report anything you do not want us to have, or do not file the report. Your AI coding tools quote nothing of yours in a report of their own. The names of actions, refusals, applications, and files are not personal details.

Call submit_feedback. In this example, the tool files its own report about a refused deploy and copies the evidence from the refusal. The reference is an invented example of its form.

{
  "source": "agent",
  "kind": "bug",
  "title": "deploy refused health_path_unserved although server.mjs answers /health",
  "text": "Called deploy for a new application. The refusal said no source file names the health path's last segment, but server.mjs at the zip's root answers GET /health.",
  "impact": "worked_around",
  "workaround": "Moved the health route into a file named health.mjs.",
  "evidence": { "action": "deploy", "refusal": "health_path_unserved", "reference": "3f9c2a7b1d" }
}

The members submit_feedback takes:

Member What it contains
source Required. agent for the tool's own filing, person for a report you dictated, or system for a program's filing. Only your signed-in session can file as a person. Under a minted token, person is filed as agent, with the same origin as an agent's filing.
provider, session Optional, for agent: the tool's provider name and its session id. Give both or neither.
kind Required. Use bug, gap for a capability you needed and could not find, docs for a missing or wrong page, friction for something that works but is hard, or praise. Use idea for a suggestion. The aliases missing_capability, documentation_gap, refusal_not_understood, problem, error, mistake, and usability are also accepted.
title Required. Up to 200 characters.
text Optional. What was attempted and what came back, with no personal details, up to 20,000 characters.
impact Optional. What the problem cost you: blocked, worked_around, annoyed, or none.
workaround Optional. What you did to get past it, up to 4,000 characters.
proposed_resolution Optional. The fix you would suggest, up to 4,000 characters.
evidence Optional. action, refusal, reference, code_site, and a context of up to 20 short strings under keys of lowercase letters, digits, and underscores. The older environment and version give the build you saw. Any other member is refused. The refusal gives the members evidence takes or, for a long list, their count and the action's reference page.
labels Optional. Up to 20 short lowercase labels. The label synthetic marks the platform’s own test reports. Without space, it is refused invalid_request unless your account is synthetic. On a space you name, it is an ordinary label.
restricted Optional. true for a security concern. A reporter's read, such as read_feedback on the platform's space, then never returns the issue to any other reporter.
problem_key Optional. Your own name for the problem. A later filing with the same name and different words adds a report to the same issue. One whose words and evidence both match the earlier report's is answered retried and adds nothing. Praise is the exception: praise and a report of another kind under the same name go to separate issues. If you leave it out, the platform makes one from the kind, the title, and the evidence's action and refusal.
files Optional. Up to 4 screenshots, each a PNG, JPEG, or WebP file of at most 524,288 bytes that you stored first. Each names its application, area, name, and environment. A missing environment means the application's deploy target.

To attach a screenshot, store it first. Call mint_upload_grant for an application of your account and an area bound to it, run the put line it returns, and name the stored file in files. The put line is the one-line command that uploads the file.

Before it files anything, the platform reads each file under your own sign-in or token. If it cannot find a file, or a file is larger than 524,288 bytes, the call is refused and nothing is filed. The image is stored with your report as you sent it, and no page of the platform shows it.

submit_feedback refuses question and task from a customer. An operator-granted Contributor uses the tzTrack tools for the group's tasks, as Testing with a granted group explains.

The response contains your report as filed, the issue it belongs to, and an outcome:

  • filed: a new issue was opened for it.
  • linked: the report joined an existing issue.
  • retried: the same filing arrived again, and nothing changed.
  • noted: praise, recorded and closed at once.
  • confirmed: you called again with report and repeat_of, and your report now belongs to the issue you named (step 3). On the platform's own space, where that issue was merged as a duplicate, your report belongs to its master instead. The master is the issue the duplicate was merged into.
  • amended: you called with amends, and your correction or withdrawal was filed as a further report beside the one it amends (step 3).
  • related: you sent repeat_of, and one of the two is praise and the other is not. Nothing is joined. Your report stays on its own issue, which the response returns as issue. The two issues are marked related unless either is restricted. No member of the response names that relation.

The filing answer's issue.live_in is null even if the fix is released; read the build with read_feedback in step 2.

On the platform's own space, candidates is an empty list. The platform team links your report to any issue it repeats when the team triages it, that is, reads and sorts it. issue is null when your report belongs to a restricted issue, including when your own filing set restricted. Your report and the outcome are still returned. masked lists the kinds of credential the service found in your text and hid. Replace each of those credentials with a new one.

personal_removed lists the kinds of personal detail the platform removed from your report before storing it: email_address, telephone_number, or card_number, in that order. Each detail is replaced by a mark, such as [email address removed], and the list is empty when nothing was removed. What is kept says where each kind is removed.

2. Read its status #

To read your submission in the platform's space, call read_feedback with issue set to the id the filing returned. Leave out space. The id below is an example.

{ "issue": "#4127" }

On the platform's space, the response shows the issue as a reporter sees it:

  • its state: new, open once it has been triaged, waiting while it needs something before it can move on, fixed once the change that fixes the issue lands, or closed;
  • its outcome once closed, such as verified, done, as_designed, declined, or duplicate;
  • a one-sentence sentence that describes the state and outcome in words;
  • the workaround, when the platform team wrote one;
  • the note_to_reporters, a message written for everyone who reported the issue, or null. In it, the platform team asks a question or gives news, in any state. On the platform's own space, a note that carries a rule code, a decision number, or any code written the same way is held back and reads null. Such a code is capital letters, a hyphen, and a number. A note in plain words is shown. When a fix lands, its note gives the landing's time and commit. That note shows while the issue is fixed, or closed done or verified;
  • live_in, the build the fix is live in, or null if no released build carries the fix yet;
  • your own reports on it, and never another reporter's words.

What changed also lists, by issue number, the reported fixes each release carried, a restricted issue excepted. Find your issue's number there, then read its state with read_feedback.

Reading a report another account filed is refused not_found. So is reading an issue number someone quotes to you that differs from the id submit_feedback returned to you. If one of your own reports joined that issue, the refusal may name your own submission for it. Call read_feedback with that id to read it. The refusal only ever names an issue you can read. For another account's issue, a restricted issue, or a number no issue has, it names nothing, so all three look the same.

Call read_feedback with no argument to list your own submissions. Add state to list only one state, or query to search your own reports' titles and texts, never the issue's title or summary. For paging with limit and cursor, follow the paging instructions below. Each list entry gives id, state, and outcome. Its title, when present, comes from your latest visible report that has one, never another reporter's report or the master issue's title.

Pass detail: true with a list or search to read its full entries within your existing access. To read one submission in full, pass its issue id and leave out detail. Nothing is deleted when the state moves, and a closed issue stays readable.

3. Add to a report, correct or withdraw it, or join it to an issue #

To add to a report you filed, or answer the platform's question about it, call submit_feedback again with the same problem_key and new text. It joins the same issue as a further report. The question appears in note_to_reporters. If the team awaits your answer, the filing returns the issue to its queue. These feedback calls provide no comment or task-work action.

To correct a report you filed, call submit_feedback with amends set to the report number from the filing response. Send the fields to correct. You can include kind, labels, and product as well as title, text, impact, workaround, or proposed_resolution. Use the same kind values as for a new report. A report about the platform cannot use question or task. To withdraw a report filed in error, send withdraws: true with amends. The example below withdraws report 57, an invented number.

{ "source": "agent", "amends": 57, "withdraws": true, "text": "Filed against the wrong application." }

The correction is filed as a further report beside the one it amends. The first report stays as you filed it, and the platform team reads the two side by side. The correction joins every issue the first report belongs to at that moment, and the response's outcome reads amended.

If you omit kind, title, text, impact, workaround, or proposed_resolution, the amendment uses that field from the latest amendment that did not withdraw the report. If there is none, it uses the original. A withdrawal with no impact has none. Send null to clear text, workaround, or proposed_resolution. An empty string clears text too. Evidence stays on the original report.

If you send labels or product, include every filing label you want to keep. product adds product:<name> to the list you send in labels. If you send only product, that list contains only the product label. This list replaces the filing labels on the issue your original report opened. If the platform team has set that issue's labels, its list stays in place.

A withdrawal changes nothing by itself. The platform team reads it and settles the issue. Send withdraws: false to take back a withdrawal. An amendment refuses evidence, problem_key, restricted, report, repeat_of, and files with invalid_request. Amending a report another account filed returns HTTP 404 (not_found), just like a report number that does not exist.

When you know which issue your report repeats, such as the issue an earlier report of yours belongs to, you can join the report to it. Call submit_feedback again with report set to your report's number and repeat_of set to that issue's id. A new filing can also name repeat_of directly, which adds it to that issue as a further report.

A new filing's response then carries repeat_of where the platform joined your report to that issue on this call. If the platform had already linked the report to that issue when it was filed, the response carries no repeat_of. If one of the two is praise and the other is not, your report keeps its own issue, the outcome reads related, and the response carries no repeat_of.

On the platform's own space, repeat_of can name only an issue that holds one of your own reports. There, an issue merged as a duplicate counts as its master: your report joins the master, and the response's issue and any repeat_of give the master. A repeat_of that names a restricted issue, an issue that holds none of your reports, or no issue at all is refused 404 not_found. The lookup counts against read_feedback's per-minute limit. The report is still filed: send the same call without repeat_of to get it back.

Testing with a granted group #

Turn Zero's operator may grant a test group access to the company's feedback space. Find it through list_issue_spaces or tztrack_list_spaces; no space ID needs handing over. Each row gives level, its name in role, restricted, the group's accounts, admitted actions and owner, which is null there.

Viewer (view) reads, Reporter (report) also files, and Contributor (contribute) also works tasks the group opened. Use the tzTrack tools for that task work: file a task, update it, close it with an outcome its state permits, except duplicate, and reopen it. submit_feedback remains findings-only and refuses a task.

The grant reads only the group's reports, never restricted issues or another account's titles, comments or counts. An issue outside that group is treated as one that does not exist. Other calls, including cache, relation changes and export, refuse grant_required. Each bounded filing creates a new issue, without joining it to an existing one. The company replies through the task's note to reporters because the company's comments stay hidden.

Only the operator's grant sets membership in that space; share_space cannot share it. Ordinary feedback reads described above remain limited to your own submissions. Sharing a space explains the five role names and account bounds.

Known issues in a refusal #

A refusal can point to a known issue. When the platform team already knows about a refusal you receive, its detail ends with a sentence that gives the issue and any workaround. Once the fix is released, that sentence gives the build that includes it.

What the platform adds to a report #

When your evidence quotes the reference of one of your own calls, the platform reads its own record of that call. It stamps a report about a refused or failed call 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 space you file into lists as critical.

It adds the action, the refusal, the place in its code that returned it, and the build that handled the call. The response contains stamped: true, and the evidence is marked stamped. The platform can match the report to others with the same cause, without anyone reading its text.

A report that meets neither ground is not stamped. A report about a call that succeeded or was held for your approval is not stamped either. The platform still adds the action and the build. The response says stamped: false, and the evidence is marked claimed. The record's values replace any refusal or code_site you wrote. A report about a refused call that meets neither ground carries the record's refusal and no code site. The platform never matches such a report to another only because both mention the same call.

The platform can find a call for 25 days after it was made. A reference it cannot find under your account stays as you wrote it, marked claimed. The day after you file, the platform checks a claimed reference again.

A report is marked confirmed only when it names the refusal and its reference quotes a call refused or failed under your account in the 24 hours before you filed. Both the report's kind and its issue's kind must also pass this test:

  • bug; or
  • neither praise nor idea, with the report's impact blocked and the action listed as critical in the platform's issue space.

Otherwise the report stays claimed, and nothing else about it changes. An old report with no kind uses its issue's kind.

A blocked report with stamped or confirmed evidence about a critical action can reach priority 1 without waiting for a triage pass. That rule acts on a bug, friction, gap, or docs issue that is not closed and that the report opens or joins by its fingerprint. It never changes a priority that a person or a session set. Repeating your own report under its problem key sets no priority by that rule.

A refusal that includes a reference also includes help, the address of its row in the refusals reference. Read its cause and remedy there before you file. Over MCP (Model Context Protocol, the connection your AI tool uses to call the platform), a refused result includes a second content block. That block gives the refusal and its reference, so your AI tool can copy them.

What happens to a report after it is filed #

The platform's triage passes read new reports with an AI model every five minutes. They record the issue's kind, the part of the platform it concerns, and its priority. They link a report to an issue it repeats, and merge duplicates where the platform's own records support the match. A report whose text reads as an instruction to whoever reads it is left for a person. Neither pass deletes a report or changes its text. The platform team also settles issues by hand. Your report's issue shows what was decided, whether by the passes or by a person.

A fixed issue closes as verified once the fix has been used. The platform counts calls of the same action that completed on a build that includes the fix, and your AI tool's retry is one of them. After a platform incident closes, the next daily pass files an issue for it. It links each report made while the incident was open, up to a limit. What the triage passes do describes the passes in full. They also run in your own spaces whose settings turn them on.

What is kept #

A report is kept as the platform's own record of the problems people meet when they build on it. It identifies the account that filed it. What you file becomes the platform's to keep and use, as the terms of service say.

Before a report is stored, the platform takes reasonable measures to remove confidential details that someone pastes into it: email addresses, telephone numbers in international form, and payment card numbers. It does not guarantee that every such detail is removed. The rest of the text stays as written, including where it identifies you, so keep personal details out of it, as step 1 asks.

Where each kind is removed:

  • Email addresses and telephone numbers are removed from the report's title, text, workaround, proposed resolution, and the technical details your AI tool attaches in each evidence context value.
  • A payment card number is removed from the report's words alone. A context value keeps it, because the technical details hold the identifiers a fix needs, and a long number among them can look like a card number.
  • The action, the refusal, the reference, and the code site in the evidence are never changed.

An image you attach is stored exactly as you sent it, because the platform cannot find personal details in an image, so crop out or leave out anything you do not want kept.

When the account is deleted, the account's identity is erased from every report it filed. No report is deleted, and each keeps its text as written.

The platform's triage passes read report text with an AI provider under the platform's own key. The privacy page lists who receives the text and how long it is kept.

Your own issue spaces #

Your account can have issue spaces of its own. Each stores issues and reports the same way the platform's own space does, for a repository's issue list or a program's test results. Every account has the tzTrack access needed to create one, mint its token, and work it through relay_issue_act. Keep your own issue list covers that task: the space, its token's grant levels, the operations the relay passes on, and how its issues get their priority.

Your AI tool lists tztrack_create_space and tztrack_share_space. A program calls relay_issue_act under the space's issues token; the AI tool's sign-in connection does not list that call. The feedback actions and list_issue_spaces stay listed too, so your applications' own spaces stay within reach.

Feedback in your application's space #

Let your app's users send feedback adds a form and a backend route, then reads the reports through your AI tool. Start there to add feedback to your app.

An application that declares the issue_tracking service in its manifest has a space of its own. Its backend files its users' reports there through the Issue Tracking client. That page describes the space: how reports are stamped with their environment and version, the build records, and what a deletion removes. Bind an application to the space binds the application to a space of your account instead.

Your backend uses its application's own space at the report grant level, so the responses it receives leave out every restricted issue. No deployment reads those restricted issues.

Your account's read_feedback call with space lists and reads restricted issues too. Reading one issue returns it whole, including every reporter's reports. Calling relay_issue_act under an owner token for that space is another way to read it.

The feedback actions can act on that space when you name it in space, with the id the response of submit_manifest gives. They can also act on any one space of an application that keeps a space for each environment, and a space your account owns.

  • submit_feedback files into that space as your account's own actor.
  • read_feedback lists the space's issues, reads one with issue, or selects a list with queue: true (Reading the queue).
  • settle_feedback settles one of its issues, or triages one by setting its kind or component.

None of them needs a grant.

To list the space, call read_feedback with space. Without query, it lists issues newest first, in every state; add state to select one. Add query to search the issue's title, summary and reports for any word of the query. Search results sort by relevance, then newest first. A search also takes state, kind and component. Lists and searches also take reporter_accounts: 1 to 20 recorded reporter account IDs. Each issue appears once when a report the call can already read was recorded under one of those accounts. The filter only narrows what you can read.

Lists and searches return compact entries by default. Each gives id, kind, title, state, outcome, priority, effective_priority, waiting_for, report_count, updated_at and restricted, where the issue has them. restricted tells you whether the issue is restricted. updated_at dates the latest change, not a filing.

Add detail: true for full issue entries, including created_at and last_reported_at. To read an issue with its reports, pass space and issue, leaving out detail and queue. The platform-space restriction to your own reports in step 2 does not apply to this owner read.

For each list or search, limit sets the page size from 1 to 100, with 50 as the default. Pass the answer's cursor in the next call to read the next page. A null cursor means there is no next page.

A filing that names a space returns up to three existing issues your report may repeat, as candidates. Each has its id, its state, and any workaround a trusted actor wrote. A candidate's title is null in three cases: a report other than the platform team's own gave it, the platform team has not yet reviewed the issue, or a triage pass wrote the title.

Each candidate also carries the issue's kind and component, and its summary where a trusted actor wrote one. Its matched_evidence names the members of your evidence, such as action or code_site, that equal those of the existing reports whose evidence chose the issue, and none where only your title's words matched.

A candidate can be an issue closed declined or as_designed. Its outcome and its sentence, such as "Not taken.", mean the request was considered and not taken. Filing it again does not reopen it. A candidate's outcome is null while its issue is not closed.

A candidate with a null title asks nothing of you, because your report is already filed. Confirm a candidate with repeat_of only where you know it is the same issue. Otherwise nothing more is needed: the triage passes look for duplicates themselves.

All three actions refuse a token scoped to an application with token_scope_refused. That application's backend uses the space through the gateway at its grant level. A request that passes application or environment is refused invalid_request, and the refusal gives space. Pass the space in space instead. A space your account does not have is refused not_found before any credential is read, whoever has it.

The platform measures each space's stored bytes without reading any record's content. That measurement counts against no account or application limit. No charge applies to an issue space's stored data. Your account's export includes only your account's own filings in each space, not the records your end users filed there.

To keep those records before you delete the application, export the space with the export operation of relay_issue_act under an owner token for that space (Keep your own issue list). That token requires tzTrack access. Without it, or where the application keeps a space for each environment, read the space with read_feedback instead. Read its issues page by page, then each issue's reports with issue. Deletion and copies says what a deletion removes.

Expected result #

submit_feedback returns 200 with your report, an issue whose state is new or open, an outcome of filed, and a reference for the call itself. read_feedback with that issue's id returns the same issue with your report on it.

Over MCP, read_feedback, submit_feedback, settle_feedback, and relay_issue_act each return one block. The block opens with a marker that says its content is untrusted. The JSON stands between two delimiter lines, because the text inside is what reporters wrote.

list_issue_spaces also returns one such block, under a marker of its own, when it lists a space another account shares with you, because that space's name is text its owner wrote. If the list contains only spaces your account owns, application spaces, or the platform space, Cloud returns plain JSON. Cloud marks the result as untrusted if it cannot classify the listing. Every other call returns a JSON block.

Refusals #

See the refusals reference for other platform errors.

A refusal gives the action and its cause in detail. It files no report. The platform's record of the call keeps the refusal and its reference. Keep your own issue list lists the refusals of the issue-space actions.

Refusal Status Cause Remedy
invalid_request 400 A member breaks the rules in step 1, a file in files holds more than 524,288 bytes, or the request passed application or environment. detail gives the member to correct. Correct the named member and call again. Name a space in space.
feedback_rate_limited 429 A limit was passed: the account's share in a minute, a space's limit, the platform's cap, or the issue service's own rate limit. detail says which. Wait until the next minute starts, then repeat the call with the same key. The platform reads it as a retry, never as a second report.
issue_service_unreachable 503 The platform's issue service did not respond. detail gives the cause in one word. Repeat the call after a short wait with the same key.
not_found 404 read_feedback named a submission that is not the account's own, or space matches no space your account has. A filing's files names a file that your call cannot read. Use the submission detail names, where it names one, or an id from read_feedback with no argument. For a space, use the identifier that submit_manifest or list_issue_spaces returns.
grant_required 403 read_feedback with queue, or settle_feedback, was called on the platform's space. Only platform staff can do that, under the feedback_queue grant. Call read_feedback without queue for your own submissions, or name your space.
token_scope_refused 403 The call came under a token scoped to one application, which no feedback action accepts. Use the session or an account-scoped token. The application's backend reaches its space through the gateway.
not_yet_provisioned 501 The platform you reached runs no issue service, which every feedback action needs. So the actions are missing from your AI tool's list of actions. Nothing on your side fixes this. Email support@turnzero.ai with the action, refusal name, and reference from the refused call.

For what you can share with the support agent, read What Turn Zero support can see.