submit_feedback #
On this page
Generated automatically from the published 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).
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 #
{
"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 #
{
"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 Required fields: ["source"] Replaced members: application and environment were replaced by space Retired members: personal and excerpt: A report has no personal option: file it again without it, leaving out anything you want excluded. |
| / |
Author: agent (you), person (dictated), or system (program). Only agent takes provider and session.Type: string Allowed values: ["person","agent","system"] |
| / |
AI provider name. Type: string Pattern: ^[a-z][a-z0-9-]{0,31}$ |
| / |
Host session id; paired with provider.Type: string Maximum length: 200 |
| / |
Required for filings; optional with amends, absent on confirmations; customer question/task refused.Type: string Allowed values: ["bug","gap","docs","friction","question","task","praise","idea","missing_capability","documentation_gap","refusal_not_understood","problem","error","mistake","usability"] |
| / |
Required for filings; optional with amends; absent on confirmations and recovered marks.Type: string Maximum length: 200 |
| / |
Reporter's words, including dictated feedback. It carries no personal details: no names, email addresses, telephone numbers, or anything else that identifies a person. Type: ["string","null"] Maximum length: 20000 |
| / |
Alias of text.Type: ["string","null"] Maximum length: 20000 |
| / |
Effect on the reporter or the person described. Type: string Allowed values: ["blocked","worked_around","annoyed","none"] |
| / |
Maps to impact; see reference.Type: string Allowed values: ["critical","high","medium","low"] |
| / |
Workaround; null clears with amends.Type: ["string","null"] Maximum length: 4000 |
| / |
Proposed fix; null clears with amends.Type: ["string","null"] Maximum length: 4000 |
| / |
Letters a-z, digits or -_.:; first a letter or digit.Type: array Maximum items: 20 |
| / |
Type: string Maximum length: 64 |
| / |
Call identifiers. Type: object Additional properties: false |
| / |
Action name without tzcloud_.Type: string Maximum length: 200 |
| / |
Refusal name. Type: string Maximum length: 200 |
| / |
Call's reference.Type: string Maximum length: 200 |
| / |
Code location in the answer. Type: string Maximum length: 200 |
| / |
Build environment; recorded only with version.Type: string Maximum length: 200 |
| / |
Build version; recorded only with environment.Type: string Maximum length: 200 |
| / |
At most 20 short strings; keys: a-z, digits or _.Type: object maxProperties: 20 |
| / |
Type: string Maximum length: 500 |
| / |
Hides a security report from other reporters. Type: boolean |
| / |
Your problem key. Type: string Maximum length: 200 |
| / |
Alias of problem_key.Type: string Maximum length: 200 |
| / |
Repeated issue, e.g. #92.Type: string Pattern: ^#[1-9][0-9]*$ |
| / |
Report for repeat_of, not an issue.Type: integer Minimum: 1 |
| / |
Report to correct or withdraw. Type: integer Minimum: 1 |
| / |
Withdraws the amends report; false reverses it.Type: boolean |
| / |
Legacy recovered mark; see reference. Type: boolean |
| / |
Screenshots uploaded with mint_upload_grant: PNG/JPEG/WebP, at most 524,288 bytes each.Type: array Minimum items: 1 Maximum items: 4 |
| / |
Type: object Required fields: ["application","area","name"] |
| / |
Screenshot's app id. Type: string |
| / |
Screenshot storage area. Type: string |
| / |
Stored path within the area. Type: string |
| / |
Upload environment; absent uses the app's deploy target. Type: string Allowed values: ["development","production"] |
| / |
Issue space UUID; absent for platform. Type: string Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ |
| / |
Turn Zero product; absent for platform, MCP or your app's issues. In your space, only for that product. Type: string Allowed values: ["tzcloud","tztrack","tzmesh"] |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","issue","outcome"] |
| / |
Required value: 1 |
| / |
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. Type: string Pattern: ^[0-9a-f]{10}$ |
| / |
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.Type: object Required fields: ["id"] |
| / |
The report's number, which you pass as report beside repeat_of to confirm a candidate.Type: integer Minimum: 1 |
| / |
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.Type: string Allowed values: ["test","beta","field","person","workspace","platform"] |
| / |
What was attempted and what came back, as filed, the credential forms the service found masked. Type: string |
| / |
What the problem cost, or null where the filing gave none. Type: ["string","null"] Allowed values: ["blocked","worked_around","annoyed","none",null] |
| / |
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. Type: object |
| / |
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.Type: string Allowed values: ["stamped","confirmed","claimed"] |
| / |
The builds the report saw, each its release line or null, its version, and its environment. Type: array |
| / |
Type: object Required fields: ["release_line","version","environment"] |
| / |
Type: ["string","null"] |
| / |
Type: string |
| / |
Type: string |
| / |
On an amendment, the number of the report it amends; null on any other report. Type: ["integer","null"] |
| / |
On an amendment, true where it withdraws the report it amends; false on any other report. Type: boolean |
| / |
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.Type: array |
| / |
Type: object |
| / |
Type: string |
| / |
Type: string Allowed values: ["image/png","image/jpeg","image/webp"] |
| / |
Type: integer Minimum: 0 |
| / |
Type: ["string","null"] |
| / |
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.Type: ["object","null"] |
| / |
Type: string Pattern: ^#[1-9][0-9]*$ |
| / |
Type: string Allowed values: ["new","open","waiting","fixed","closed"] |
| / |
Type: ["string","null"] |
| / |
Type: string |
| / |
Type: ["string","null"] |
| / |
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.Type: ["string","null"] Minimum length: 1 Maximum length: 2000 |
| / |
Always null in this filing answer, even if the fix is released. Call read_feedback to read the build the fix is live in.Type: ["object","null"] |
| / |
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. Type: ["array","null"] |
| / |
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.Type: string Allowed values: ["filed","linked","retried","noted","confirmed","related","amended","recovered","repeated","reopened"] |
| / |
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.Type: array |
| / |
Type: object |
| / |
Type: string Pattern: ^#[1-9][0-9]*$ |
| / |
Type: ["string","null"] |
| / |
Type: string Allowed values: ["new","open","waiting","fixed","closed"] |
| / |
Type: ["string","null"] Allowed values: ["declined","as_designed",null] |
| / |
Type: string |
| / |
Type: ["string","null"] |
| / |
Type: ["object","null"] |
| / |
Type: ["string","null"] |
| / |
Type: string Allowed values: ["bug","gap","docs","friction","question","task","praise","idea"] |
| / |
Type: ["string","null"] |
| / |
Type: array |
| / |
Type: string Allowed values: ["action","refusal","reference","code_site"] |
| / |
The credential forms the service masked in the filing: rotate each. Type: array |
| / |
Type: string |
| / |
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. Type: array |
| / |
Type: string Allowed values: ["email_address","telephone_number","card_number"] |
| / |
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.Type: boolean |
| / |
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.Type: string Pattern: ^#[1-9][0-9]*$ |
Complete payload contract #
{
"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: every refusal, by surface, with its cause and its remedy
- schemas/wire_error.schema.json
- schemas/wire_errors.json
- schemas/action_payloads.json (includes shared shapes)
- management_api_contract.md