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

# List Terminals

> Retrieve all active terminals in your group with connection details and status

<Note>
  This endpoint requires HMAC-SHA256 authentication. See [Authentication](../../docs/terminal-gateway/authentication) for signature computation details.
</Note>

## Terminal ID Usage

The response includes both `connectionId` and `deviceId` for each terminal:

* **deviceId (Recommended)** - Stable identifier that persists across reconnections
* **connectionId** - Temporary identifier that changes when a terminal reconnects

Use `deviceId` when initiating payments for reliable terminal targeting.


## OpenAPI

````yaml api-reference/terminal-gateway/openapi.json GET /v1/terminals
openapi: 3.1.0
info:
  title: Terminal Gateway HTTP API
  version: 1.0.0
  description: >-
    HTTP API for POS-to-terminal communication. Enables payment processing
    through connected terminals.
  contact:
    name: Modulus Labs Support
    email: support@moduluslabs.io
servers:
  - url: https://your-endpoint.moduluslabs.io
    description: >-
      Your provisioned Terminal Gateway API endpoint. Contact
      support@moduluslabs.io to obtain your URL and credentials.
security:
  - hmacAuth: []
tags:
  - name: Terminals
    description: Terminal discovery and management
  - name: Payments
    description: Payment processing
  - name: Transactions
    description: Transaction status and reconciliation
  - name: Webhooks
    description: Webhook endpoint management for asynchronous payment notifications
paths:
  /v1/terminals:
    get:
      tags:
        - Terminals
      summary: List Terminals
      description: >-
        Retrieve all active terminals in your group. Returns terminal connection
        details including device IDs and status.
      operationId: listTerminals
      responses:
        '200':
          description: List of active terminals
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TerminalsResponse'
              example:
                terminals:
                  - connectionId: abc123xyz
                    terminalId: TERM-001
                    deviceId: TERM-001
                    connectedAt: '2024-01-15T10:30:00.000Z'
                    lastActivity: '2024-01-15T10:35:00.000Z'
                    status: online
                    metadata: {}
                count: 1
                timestamp: '2024-01-15T10:35:30.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    TerminalsResponse:
      type: object
      required:
        - terminals
        - count
        - timestamp
      properties:
        terminals:
          type: array
          description: List of available terminals
          items:
            $ref: '#/components/schemas/TerminalInfo'
        count:
          type: integer
          description: Total number of terminals
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the response
    TerminalInfo:
      type: object
      required:
        - connectionId
        - terminalId
        - connectedAt
        - lastActivity
        - status
      properties:
        connectionId:
          type: string
          description: Unique connection identifier. Changes when terminal reconnects.
        terminalId:
          type: string
          description: >-
            Primary identifier. Uses deviceId if available, otherwise
            connectionId.
        deviceId:
          type: string
          description: Stable device identifier. Persists across reconnections.
        connectedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the terminal connected
        lastActivity:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the terminal's last activity
        status:
          type: string
          enum:
            - online
            - offline
            - reconnecting
          description: Terminal status
        metadata:
          type: object
          description: Custom terminal metadata
          additionalProperties: true
    Error:
      type: object
      required:
        - error
        - timestamp
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Error code
            message:
              type: string
              description: Human-readable error message
            details:
              type: object
              description: Additional error details
              additionalProperties: true
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp
        requestId:
          type: string
          description: Request identifier for debugging
        transactionId:
          type: string
          description: Transaction ID if applicable
  responses:
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unauthorized:
              summary: Invalid API key
              value:
                error:
                  code: UNAUTHORIZED
                  message: Missing or invalid API key
                timestamp: '2024-01-15T10:40:00.000Z'
            invalidSignature:
              summary: Invalid signature
              value:
                error:
                  code: INVALID_SIGNATURE
                  message: HMAC signature verification failed
                timestamp: '2024-01-15T10:40:00.000Z'
            timestampExpired:
              summary: Timestamp expired
              value:
                error:
                  code: TIMESTAMP_EXPIRED
                  message: Request timestamp outside 5-minute window
                timestamp: '2024-01-15T10:40:00.000Z'
    Forbidden:
      description: Access denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: GROUP_MISMATCH
              message: Resource belongs to a different group
            timestamp: '2024-01-15T10:40:00.000Z'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_ERROR
              message: Unexpected server error
            timestamp: '2024-01-15T10:40:00.000Z'
  securitySchemes:
    hmacAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        HMAC-SHA256 authentication. Requires three headers: x-api-key (your API
        key), x-timestamp (ISO 8601 timestamp), and x-signature (Base64-encoded
        HMAC-SHA256 signature). See Authentication documentation for signature
        computation.

````