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

# List Workspaces

> Returns paginated workspaces with repository associations and pull request states.



## OpenAPI

````yaml /openapi.json get /v1/workspaces
openapi: 3.1.0
info:
  title: Replica API
  version: 2.0.0
  description: >-
    The Replica API allows you to programmatically manage cloud workspaces for
    AI agents. Use this API to manage environments (the org-scoped primitive
    workspaces are created from — including variables, files, skills, MCPs, warm
    hooks, start hooks, and warm pools), create and manage replicas, send
    messages, manage chats, stream events, read connected repositories and
    repository sets, and configure automations.
servers:
  - url: https://api.replicas.dev
    description: Production API
security:
  - apiKey: []
tags:
  - name: Environments
    description: >-
      Manage environments — the primitive that workspaces are created from.
      Variables, files, skills, MCPs, warm-hooks, and warm-pools are all scoped
      to an environment. Every organization has a singleton Global environment
      whose values apply to every workspace. Personal environments are scoped to
      the authenticated user and can be standalone or source-backed by a team
      environment.
  - name: Repository
    description: >-
      Read repositories and repository sets connected to your organization.
      Repositories are the underlying GitHub-connection layer; bind them to an
      environment to use them in workspaces.
  - name: Replica
    description: >-
      Manage replicas (workspaces) for AI agents. Workspace creation with `POST
      /v1/replica` accepts API keys and workspace engine-secret authentication.
      Other Replica operations also accept logged-in user JWTs from first-party
      clients.
  - name: Terminal
    description: Manage interactive terminal sessions in active workspaces
  - name: Preview
    description: Manage public preview URLs for workspace ports
  - name: Profile
    description: Read and update the authenticated user's profile
  - name: Credentials
    description: >-
      Manage coding-agent credentials for an organization or the authenticated
      user
  - name: Preferences
    description: Manage organization behavior preferences
  - name: Slack
    description: Connect Slack identities and route threads to Replicas workspaces
  - name: Linear
    description: Connect Linear identities to Replicas accounts
  - name: Automation
    description: >-
      Create and manage automations that trigger replicas on a schedule or in
      response to events
  - name: Downloads
    description: Download Replicas applications
  - name: Media
    description: >-
      Read workspace media and obtain short-lived download or inline preview
      URLs
  - name: Analytics
    description: >-
      Read aggregated activity and usage metrics for your organization: compute
      minutes, workspaces created by source, and pull request throughput over a
      time range.
  - name: Presence
    description: >-
      Read and report ephemeral member presence: who is online, where they are
      (environment or workspace), and whether they are typing. Presence is
      backed by short-lived keys rather than the database and broadcast to other
      members over the events stream.
  - name: Plugins
    description: >-
      Install and manage native and Composio-backed workspace plugins. A plugin
      installs for a single environment, for the whole organization (which uses
      the Global environment), or for one member personally. A workspace uses
      the most specific installation available: personal, then its own
      environment, then the environment it was branched from, then Global.
      Composio Connect Links host managed OAuth, custom OAuth, API-key,
      bearer-token, basic, and dynamic OAuth authentication without exposing
      provider credentials to Replicas.
paths:
  /v1/workspaces:
    get:
      tags:
        - Replica
      summary: List Workspaces
      description: >-
        Returns paginated workspaces with repository associations and pull
        request states.
      operationId: listWorkspaces
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 10
            minimum: 1
        - name: name
          in: query
          description: Filter workspaces by name.
          required: false
          schema:
            type: string
        - name: viewModes
          in: query
          description: Comma-separated workspace views, such as `owned,shared`.
          required: false
          schema:
            type: string
        - name: archived
          in: query
          description: Controls whether archived workspaces are included.
          required: false
          schema:
            type: string
            enum:
              - include
              - exclude
              - only
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkspacesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ListWorkspacesResponse:
      type: object
      properties:
        workspaces:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceListItem'
        workspace_repositories:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceRepository'
        workspace_pull_requests:
          type: array
          items:
            $ref: '#/components/schemas/WorkspacePullRequestState'
        workspace_turn_completed_at:
          type: object
          description: Latest completed turn timestamp by workspace ID.
          additionalProperties:
            type: string
            format: date-time
        creator_names:
          type: object
          additionalProperties:
            type: string
        creator_avatar_urls:
          type: object
          additionalProperties:
            type: string
            format: uri
        shared_with:
          type: object
          additionalProperties:
            type: array
        viewer_share_ids:
          type: array
          items:
            type: string
            format: uuid
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
        totalPages:
          type: integer
      required:
        - workspaces
        - total
        - page
        - limit
        - totalPages
    WorkspaceListItem:
      type: object
      description: A workspace returned by the dashboard workspace list.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        status:
          type: string
          enum:
            - active
            - sleeping
            - archived
            - preparing
            - error
        created_at:
          type: string
          format: date-time
        last_activity_at:
          type:
            - string
            - 'null'
          format: date-time
        source_link:
          type: object
          description: >-
            Link back to the Slack thread or Linear issue that started the
            workspace. Omitted when the workspace was not started from Slack or
            Linear.
          properties:
            source:
              type: string
              enum:
                - slack
                - linear
            url:
              type: string
              format: uri
            label:
              type: string
              description: Display text, such as a Linear issue identifier.
          required:
            - source
            - url
            - label
      required:
        - id
        - name
        - status
        - created_at
        - last_activity_at
    WorkspaceRepository:
      type: object
      description: A repository associated with a workspace.
      properties:
        id:
          type: string
          format: uuid
        workspace_id:
          type: string
          format: uuid
        provider:
          type: string
          enum:
            - github
            - gitlab
        name:
          type: string
        url:
          type: string
          format: uri
        default_branch:
          type: string
      required:
        - id
        - workspace_id
        - provider
        - name
        - url
        - default_branch
    WorkspacePullRequestState:
      type: object
      description: The latest pull request state associated with a workspace.
      properties:
        workspace_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - open
            - closed
            - merged
        url:
          type: string
          format: uri
          nullable: true
      required:
        - workspace_id
        - status
        - url
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
        details:
          type:
            - string
            - 'null'
          description: Additional error details
      required:
        - error
  responses:
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        API key authentication. Obtain your API key from the Replicas dashboard
        under Organization → Settings → API Keys.

````