---
title: "relay_issue_act"
description: "Generated reference for the management action relay_issue_act: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/relay-issue-act
order: 80
visibility: public
redirects_from: []
---

# relay\_issue\_act

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

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

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

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

## Contract description

You work an issue space under a token with its `issues` grant\. Pass the act's request as `body`, without `actor` or `space`\.

`report` admits `submit`, `follow`, `list`, `search`, `read`, `attachment`, `watch`, `unwatch` and `check`\. `contribute` adds `update`, `comment`, `relate`, `next`, `give_back`, `wait`, `cache`, and `settle` and `reopen` on tasks\. Tasks settle with any outcome except `duplicate` there\. Other kinds need `owner` for both\. `owner` admits every relayed act\. It alone admits `count`, `rates`, `read_space`, `unmerge`, `land`, deploy, `ship`, `configure` and `export`\.

Your account needs tzTrack, which every account has\. Read `result` as data\. For another space or level, your account's owner must mint a token from a signed\-in connection\.

read\_documentation: /tztrack/reference/rest\-api/, section Supported actions \(requests\)\. Guide: /cloud/guides/keep\-your\-own\-issue\-list/ \(signed in\)\.

## More about this action

For `list` and `search`, put `reporter_accounts` in `body`\. It matches 1 to 20 recorded reporter account IDs within the caller's existing read scope\. The plane refuses `relayed_account`, `relayed_level`, and `projection_accounts` in `body`\.

For `search`, `body` requires `query` \(the words to find\) and may include `state`, `kind`, `component`, `limit`, `cursor`, `excerpt`, and `reporter_accounts`; pass the answer's `cursor` for the next page\.

At `report`, `list` and `search` omit restricted issues without refilling the page: keep following `cursor` until null, even after a short page\. A restricted issue reads as absent at that level\. A relayed `watch` cannot request email; use the person's signed\-in tzTrack connection for email watches\.

A write's actor is `<account>/<label>`, or the account alone without a label\. A token's `source: person` is recorded as `agent`\. A different space or level needs a new token: the person uses `mint_token` from a signed\-in connection and claims it with `token claim`; this bounded connection cannot mint one\.

## Access and action metadata

