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

# Find selectable terminals for an Agent

> Search approved terminals under the Agent assigned Service Account live device and workspace permissions, including Group membership. An explicitly selected assignable Service Account may be previewed while editing. Returns bounded paged grants with names, readable workspaces and live presence; does not activate the execution identity or grant access.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/agents/{agentId}/terminals
openapi: 3.0.0
info:
  title: RevoEngine Platform API
  description: Official RevoEngine Platform API documentation.
  version: 1.6.4
  contact:
    name: Support
    email: support@revoengine.com
  termsOfService: https://docs.revoengine.com/tos
servers:
  - url: https://api.revoengine.com
    description: Production
security: []
tags:
  - name: Accounts
    description: Users, service accounts, API keys, status, and platform access.
    externalDocs:
      description: Identity and access guide
      url: https://docs.revoengine.com/operate/identity-and-access
  - name: Activity
    description: Snapshot-backed activity and version history.
    externalDocs:
      description: Observability guide
      url: https://docs.revoengine.com/operate/observability
  - name: Agent Memory
    description: Administrative access to durable Agent memory.
    externalDocs:
      description: Agent memory and workspaces guide
      url: https://docs.revoengine.com/ai/memory-and-workspaces
  - name: Agent Plugins
    description: Agent plugin definitions, synchronization, testing, and lifecycle.
    externalDocs:
      description: Agent plugins guide
      url: https://docs.revoengine.com/ai/plugins
  - name: Agent Terminals
    description: Terminal pairing, owner grants, access, and command activity.
    externalDocs:
      description: Connect a terminal guide
      url: https://docs.revoengine.com/ai/terminals
  - name: Agents
    description: >-
      Agent definitions, runs, sessions, inboxes, memory, tools, workspaces, and
      lifecycle.
    externalDocs:
      description: Autonomous Agents guide
      url: https://docs.revoengine.com/ai/agents
  - name: Assistant
    description: >-
      Assistant threads, messages, responses, goals, reports, sharing,
      attachments, and control.
    externalDocs:
      description: Assistant guide
      url: https://docs.revoengine.com/ai/assistant
  - name: Automation
    description: >-
      Jobs, templates, schedules, events, webhooks, execution history, and
      lifecycle.
    externalDocs:
      description: Automation guide
      url: https://docs.revoengine.com/operate/automation
  - name: Chat
    description: Collaborative chat threads, messages, reactions, uploads, and attachments.
    externalDocs:
      description: Team Chat guide
      url: https://docs.revoengine.com/operate/chat
  - name: Component deployments
    description: >-
      Custom Node.js runtime deployment attempts, readiness, activation, and
      rollback.
    externalDocs:
      description: Custom Node.js guide
      url: https://docs.revoengine.com/build/custom-nodejs
  - name: Components
    description: Components, elements, versions, validation, activation, and lifecycle.
    externalDocs:
      description: Components guide
      url: https://docs.revoengine.com/build/components
  - name: Config
    description: Instance configuration, usage, logs, and cache administration.
    externalDocs:
      description: Instance settings guide
      url: https://docs.revoengine.com/platform/instance-settings
  - name: Database Cache
    description: Instance Database cache values and statistics.
    externalDocs:
      description: Database Cache guide
      url: https://docs.revoengine.com/operate/database-cache
  - name: Database Views
    description: Database Views, previews, refreshes, exports, and controlled data actions.
    externalDocs:
      description: Database Views guide
      url: https://docs.revoengine.com/operate/database-views
  - name: Databases
    description: Database definitions, data, audits, exports, cloning, and lifecycle.
    externalDocs:
      description: Databases guide
      url: https://docs.revoengine.com/operate/databases
  - name: Endpoints
    description: >-
      Endpoint definitions, activation, validation, generated OpenAPI, and
      statistics.
    externalDocs:
      description: Endpoints guide
      url: https://docs.revoengine.com/operate/endpoints
  - name: Files
    description: Compatibility file listing, preview, download, and deletion operations.
    externalDocs:
      description: Files compatibility guide
      url: https://docs.revoengine.com/operate/files
  - name: Groups
    description: Groups, membership, avatars, and lifecycle.
    externalDocs:
      description: Groups guide
      url: https://docs.revoengine.com/operate/groups
  - name: Instance Vault
    description: Operations in the Instance Vault Platform API domain.
    externalDocs:
      description: Secrets and Vault guide
      url: https://docs.revoengine.com/operate/secrets
  - name: Me
    description: Current user profile, keys, avatar, and session information.
    externalDocs:
      description: Authentication guide
      url: https://docs.revoengine.com/developers/authentication
  - name: Observability
    description: Authorized execution, performance, graph, and log evidence.
    externalDocs:
      description: Observability guide
      url: https://docs.revoengine.com/operate/observability
  - name: Preferences
    description: User and instance preference values.
    externalDocs:
      description: Platform UI guide
      url: https://docs.revoengine.com/platform/ui-tour
  - name: Role Groups
    description: Role groups, members, assigned roles, and lifecycle.
    externalDocs:
      description: Permissions guide
      url: https://docs.revoengine.com/operate/permissions
  - name: Roles
    description: Available platform roles and role details.
    externalDocs:
      description: Permissions guide
      url: https://docs.revoengine.com/operate/permissions
  - name: Search
    description: Cross-domain search over objects visible to the caller.
    externalDocs:
      description: Search and discovery guide
      url: https://docs.revoengine.com/platform/search
  - name: Secrets
    description: >-
      Secret definitions, revision history, explicit rotation, activation,
      reveal, disable, and destruction.
    externalDocs:
      description: Secrets guide
      url: https://docs.revoengine.com/operate/secrets
  - name: Share
    description: >-
      Short-lived authenticated links to supported application routes and grid
      state.
    externalDocs:
      description: Platform API share-link guide
      url: >-
        https://docs.revoengine.com/developers/platform-api#share-application-context
  - name: Storage
    description: >-
      Storage workspaces, folders, objects, upload sessions, signed access, and
      lifecycle.
    externalDocs:
      description: Storage guide
      url: https://docs.revoengine.com/operate/storage
