submit_feedback
Generated automatically from the published contract sources.
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.
A script calls this action over HTTPS at POST https://turnzero.ai/api/v1/actions/submit_feedback, with a bearer credential and the action's payload as the JSON body.
Contract description
File feedback about the platform into its own issue service: a refusal you did not expect, a capability you had to work around, a page you could not find, a bug, praise.
`source` is `agent` for your own filing, with your `provider` and `session`, or `person` for a report the person dictated. The `kind` is `bug`, `gap`, `docs`, `friction`, or `praise`. Give a `title`, a `text` that says what was attempted and what answered, the `impact` it had on you, and any `workaround` you used. Give an `evidence` member naming the action, the refusal, and its `reference`, the ten-character code a management action's refusal carries; for a `bug` the platform stamps the rest from its own record of the call.
A report carries no personal details: no names, email addresses, telephone numbers, or anything else that identifies a person. Quote nothing of the person's content unless they file it themselves.
A repeat with the same `problem_key` adds a report to the same issue. The answer carries your report, the issue's state, and up to three `candidates` you may be repeating: confirm one by calling again with `report` and `repeat_of`. With `space`, the identifier of an issue space your account holds, the report files into that space as the account's own actor. The rest is on the page /cloud/reference/actions/submit-feedback/, which `read_documentation` reads as `page` and the platform's origin serves.
More about this action
The actor's identifier is the acting account's. The `kind` words are `bug`, `gap`, `docs`, `friction`, `question`, `task`, and `praise`, or a 0.2.0 word still read: `missing_capability`, `documentation_gap`, `refusal_not_understood`, or `usability`.
Where the `evidence` member's reference names one of your own calls that was refused and the kind is `bug`, the platform stamps the action, the refusal, the code site, and the build from its own record. Where that call was answered, or the report is of another kind, it writes the action and the build and leaves the evidence claimed.
Absent a `problem_key`, the service derives one from the kind, the title, and the evidence's action and refusal. Beside a filing, `repeat_of` confirms it at once, and with `report` alone it confirms an earlier filing. The confirmation links the report that `report` names to the named issue. With `space`, the filing goes into that space under its own token, the actor the acting account's.
Access and action metadata
{
"name": "submit_feedback",
"resource": "account",
"tier": "reversible",
"admits": [
"synthetic_estate"
],
"summary": "File a report into the platform's own space of the issue service as the caller's own actor, under any bearer or account-scoped minted token, a token the synthetic_estate grant bounds among them: `source` names the actor's kind, `person`, `agent`, or `system`, an agent naming its `provider` and `session`; `kind` is one of the record's seven kinds or the 0.2.0 words still accepted, with a `title`, an optional `text` (or `body`), `impact` (or `severity`), `workaround`, `proposed_resolution`, `labels`, `restricted`, and an `evidence` member naming 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 names one of the caller's own refused calls and the kind is `bug`, the platform stamps the action, the refusal, the code site, and the build from its own record and marks the evidence stamped. A call that was answered, or a filing of another kind, gives the action and the build and leaves the evidence claimed. `problem_key` (or `key`) names the problem among the caller's own reports, a repeat with new evidence filing a new report linked to the same issue. The answer carries the caller's own report, the issue through the projection, the outcome (`filed`, `linked`, `retried`, or `noted`), 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. 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 answers `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`, naming an issue space the acting account holds, the filing goes into that space: a space of the account's own, an application's own space, or one space of an application's per-environment pair. An identifier naming no such space is answered `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": false,
"openWorldHint": false
}
}
MCP catalog entry
{
"name": "submit_feedback",
"tier": "reversible",
"scenario": "CHI-L0-14",
"summary": "File feedback about the platform into its own issue service: a refusal you did not expect, a capability you had to work around, a page you could not find, a bug, praise.\n\n`source` is `agent` for your own filing, with your `provider` and `session`, or `person` for a report the person dictated. The `kind` is `bug`, `gap`, `docs`, `friction`, or `praise`. Give a `title`, a `text` that says what was attempted and what answered, the `impact` it had on you, and any `workaround` you used. Give an `evidence` member naming the action, the refusal, and its `reference`, the ten-character code a management action's refusal carries; for a `bug` the platform stamps the rest from its own record of the call.\n\nA report carries no personal details: no names, email addresses, telephone numbers, or anything else that identifies a person. Quote nothing of the person's content unless they file it themselves.\n\nA repeat with the same `problem_key` adds a report to the same issue. The answer carries your report, the issue's state, and up to three `candidates` you may be repeating: confirm one by calling again with `report` and `repeat_of`. With `space`, the identifier of an issue space your account holds, the report files into that space as the account's own actor. The rest is on the page /cloud/reference/actions/submit-feedback/, which `read_documentation` reads as `page` and the platform's origin serves.",
"owners": [
"PLD-L0-40"
]
}
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, and leave out of it anything you do not want kept. |
| / |
The kind of actor filing: `person`, a report the person made; `agent`, the assistant's own; `system`, a program's or a company harness's. Type: string Allowed values: ["person","agent","system"] |
| / |
An agent's provider, 1 to 32 lowercase letters, digits, and hyphens opening with a letter; with `session`, both or neither. Type: string Pattern: ^[a-z][a-z0-9-]{0,31}$ |
| / |
An agent's session identifier, 1 to 200 printable characters; with `provider`, both or neither. Type: string Maximum length: 200 |
| / |
The filing's kind, required on a filing. A `question` or a `task` is refused from a customer's report. Type: string Allowed values: ["bug","gap","docs","friction","question","task","praise","missing_capability","documentation_gap","refusal_not_understood","usability"] |
| / |
The filing's title, 1 to 200 characters; required on a filing. Type: string Maximum length: 200 |
| / |
What was attempted and what answered, in your own words. It carries no personal details: no names, email addresses, telephone numbers, or anything else that identifies a person. Type: string Maximum length: 20000 |
| / |
The 0.2.0 name of `text`; never beside it. Type: string Maximum length: 20000 |
| / |
What the problem cost you. Type: string Allowed values: ["blocked","worked_around","annoyed","none"] |
| / |
The 0.2.0 word read as an impact; never beside `impact`. Type: string Allowed values: ["critical","high","medium","low"] |
| / |
What you did to get past it. Type: string Maximum length: 4000 |
| / |
The fix you propose. Type: string Maximum length: 4000 |
| / |
At most 20 labels, each 1 to 64 lowercase letters, digits, hyphens, underscores, periods, and colons opening with a letter or a digit. Type: array Maximum items: 20 |
| / |
Type: string Maximum length: 64 |
| / |
What the report is about: the action, the refusal name, the reference the refusal or the answer carried, the code site, and the 0.2.0 `environment` and `version`, which the platform reads as the build the report saw. The `context` member holds at most 20 short string members named by lowercase letters, digits, and underscores. Names and identifiers, never the person's content. Type: object Additional properties: false |
| / |
Type: string Maximum length: 200 |
| / |
Type: string Maximum length: 200 |
| / |
Type: string Maximum length: 200 |
| / |
Type: string Maximum length: 200 |
| / |
Type: string Maximum length: 200 |
| / |
Type: string Maximum length: 200 |
| / |
Type: object maxProperties: 20 |
| / |
Type: string Maximum length: 500 |
| / |
True where the report is a security concern, which hides its issue from every other reporter. Type: boolean |
| / |
Your own name for the problem, judged among your own reports. Type: string Maximum length: 200 |
| / |
The 0.2.0 name of `problem_key`, and the key the recovered mark names. Type: string Maximum length: 200 |
| / |
The issue the report repeats, one of the candidates a filing answered. Type: string Pattern: ^#[1-9][0-9]*$ |
| / |
With `repeat_of` alone: the number of your own report a filing answered. Type: integer Minimum: 1 |
| / |
With `key` and no member of a filing: the 0.2.0 recovered mark, which settles the open filing the key names among the caller's own as recovered. Type: boolean |
| / |
The identifier of an issue space the acting account holds, a lower-case UUID: a space of the account's own, an application's own space as `submit_manifest`'s receipt names it, or one space of an application's per-environment pair. Absent, the call addresses the platform's own space. A request naming `application` or `environment` is refused `invalid_request` naming `space`. Type: string Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ |
response
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","issue","outcome"] |
| / |
Required value: 1 |
| / |
The short reference the platform recorded this call under, ten lowercase hexadecimal characters, the value the call's record row carries; quote it when reporting the call. Type: string Pattern: ^[0-9a-f]{10}$ |
| / |
The caller's 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`); and the builds it saw. The service's other members of a report may stand beside them. Type: object Required fields: ["id"] |
| / |
The report's number, which `report` beside `repeat_of` names to confirm a candidate. Type: integer Minimum: 1 |
| / |
Where the report came from, which the platform gives it and no filer names: `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 answered, as filed, the credential forms the service found masked. Type: string |
| / |
What the problem cost, or null where the filing named 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 named one of your own calls. Type: object |
| / |
`stamped` where the platform stamped a `bug`'s evidence from its record of a refused call. `confirmed` where its daily check joined a `bug`'s claimed reference to a refused or failed call. `claimed` otherwise, answered calls and other kinds among them. Type: string Allowed values: ["stamped","confirmed","claimed"] |
| / |
The builds the report saw, each its line or null, its version, and its environment. Type: array |
| / |
Type: object Required fields: ["line","version","environment"] |
| / |
Type: ["string","null"] |
| / |
Type: string |
| / |
Type: string |
| / |
On a filing 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 answers 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"] |
| / |
Type: ["object","null"] |
| / |
The identifiers of the statements that design the behaviour, strings, where the issue closed as designed; null otherwise. Type: ["array","null"] |
| / |
Type: array |
| / |
Type: object |
| / |
What the call did: `filed` a new issue, `linked` the report to a standing one, `retried` an earlier identical filing, `noted` praise, `confirmed` a candidate; the 0.2.0 recovered mark answers that wire's words. Type: string Allowed values: ["filed","linked","retried","noted","confirmed","recovered","repeated","reopened"] |
| / |
Up to three issues the report may repeat: each title and workaround only where a trusted actor wrote them. 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"] |
| / |
Type: ["object","null"] |
| / |
The credential forms the service masked in the filing: rotate each. Type: array |
| / |
Type: string |
| / |
True where the platform stamped the evidence from its own record of the call the reference names, which it does where that call was refused and the report is a `bug` alone. False where the call was answered, the report is of another kind, the reference names no call of yours, or no reference was quoted. Type: boolean |
| / |
The issue a filing confirmed beside it, where one was named. Type: string Pattern: ^#[1-9][0-9]*$ |
Complete payload contract
{
"request": {
"type": "object",
"required": [
"source"
],
"properties": {
"source": {
"type": "string",
"enum": [
"person",
"agent",
"system"
],
"description": "The kind of actor filing: `person`, a report the person made; `agent`, the assistant's own; `system`, a program's or a company harness's."
},
"provider": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,31}$",
"description": "An agent's provider, 1 to 32 lowercase letters, digits, and hyphens opening with a letter; with `session`, both or neither."
},
"session": {
"type": "string",
"maxLength": 200,
"description": "An agent's session identifier, 1 to 200 printable characters; with `provider`, both or neither."
},
"kind": {
"type": "string",
"enum": [
"bug",
"gap",
"docs",
"friction",
"question",
"task",
"praise",
"missing_capability",
"documentation_gap",
"refusal_not_understood",
"usability"
],
"description": "The filing's kind, required on a filing. A `question` or a `task` is refused from a customer's report."
},
"title": {
"type": "string",
"maxLength": 200,
"description": "The filing's title, 1 to 200 characters; required on a filing."
},
"text": {
"type": "string",
"maxLength": 20000,
"description": "What was attempted and what answered, in your own words. It carries no personal details: no names, email addresses, telephone numbers, or anything else that identifies a person."
},
"body": {
"type": "string",
"maxLength": 20000,
"description": "The 0.2.0 name of `text`; never beside it."
},
"impact": {
"type": "string",
"enum": [
"blocked",
"worked_around",
"annoyed",
"none"
],
"description": "What the problem cost you."
},
"severity": {
"type": "string",
"enum": [
"critical",
"high",
"medium",
"low"
],
"description": "The 0.2.0 word read as an impact; never beside `impact`."
},
"workaround": {
"type": "string",
"maxLength": 4000,
"description": "What you did to get past it."
},
"proposed_resolution": {
"type": "string",
"maxLength": 4000,
"description": "The fix you propose."
},
"labels": {
"type": "array",
"maxItems": 20,
"items": {
"type": "string",
"maxLength": 64
},
"description": "At most 20 labels, each 1 to 64 lowercase letters, digits, hyphens, underscores, periods, and colons opening with a letter or a digit."
},
"evidence": {
"type": "object",
"description": "What the report is about: the action, the refusal name, the reference the refusal or the answer carried, the code site, and the 0.2.0 `environment` and `version`, which the platform reads as the build the report saw. The `context` member holds at most 20 short string members named by lowercase letters, digits, and underscores. Names and identifiers, never the person's content.",
"properties": {
"action": {
"type": "string",
"maxLength": 200
},
"refusal": {
"type": "string",
"maxLength": 200
},
"reference": {
"type": "string",
"maxLength": 200
},
"code_site": {
"type": "string",
"maxLength": 200
},
"environment": {
"type": "string",
"maxLength": 200
},
"version": {
"type": "string",
"maxLength": 200
},
"context": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 500
},
"maxProperties": 20
}
},
"additionalProperties": false
},
"restricted": {
"type": "boolean",
"description": "True where the report is a security concern, which hides its issue from every other reporter."
},
"problem_key": {
"type": "string",
"maxLength": 200,
"description": "Your own name for the problem, judged among your own reports."
},
"key": {
"type": "string",
"maxLength": 200,
"description": "The 0.2.0 name of `problem_key`, and the key the recovered mark names."
},
"repeat_of": {
"type": "string",
"pattern": "^#[1-9][0-9]*$",
"description": "The issue the report repeats, one of the candidates a filing answered."
},
"report": {
"type": "integer",
"minimum": 1,
"description": "With `repeat_of` alone: the number of your own report a filing answered."
},
"recovered": {
"type": "boolean",
"description": "With `key` and no member of a filing: the 0.2.0 recovered mark, which settles the open filing the key names among the caller's own as recovered."
},
"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": "The identifier of an issue space the acting account holds, a lower-case UUID: a space of the account's own, an application's own space as `submit_manifest`'s receipt names it, or one space of an application's per-environment pair. Absent, the call addresses the platform's own space. A request naming `application` or `environment` is refused `invalid_request` naming `space`."
}
},
"x-renamed": {
"application": "space",
"environment": "space"
},
"x-retired": {
"personal": "A report has no personal option: file it again without it, and leave out of it anything you do not want kept.",
"excerpt": "A report has no personal option: file it again without it, and leave out of it anything you do not want kept."
}
},
"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 this call under, ten lowercase hexadecimal characters, the value the call's record row carries; quote it when reporting the call."
},
"report": {
"type": "object",
"description": "The caller's 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`); and the builds it saw. The service's other members of a report may stand beside them.",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"description": "The report's number, which `report` beside `repeat_of` names 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 no filer names: `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 answered, 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 named 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 named one of your own calls."
},
"evidence_basis": {
"type": "string",
"enum": [
"stamped",
"confirmed",
"claimed"
],
"description": "`stamped` where the platform stamped a `bug`'s evidence from its record of a refused call. `confirmed` where its daily check joined a `bug`'s claimed reference to a refused or failed call. `claimed` otherwise, answered calls and other kinds among them."
},
"seen_in": {
"type": "array",
"items": {
"type": "object",
"required": [
"line",
"version",
"environment"
],
"properties": {
"line": {
"type": [
"string",
"null"
]
},
"version": {
"type": "string"
},
"environment": {
"type": "string"
}
}
},
"description": "The builds the report saw, each its line or null, its version, and its environment."
}
}
},
"issue": {
"type": [
"object",
"null"
],
"description": "On a filing 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 answers 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"
]
},
"live_in": {
"type": [
"object",
"null"
]
},
"requirements": {
"type": [
"array",
"null"
],
"description": "The identifiers of the statements that design the behaviour, strings, where the issue closed as designed; null otherwise."
},
"reports": {
"type": "array",
"items": {
"type": "object"
}
}
}
},
"outcome": {
"type": "string",
"enum": [
"filed",
"linked",
"retried",
"noted",
"confirmed",
"recovered",
"repeated",
"reopened"
],
"description": "What the call did: `filed` a new issue, `linked` the report to a standing one, `retried` an earlier identical filing, `noted` praise, `confirmed` a candidate; the 0.2.0 recovered mark answers that wire's words."
},
"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"
]
},
"workaround": {
"type": [
"string",
"null"
]
},
"live_in": {
"type": [
"object",
"null"
]
}
}
},
"description": "Up to three issues the report may repeat: each title and workaround only where a trusted actor wrote them. 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."
},
"stamped": {
"type": "boolean",
"description": "True where the platform stamped the evidence from its own record of the call the reference names, which it does where that call was refused and the report is a `bug` alone. False where the call was answered, the report is of another kind, the reference names no call of yours, or no reference was quoted."
},
"repeat_of": {
"type": "string",
"pattern": "^#[1-9][0-9]*$",
"description": "The issue a filing confirmed beside it, where one was named."
}
}
}
}
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