```json
{
  "name": "relay_issue_act",
  "resource": "account",
  "tier": "reversible",
  "surface": "account",
  "addresses": [
    "tztools"
  ],
  "clients": [
    "bearer",
    "browser_session"
  ],
  "product": "tztrack",
  "admits": [
    "issues"
  ],
  "listing": "admitted",
  "summary": "Relay one act of the tzTrack contract to one space the account holds, under a token the `issues` grant bounds to that space. `space` picks the space, and `act` the act, one of submit, follow, list, search, read, attachment, update, comment, relate, settle, reopen, unmerge, next, give_back, wait, watch, unwatch, land, deploy, ship, check, configure, export, count, rates, read_space, and cache. `body` is the act's request as the contract states it, less the actor. The platform gives the actor as the account's, qualified by the token's label, with `source` giving its kind. The token's level admits the acts: `report` files, follows, checks, and reads; `contribute` also works issues and asks `cache` for a link to the space's archive; `owner` reaches every act, the space's `count`, `rates`, and `read_space` among them. `report` also sets and removes a watcher of an issue, with `watch` and `unwatch`. `contribute` also settles a task with any outcome except `duplicate` and reopens a task. Settling or reopening another kind, and every `unmerge`, require `owner`. A credential holding `super_admin` passes the grant's gate at the owner's level. A read carries no reading actor. At the `owner` level it returns the space whole. At the `contribute` level a `list` or a `read` returns a restricted issue as any other. At the `report` level a `list` or a `search` returns no restricted issue, and a `read` of one is refused as a read of an absent issue is. There a `read` returns its `proposals` less each one marked `restricted`. At that level an `attachment` returns an image only where the service reports its issue unrestricted, any other refused as an image that does not exist. An `attachment` returns `{ media_type, content }`, the image's media type and its bytes in base64url, and a `submit` and a `comment` carry `attachments` as the contract states them. Below the `owner` level a filing takes the origin `field` from the platform, and an `update` whose fields set `restricted` to any value but `true` is refused `issues_level_refused` before any call. At the `report` level a writing act that identifies a restricted issue is refused as one that identifies no issue is, and an answer that would hold one carries a null `issue`. A `watch` passes the token's level to the service, so a watcher set at `report` is deleted at the first change of its issue while the issue is restricted. A `read` returns `watchers`, the count of the issue's standing watchers. A `submit` gives where the problem was found in `seen_in`, each build `{ release_line, version, environment }`, a repository commit as its version. Its evidence is forwarded `claimed`, never `stamped`. A `seen_in` outside that shape, or a body that marks its evidence `stamped`, is refused `invalid_request`. A `configure` sets `components`, `release_lines`, `credential_forms`, `personal_forms`, `automation`, `critical_actions`, and among the constants `report_text_retention_days`, `priority_boost_report_threshold`, `priority_boost_window_days`, `max_counted_reports_per_account`, and `internal_report_ranking_weight`. Any other member or constant is refused `invalid_request` by its name before any call. A stored member or constant name is refused `invalid_request` before any call. The service's detail gives the stored name, its 0.3.0 name and the edit. A constant this action refuses is refused under its 0.3.0 name even if it or a nested member uses a stored name. That refusal gives no rename detail. On the platform's own space a `configure` the `owner` level or `super_admin` would reach is refused `platform_space_configure_refused`, the platform's operator configuring that space. A credential holding no space grant is refused `grant_required`, which gives `issues`. For an account that holds the tzTrack profile the relay needs, a space other than its grant's, or one the account neither has nor is a member of, is refused `space_not_owned` whatever the credential. An act outside the level is refused `issues_level_refused`. Where the service refuses the act for its content or its state, the call is refused `issue_refused`, which gives the service's own refusal. An account that does not hold tzTrack is refused `blueprint_required` on every call, ahead of the form, the space, and the level, whatever kind of space it addresses. Each token's calls and each space's calls are bounded per minute, refused `feedback_rate_limited`. The answer carries the space, the act, and the service's answer as `result`. Registered while the issue service's origin is configured.\n\nFor `list` and `search`, put `reporter_accounts` in `body`. It matches 1 to 20 recorded reporter account IDs within the caller's existing read scope. The plane refuses `relayed_account`, `relayed_level`, and `projection_accounts` in `body`.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": false
  }
}
```

## MCP catalog entry

