> ## Documentation Index
> Fetch the complete documentation index at: https://docs.building58.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Propose ticket change

> {"action", "ids", "why"}: proposes to change a Triage or Ready ticket. action is replace (with one or more ids), merge (with one), close (with none) or blockers (the whole new list, which can be empty). why is up to 500 characters. Nothing changes but the ticket's proposal, which holds it back. The PM's and the Lead's tokens propose, and so does the person's key, when the proposal then says You propose. Refused with 400 when an id is not on the Board, is the ticket itself, or was rejected, for every kind, and when a new blocker already waits for the ticket. A ticket that is starting, started, done or rejected gets 409, or 403 for a session's token. See Proposals.

Tokens: the relay key, and the token of a PM, the Lead. A route a token reaches can still refuse it, as the description says.

From docs/manual/relay.html#routes.



## OpenAPI

````yaml https://raw.githubusercontent.com/bfalkowski/Building58/main/docs/openapi.json post /channels/{channel}/tickets/{id}/propose
openapi: 3.1.0
info:
  title: Building58 relay
  version: 2.0.0
  description: >-
    The relay passes commands to a world's page and runs the room: tickets,
    tasks, sessions and reviews. It answers this computer only. Each route's
    description is the manual's, from docs/manual/relay.html, where the fields,
    the tokens and the errors are.
  license:
    name: PolyForm Noncommercial 1.0.0
    identifier: PolyForm-Noncommercial-1.0.0
servers:
  - url: http://localhost:8787
    description: The relay on this computer. npm run office starts it on 8787.
security:
  - relayKey: []
  - relayKeyQuery: []
  - sessionToken: []
tags:
  - name: calls
    description: 'Calls any caller uses: commands, events and the page.'
  - name: autopilot
  - name: chat
  - name: checkouts
  - name: floor
  - name: games
  - name: huddle
  - name: needs-you
  - name: officers
  - name: old-relays
  - name: play
  - name: pr-watch
  - name: ready
  - name: reviews
  - name: rounds
  - name: settings
  - name: tasks
  - name: terminals
  - name: tickets
  - name: update
paths:
  /channels/{channel}/tickets/{id}/propose:
    post:
      tags:
        - tickets
      summary: Propose ticket change
      description: >-
        {"action", "ids", "why"}: proposes to change a Triage or Ready ticket.
        action is replace (with one or more ids), merge (with one), close (with
        none) or blockers (the whole new list, which can be empty). why is up to
        500 characters. Nothing changes but the ticket's proposal, which holds
        it back. The PM's and the Lead's tokens propose, and so does the
        person's key, when the proposal then says You propose. Refused with 400
        when an id is not on the Board, is the ticket itself, or was rejected,
        for every kind, and when a new blocker already waits for the ticket. A
        ticket that is starting, started, done or rejected gets 409, or 403 for
        a session's token. See Proposals.


        Tokens: the relay key, and the token of a PM, the Lead. A route a token
        reaches can still refuse it, as the description says.


        From docs/manual/relay.html#routes.
      operationId: proposeTicketChange
      parameters:
        - name: channel
          in: path
          required: true
          description: >-
            The channel, such as office: 1 to 64 letters, numbers, dashes or
            underscores.
          schema:
            type: string
            pattern: ^[\w-]{1,64}$
        - name: id
          in: path
          required: true
          description: The ticket's id, such as T-5.
          schema:
            type: string
            pattern: ^[\w-]{1,64}$
      requestBody:
        required: false
        description: JSON. The fields are in the description.
        content:
          application/json:
            schema:
              type: object
      responses:
        2XX:
          description: Done.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ok'
        default:
          $ref: '#/components/responses/Problem'
components:
  schemas:
    Ok:
      type: object
      properties:
        ok:
          const: true
      required:
        - ok
      additionalProperties: true
    Problem:
      type: object
      properties:
        ok:
          const: false
        error:
          type: string
          description: A short code, such as bad_param, forbidden or not_found.
        message:
          type: string
          description: What went wrong, in plain words.
      required:
        - ok
        - error
        - message
      additionalProperties: true
  responses:
    Problem:
      description: >-
        Refused. 400 for a bad body, 401 for no key, 403 for a key or token that
        may not, 404 for an unknown route or id, 409 for a state that does not
        allow it, 413 for a body over 256 KB, 429 for too soon, 503 and 504 when
        no page answers.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    relayKey:
      type: http
      scheme: bearer
      description: 'The relay key, RELAY_KEY: Authorization: Bearer <key>.'
    relayKeyQuery:
      type: apiKey
      in: query
      name: key
      description: The relay key in the address, as the page sends it.
    sessionToken:
      type: http
      scheme: bearer
      description: >-
        A session's own token, OFFICE_TICKET_TOKEN. It reaches only the routes
        its role needs: see docs/manual/relay.html#tokens.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.