> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryreplicas.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Dashboard Workspace > Creates a workspace from an environment for the authenticated dashboard user. `repository_branches` can override the starting branch for repositories in that environment; repositories without an override use their configured default branch. ## OpenAPI ````yaml /openapi.json post /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.tryreplicas.com 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. paths: /v1/workspaces: post: tags: - Replica summary: Create Dashboard Workspace description: >- Creates a workspace from an environment for the authenticated dashboard user. `repository_branches` can override the starting branch for repositories in that environment; repositories without an override use their configured default branch. operationId: createDashboardWorkspace requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWorkspaceRequest' responses: '201': description: Workspace created content: application/json: schema: $ref: '#/components/schemas/CreateWorkspaceResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': description: Workspace creation rate or concurrency limit reached '500': $ref: '#/components/responses/InternalServerError' security: - userJwt: [] components: schemas: CreateWorkspaceRequest: type: object description: Dashboard workspace creation request. properties: name: type: string description: Optional workspace name. A placeholder is generated when omitted. environment_id: type: string format: uuid description: >- Environment whose repository binding and configuration the workspace uses. repository_branches: type: object description: >- Optional starting-branch overrides keyed by repository UUID. Every repository must belong to the selected environment. Omitted repositories use their configured default branch. propertyNames: type: string format: uuid additionalProperties: type: string minLength: 1 maxLength: 255 config: $ref: '#/components/schemas/WorkspaceConfig' size: type: string enum: - small - large required: - environment_id CreateWorkspaceResponse: type: object properties: workspace: $ref: '#/components/schemas/WorkspaceListItem' required: - workspace WorkspaceConfig: type: object description: >- Workspace behavior configuration. Missing capabilities and preferences default to disabled. properties: capabilities: type: object description: >- Actions this workspace is allowed to perform. Automations snapshot this config onto each workspace they create; API-created replicas can set it at creation time. properties: pr_followups: type: boolean description: >- Whether matching pull requests can receive Replicas follow-up actions. Defaults to true for workspaces created from the dashboard, Slack, Linear, GitHub, or the API, and to false for workspaces created from an automation. When enabled, later CI and review-comment replies can route back to this workspace. read_only_contents: type: boolean description: >- Whether the workspace GitHub token is restricted to read-only repository contents, keeping write access for pull request comments, issues, and checks. Defaults to false, so the workspace can push branches and open pull requests. additionalProperties: true preferences: type: object description: >- Workspace behavior preferences that do not grant new action permissions. properties: keep_open_on_pr_merge: type: boolean description: >- Whether the workspace should remain open after its last tracked PR is merged. Defaults to false. default: false keep_open_on_pr_close: type: boolean description: >- Whether the workspace should remain open after its last tracked PR is closed without merging. Defaults to false. default: false additionalProperties: true provisioning_error: type: object description: >- Setup/provisioning or wake/resume failure captured when the workspace remains queryable in `error` status. Some wake/resume failures can be retried; the `error` status can also represent an unrecoverable sandbox failure. properties: message: type: string description: >- Underlying setup failure message, such as repository clone/auth errors. additionalProperties: true additionalProperties: true 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 Error: type: object properties: error: type: string description: Error message details: type: - string - 'null' description: Additional error details required: - error responses: BadRequest: description: Bad request - Missing or invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' PaymentRequired: description: >- Payment Required - The organization is out of included minutes or its free trial has ended content: application/json: schema: type: object properties: error: type: string description: Error message code: type: string enum: - INSUFFICIENT_MINUTES - TRIAL_EXPIRED description: Machine-readable billing block reason required: - error - code Forbidden: description: Forbidden - The authenticated account cannot access this resource content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource not found 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. userJwt: type: http scheme: bearer description: >- Logged-in user-session JWT authentication for first-party clients. Org-scoped requests also require the `Replicas-Org-Id` header. User JWTs cannot create workspaces with `POST /v1/replica`. ````