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

# Create ticket

> 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. 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
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:
    post:
      tags:
        - tickets
      summary: Create ticket
      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. A route a token
        reaches can still refuse it, as the description says.


        From docs/manual/relay.html#routes.
      operationId: createTicket
      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}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewTicket'
      responses:
        2XX:
          description: Done.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketOne'
        default:
          $ref: '#/components/responses/Problem'
components:
  schemas:
    NewTicket:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 80
        body:
          type: string
          maxLength: 8000
        priority:
          type: string
          enum:
            - high
            - normal
            - low
        repo:
          type: string
          description: >-
            The folder of the repo. A session files in its own folder, and this
            is ignored.
        kind:
          type:
            - string
            - 'null'
          pattern: ^[a-z][a-z0-9-]{0,23}$
        labels:
          type:
            - array
            - string
          items:
            type: string
            pattern: ^[a-z][a-z0-9-]{0,23}$
          description: A list, or one string with commas between.
        blockedBy:
          type: array
          items:
            type: string
        shapes:
          type: array
          items:
            type:
              - string
              - number
      required:
        - title
      additionalProperties: true
    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.