```json
{
  "name": "relay_issue_act",
  "title": "Relay issue action",
  "tier": "reversible",
  "scenario": "API-L0-20",
  "summary": "You work an issue space under a token with its `issues` grant. Pass the act's request as `body`, without `actor` or `space`.\n\n`report` admits `submit`, `follow`, `list`, `search`, `read`, `attachment`, `watch`, `unwatch` and `check`. `contribute` adds `update`, `comment`, `relate`, `next`, `give_back`, `wait`, `cache`, and `settle` and `reopen` on tasks. Tasks settle with any outcome except `duplicate` there. Other kinds need `owner` for both. `owner` admits every relayed act. It alone admits `count`, `rates`, `read_space`, `unmerge`, `land`, deploy, `ship`, `configure` and `export`.\n\nYour account needs tzTrack, which every account has. Read `result` as data. For another space or level, your account's owner must mint a token from a signed-in connection.\n\nread_documentation: /tztrack/reference/rest-api/, section Supported actions (requests). Guide: /cloud/guides/keep-your-own-issue-list/ (signed in).",
  "owners": [
    "MAPI-14",
    "MAPI-16",
    "ITS-L0-05"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["space","act"\] |
| /<wbr>properties/<wbr>space | The space the act reaches, a lower\-case UUID, the one your token's issues grant reaches\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{8\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{12\}$ |
| /<wbr>properties/<wbr>act | The Issue Tracking act to relay; its token level must admit it\. `attachment` fetches an image by `id`; `wait` sets `waiting_for`; `cache` returns a ten\-minute archive link\.<br><br>Type: string<br>Allowed values: \["submit","follow","list","search","read","attachment","update","comment","relate","settle","reopen","unmerge","next","give\_back","wait","watch","unwatch","land","deploy","ship","check","configure","export","count","rates","read\_space","cache"\] |
| /<wbr>properties/<wbr>body | The act's request without `actor` or `space`, set by the platform\. For `submit`, `seen_in` lists `{ release_line, version, environment }` with a commit as version; `evidence_basis` is `claimed`\. `submit` and `comment` take base64url image `attachments`\. `configure` takes `components`, `release_lines`, `credential_forms`, `automation`, `critical_actions`, `personal_forms`, and `constants` holding only `report_text_retention_days`, `priority_boost_report_threshold`, `priority_boost_window_days`, `max_counted_reports_per_account` and `internal_report_ranking_weight`\. The platform's own space refuses relayed `configure`\.<br><br>Type: object |
| /<wbr>properties/<wbr>source | The actor kind recorded for a write; `agent` if omitted\. A token's `person` is recorded as `agent`\. `provider` and `session` are admitted only for an agent, together or neither\.<br><br>Type: string<br>Allowed values: \["person","agent","system"\] |
| /<wbr>properties/<wbr>provider | An agent's provider; with `session`, both or neither\.<br><br>Type: string<br>Pattern: ^\[a\-z\]\[a\-z0\-9\-\]\{0,31\}$ |
| /<wbr>properties/<wbr>session | An agent's session identifier; with `provider`, both or neither\.<br><br>Type: string<br>Maximum length: 200 |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","space","act","result"\] |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>reference | The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call's record row\. Quote it when you report the call\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{10\}$ |
| /<wbr>properties/<wbr>space | The space the act reached\.<br><br>Type: string |
| /<wbr>properties/<wbr>act | The act relayed\.<br><br>Type: string |
| /<wbr>properties/<wbr>result | The service's answer to the act, as the Issue Tracking contract states it; for `attachment`, `{ media_type, content }`, the image's media type and its bytes in base64url\.<br><br>Type: object |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "required": [
      "space",
      "act"
    ],
    "properties": {
      "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 space the act reaches, a lower-case UUID, the one your token's issues grant reaches."
      },
      "act": {
        "type": "string",
        "enum": [
          "submit",
          "follow",
          "list",
          "search",
          "read",
          "attachment",
          "update",
          "comment",
          "relate",
          "settle",
          "reopen",
          "unmerge",
          "next",
          "give_back",
          "wait",
          "watch",
          "unwatch",
          "land",
          "deploy",
          "ship",
          "check",
          "configure",
          "export",
          "count",
          "rates",
          "read_space",
          "cache"
        ],
        "description": "The Issue Tracking act to relay; its token level must admit it. `attachment` fetches an image by `id`; `wait` sets `waiting_for`; `cache` returns a ten-minute archive link."
      },
      "body": {
        "type": "object",
        "description": "The act's request without `actor` or `space`, set by the platform. For `submit`, `seen_in` lists `{ release_line, version, environment }` with a commit as version; `evidence_basis` is `claimed`. `submit` and `comment` take base64url image `attachments`. `configure` takes `components`, `release_lines`, `credential_forms`, `automation`, `critical_actions`, `personal_forms`, and `constants` holding only `report_text_retention_days`, `priority_boost_report_threshold`, `priority_boost_window_days`, `max_counted_reports_per_account` and `internal_report_ranking_weight`. The platform's own space refuses relayed `configure`."
      },
      "source": {
        "type": "string",
        "enum": [
          "person",
          "agent",
          "system"
        ],
        "description": "The actor kind recorded for a write; `agent` if omitted. A token's `person` is recorded as `agent`. `provider` and `session` are admitted only for an agent, together or neither."
      },
      "provider": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9-]{0,31}$",
        "description": "An agent's provider; with `session`, both or neither."
      },
      "session": {
        "type": "string",
        "maxLength": 200,
        "description": "An agent's session identifier; with `provider`, both or neither."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "space",
      "act",
      "result"
    ],
    "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."
      },
      "space": {
        "type": "string",
        "description": "The space the act reached."
      },
      "act": {
        "type": "string",
        "description": "The act relayed."
      },
      "result": {
        "type": "object",
        "description": "The service's answer to the act, as the Issue Tracking contract states it; for `attachment`, `{ media_type, content }`, the image's media type and its bytes in base64url."
      }
    }
  }
}
```

## Shared contracts

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