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

> List or start sessions. A start can have a prompt, up to 8000 characters, which the relay types as the session's first prompt. A longer one is refused with bad_prompt. The list also has finished: the latest automatic reviewers that posted and left. Each session has its seat, the id of the person the relay gave it, and who, that person's name (see Which person gets it), its work label (see labels), and its starts, startsLeft, lastStart, refresh, refreshNote and tired (how full its context is, or null: see How tired the Lead is), and the list has the wipLimit.

Tokens: the relay key only.

From docs/manual/relay.html#routes.



## OpenAPI

````yaml https://raw.githubusercontent.com/bfalkowski/Building58/main/docs/openapi.json get /channels/{channel}/terminals
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}/terminals:
    get:
      tags:
        - terminals
      summary: List sessions
      description: >-
        List or start sessions. A start can have a prompt, up to 8000
        characters, which the relay types as the session's first prompt. A
        longer one is refused with bad_prompt. The list also has finished: the
        latest automatic reviewers that posted and left. Each session has its
        seat, the id of the person the relay gave it, and who, that person's
        name (see Which person gets it), its work label (see labels), and its
        starts, startsLeft, lastStart, refresh, refreshNote and tired (how full
        its context is, or null: see How tired the Lead is), and the list has
        the wipLimit.


        Tokens: the relay key only.


        From docs/manual/relay.html#routes.
      operationId: listSessions
      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/SessionList'
        default:
          $ref: '#/components/responses/Problem'
components:
  schemas:
    SessionList:
      type: object
      properties:
        ok:
          const: true
        enabled:
          type: boolean
        home:
          type: string
        cwd:
          type: string
        terminals:
          type: array
          items:
            $ref: '#/components/schemas/Session'
        lead:
          type:
            - object
            - 'null'
        wipLimit:
          type: number
      required:
        - ok
        - enabled
        - terminals
      additionalProperties: true
    Session:
      type: object
      properties:
        id:
          type: string
          pattern: ^[0-9a-f]{12}$
        who:
          type:
            - string
            - 'null'
        cwd:
          type: string
        sessionId:
          type: string
        title:
          type:
            - string
            - 'null'
        role:
          type:
            - string
            - 'null'
        task:
          type:
            - string
            - 'null'
        pr:
          type:
            - string
            - 'null'
        lead:
          type: boolean
        running:
          type: boolean
        state:
          type: string
          description: working, waiting, idle, quiet or stuck, from its hooks.
        startedAt:
          type: string
      required:
        - id
        - cwd
        - sessionId
        - lead
        - running
        - state
      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.