relay_issue_act #

View this page as Markdown

On this page

Generated automatically from the published 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).

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 #

{
  "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 #

{
  "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
Required fields: ["space","act"]
/properties/space The space the act reaches, a lower-case UUID, the one your token's issues grant reaches.

Type: string
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
/properties/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.

Type: string
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"]
/properties/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.

Type: object
/properties/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.

Type: string
Allowed values: ["person","agent","system"]
/properties/provider An agent's provider; with session, both or neither.

Type: string
Pattern: ^[a-z][a-z0-9-]{0,31}$
/properties/session An agent's session identifier; with provider, both or neither.

Type: string
Maximum length: 200

response #

JSON pointer Description and constraints
"" (root) Type: object
Required fields: ["contract_version","space","act","result"]
/properties/contract_version Required value: 1
/properties/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.

Type: string
Pattern: ^[0-9a-f]{10}$
/properties/space The space the act reached.

Type: string
/properties/act The act relayed.

Type: string
/properties/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.

Type: object

Complete payload contract #

{
  "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 #