> ## 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.

# Edit ticket

> Changes any of a ticket's fields, saved together, or none when one is refused: title (1 to 80 characters) and body (up to 8000) of a Triage or Ready ticket; priority, high, normal or low, which puts it last in that priority; kind, a word, or "" to take it away (Kind); labels, up to 5, at any status, the list replacing the one there (Labels); mark, "hold", "replaced" with an optional replacedBy, or null to clear it (On hold, replaced, and design tickets); shapes, the tickets this design ticket shapes, while it is in Triage, Ready or Started; and base, another local branch to start from. Each field keeps its own error code, such as bad_title, bad_priority, bad_kind, bad_label, bad_mark, bad_shapes, bad_base or no_base. A field the ticket's state does not allow gets 409 not_ready, or 403 for a session's token, and a title or base another open ticket in the repo has on that branch gets 409 duplicate. For the PM and the Lead, a ticket you rejected counts too, as in filing. Only the fields that differ are written: the answer's edited lists them, and has unchanged when none do. The PM and the Lead send only title, body and priority, and priority only while you let them set the order (The PM sets the order, The Lead sets priority); anything else gets 403. Any other session's token gets 403. See Editing a ticket.

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}/edit
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}/edit:
    post:
      tags:
        - tickets
      summary: Edit ticket
      description: >-
        Changes any of a ticket's fields, saved together, or none when one is
        refused: title (1 to 80 characters) and body (up to 8000) of a Triage or
        Ready ticket; priority, high, normal or low, which puts it last in that
        priority; kind, a word, or "" to take it away (Kind); labels, up to 5,
        at any status, the list replacing the one there (Labels); mark, "hold",
        "replaced" with an optional replacedBy, or null to clear it (On hold,
        replaced, and design tickets); shapes, the tickets this design ticket
        shapes, while it is in Triage, Ready or Started; and base, another local
        branch to start from. Each field keeps its own error code, such as
        bad_title, bad_priority, bad_kind, bad_label, bad_mark, bad_shapes,
        bad_base or no_base. A field the ticket's state does not allow gets 409
        not_ready, or 403 for a session's token, and a title or base another
        open ticket in the repo has on that branch gets 409 duplicate. For the
        PM and the Lead, a ticket you rejected counts too, as in filing. Only
        the fields that differ are written: the answer's edited lists them, and
        has unchanged when none do. The PM and the Lead send only title, body
        and priority, and priority only while you let them set the order (The PM
        sets the order, The Lead sets priority); anything else gets 403. Any
        other session's token gets 403. See Editing a ticket.


        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: editTicket
      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: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TicketEdit'
      responses:
        2XX:
          description: Done.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketOne'
        default:
          $ref: '#/components/responses/Problem'
components:
  schemas:
    TicketEdit:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 80
        body:
          type: string
          maxLength: 8000
        priority:
          type: string
          enum:
            - high
            - normal
            - low
          description: A PM or the Lead needs its switch on to send this.
        kind:
          type:
            - string
            - 'null'
          pattern: ^[a-z][a-z0-9-]{0,23}$
          description: The person only.
        labels:
          type:
            - array
            - string
          items:
            type: string
            pattern: ^[a-z][a-z0-9-]{0,23}$
          description: The person only. A list, or one string with commas between.
        mark:
          type:
            - string
            - 'null'
          enum:
            - hold
            - replaced
            - ''
          description: The person only. null or an empty string clears it.
        replacedBy:
          type: string
          description: 'With "mark": "replaced": the ticket that replaces it.'
        shapes:
          type: array
          items:
            type:
              - string
              - number
        base:
          type: string
          minLength: 1
          description: The person only. A local branch with commits.
      required: []
      additionalProperties: true
      minProperties: 1
      description: >-
        Any of these, saved together, or none when one is refused. A PM or the
        Lead sends only title, body and priority.
    TicketOne:
      type: object
      properties:
        ok:
          const: true
        ticket:
          $ref: '#/components/schemas/Ticket'
      required:
        - ok
        - ticket
      additionalProperties: true
    Ticket:
      type: object
      properties:
        id:
          type: string
          description: Such as T-5, or the issue number in the GitHub store.
        title:
          type: string
          maxLength: 80
        body:
          type: string
          maxLength: 8000
        status:
          type: string
          enum:
            - triage
            - ready
            - started
            - done
            - rejected
        priority:
          type: string
          enum:
            - high
            - normal
            - low
        rank:
          type: number
          description: Its place in the work order within its priority.
        repo:
          type:
            - string
            - 'null'
        base:
          type:
            - string
            - 'null'
          description: The branch a start makes its branch from.
        kind:
          type:
            - string
            - 'null'
          pattern: ^[a-z][a-z0-9-]{0,23}$
        labels:
          type: array
          items:
            type: string
            pattern: ^[a-z][a-z0-9-]{0,23}$
        blockedBy:
          type: array
          items:
            type: string
        waitingFor:
          type: array
          items:
            type: string
        rejectedBlockers:
          type: array
          items:
            type: string
        approved:
          type: boolean
        approvedBy:
          type:
            - string
            - 'null'
        createdBy:
          type:
            - string
            - 'null'
        heldBack:
          type:
            - string
            - 'null'
          description: >-
            Why nothing starts it by itself: a hold, a replacement, a design
            ticket or a proposal.
        mark:
          type:
            - string
            - 'null'
          enum:
            - hold
            - replaced
        task:
          type:
            - object
            - 'null'
          description: Its task once started.
        history:
          type: array
          items:
            $ref: '#/components/schemas/TicketStep'
        createdAt:
          type: string
        updatedAt:
          type: string
      required:
        - id
        - title
        - status
        - priority
        - createdAt
        - updatedAt
      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
    TicketStep:
      type: object
      properties:
        at:
          type: string
        stage:
          type: string
        by:
          type: string
      required:
        - at
        - stage
        - by
      additionalProperties: true
      description: One step in a ticket's history.
  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.