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

# List tickets

> List or file tickets. The list comes in Board order: open tickets high, normal, low, in work order (rank) within each, then done and rejected ones, the latest changed first. It also has kinds (the kinds a ticket can have, see Kind), labels (the labels tickets have, A to Z, see Labels), wipLimit, leadStarts (the number you let the Lead start tickets up to, or 0) and leadStartsLeft. A ticket has approvedBy (you or Lead) once it is put in Ready. The room page gets the same list as a tickets event on its GET /stream when it opens the stream with board=1, with people, who sits on each ticket, and without the time each pipeline was checked. The stream's hello says whether it will (tickets). It is sent once as the stream opens, then only when it changes, and only to the room page on this computer.

Tokens: the relay key, and the token of any session, the COO, the security officer. 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 get /channels/{channel}/tickets
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:
    get:
      tags:
        - tickets
      summary: List tickets
      description: >-
        List or file tickets. The list comes in Board order: open tickets high,
        normal, low, in work order (rank) within each, then done and rejected
        ones, the latest changed first. It also has kinds (the kinds a ticket
        can have, see Kind), labels (the labels tickets have, A to Z, see
        Labels), wipLimit, leadStarts (the number you let the Lead start tickets
        up to, or 0) and leadStartsLeft. A ticket has approvedBy (you or Lead)
        once it is put in Ready. The room page gets the same list as a tickets
        event on its GET /stream when it opens the stream with board=1, with
        people, who sits on each ticket, and without the time each pipeline was
        checked. The stream's hello says whether it will (tickets). It is sent
        once as the stream opens, then only when it changes, and only to the
        room page on this computer.


        Tokens: the relay key, and the token of any session, the COO, the
        security officer. A route a token reaches can still refuse it, as the
        description says.


        From docs/manual/relay.html#routes.
      operationId: listTickets
      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}$
      responses:
        2XX:
          description: Done.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketList'
        default:
          $ref: '#/components/responses/Problem'
components:
  schemas:
    TicketList:
      type: object
      properties:
        ok:
          const: true
        store:
          type: string
        wipLimit:
          type: number
        leadStarts:
          type: number
        leadStartsLeft:
          type: number
        statuses:
          type: array
          items:
            type: string
            enum:
              - triage
              - ready
              - started
              - done
              - rejected
        kinds:
          type: array
          items:
            type: string
        labels:
          type: array
          items:
            type: string
        tickets:
          type: array
          items:
            $ref: '#/components/schemas/Ticket'
      required:
        - ok
        - tickets
        - statuses
        - kinds
        - labels
      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.