externalDocs:
  description: Documentation
  url: https://docs.revoengine.com
paths:
  /api/v1/agents/{agentId}/terminals:
    get:
      tags:
        - Agents
      summary: Find selectable terminals for an Agent
      description: >-
        Search approved terminals under the Agent assigned Service Account live
        device and workspace permissions, including Group membership. An
        explicitly selected assignable Service Account may be previewed while
        editing. Returns bounded paged grants with names, readable workspaces
        and live presence; does not activate the execution identity or grant
        access.
      operationId: AgentController_listAgentTerminals
      parameters:
        - name: agentId
          required: true
          in: path
          schema:
            type: string
        - name: serviceAccountUserId
          required: false
          in: query
          description: >-
            Execution Service Account to preview while editing. Required for a
            new Agent; existing Agents default to their assigned Service
            Account.
          schema:
            type: string
            format: uuid
        - name: search
          required: false
          in: query
          description: Literal terminal or workspace name search.
          schema:
            maxLength: 100
            type: string
        - name: skip
          required: false
          in: query
          schema:
            type: number
            default: 0
            minimum: 0
        - name: take
          required: false
          in: query
          schema:
            minimum: 1
            maximum: 50
            default: 50
            type: number
        - name: agentTerminalIds
          required: false
          in: query
          description: >-
            Hydrate only selected terminal IDs, still constrained by the Service
            Account live ACL.
          schema:
            maxItems: 50
            type: array
            items:
              type: string
              format: uuid
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TerminalGrantGridDto'
      security:
        - bearer: []
components:
  schemas:
    TerminalGrantGridDto:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TerminalGrantDto'
        results:
          type: number
        total:
          type: number
        next:
          type: boolean
      required:
        - data
        - results
        - total
        - next
    TerminalGrantDto:
      type: object
      properties:
        refToken:
          type: string
          description: Clickable terminal resource reference.
        agentTerminalId:
          type: string
          format: uuid
        ownerUserId:
          type: string
          format: uuid
        name:
          type: string
        workspace:
          type: string
        workspaces:
          description: Atomic workspace permission contract under the terminal revision.
          type: array
          items:
            $ref: '#/components/schemas/TerminalWorkspaceDto'
        status:
          type: string
          enum:
            - pending
            - approved
        mode:
          type: string
          enum:
            - review
            - full
        networkMode:
          type: string
          enum:
            - restricted
            - sandbox
            - external
        revision:
          type: number
        connectionRevision:
          type: number
          description: >-
            Runner and conversation connection epoch; command review mode edits
            keep it unchanged.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        lastOnlineAt:
          format: date-time
          type: string
          nullable: true
        online:
          type: boolean
        connectionIp:
          type: string
          nullable: true
          description: Gateway-observed IP of the active runner, visible only to its owner.
        canManage:
          type: boolean
        restricted:
          type: boolean
        users:
          type: array
          items:
            type: string
        groups:
          type: array
          items:
            type: string
        createdBy:
          type: string
          format: uuid
        lastUpdateAt:
          type: string
          format: date-time
        lastUpdateBy:
          type: string
          format: uuid
        version:
          type: number
      required:
        - agentTerminalId
        - ownerUserId
        - name
        - workspace
        - workspaces
        - status
        - mode
        - networkMode
        - revision
        - connectionRevision
        - createdAt
        - updatedAt
        - restricted
        - users
        - groups
    TerminalWorkspaceDto:
      type: object
      properties:
        agentTerminalWorkspaceId:
          type: string
          format: uuid
        name:
          type: string
          maxLength: 128
        path:
          type: string
          maxLength: 2048
        status:
          type: string
          enum:
            - pending
            - approved
        mode:
          type: string
          enum:
            - review
            - full
        networkMode:
          type: string
          enum:
            - restricted
            - sandbox
            - external
        restricted:
          type: boolean
        users:
          type: array
          items:
            type: string
            format: uuid
        groups:
          type: array
          items:
            type: string
            format: uuid
        inheritDevicePermissions:
          type: boolean
          description: >-
            Use device permission ceilings directly; default workspace preserves
            existing grants.
      required:
        - agentTerminalWorkspaceId
        - name
        - path
        - status
        - mode
        - networkMode
        - restricted
        - users
        - groups
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      description: Bearer JWT token or API Key (sk-*).
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.