---
title: "Plan a workspace switch"
description: "Reports, without changing anything, what switching to a GitHub repository branch would do: reuse or create the computer for that workspace, and whether the branch exists."
canonical: "https://www.cool.computer/docs/api-reference/github/plan-a-workspace-switch"
---
# Plan a workspace switch

> Reports, without changing anything, what switching to a GitHub repository branch would do: reuse or create the computer for that workspace, and whether the branch exists.

```http
POST https://api.cool.computer/api/workspaces/switch/plan
```

Reports, without changing anything, what switching to a GitHub repository branch would do: reuse or create the computer for that workspace, and whether the branch exists. Callers: an account bearer (API key or access token).

## Authorization

- A Cool Computers API key, user access token, or claimed agent access token in the Authorization header. Follow https://www.cool.computer/auth.md for agent registration and https://www.cool.computer/authentication.md for direct user credentials.

## Request body

Required.

- `application/json` (object)
  - `repo` (string, required): owner/name of a repository the connected GitHub user can access.
  - `branch` (string, required)
  - `create` (boolean): Create the branch when it does not exist.
  - `from` (string): Base branch for a created branch.

## Responses

- `200`: The plan.
  - `application/json` (object)
    - `read_only` (boolean, required)
    - `ready` (boolean, required)
    - `repo` (string, required)
    - `branch` (string, required)
    - `create` (boolean, required)
    - `workspace_identity` (string, required)
    - `predicted_slug` (string, required)
    - `action` (string, required)
    - `reason` (string, required)
    - `existing_computer` (object)
      - `id` (string, required)
      - `hostname` (string, required)
      - `name` (string, required)
      - `ip` (string, required)
      - `status` (string, required): artifact (no VM), creating, running, stopped while its account's Pro has lapsed (its VM is stopped and deleted at auto_delete_at unless Pro returns; once Pro returns it can show running briefly until the reconciler has started its VM), or deleting from when its deletion begins until it is gone.
      - `url` (string, uri)
      - `email_address` (string, email)
      - `visibility` ("private" or "public", required)
      - `access` ("owner" or "can_use" or "claim_key", required): What the caller holds: owner, can_use for a computer shared with them, or claim_key in the response to a publish without an account, whose claim key republishes to the computer and claims it.
      - `copy_enabled` (boolean, required): People other than the owner may copy the computer into their own accounts (PUT /api/computers/{id}/copy-settings).
      - `site` (boolean, required): The URL serves the computer's published files: from the edge, or from its VM's built-in site server until a port is first exposed, when the program on it takes every path but the functions' for good.
      - `network_policy` (object, required): Outbound access policy. open allows public destinations, none blocks outbound access, and allowlist permits only the named public hosts. Private and reserved addresses remain blocked.
        - `mode` ("open" or "none" or "allowlist", required)
        - `allowed_hosts` (array of string, at most 100 items): Required and non-empty only when mode is allowlist. Each value is a hostname, public IP, or leading wildcard such as \*.example.com, without a scheme, port, path, or CIDR.
      - `created_at` (string, date-time, required)
      - `auto_delete_at` (string or null, date-time): When the computer is deleted by itself: its own auto-delete deadline, or, for a VM of an account whose Pro lapsed, when its stopped VMs are deleted, whichever comes first.
      - `creation_mode` (string)
    - `target_branch` (object, required)
      - `name` (string, required)
      - `exists` (boolean, required)
      - `source` (string)
    - `base_branch` (object)
      - `name` (string, required)
      - `exists` (boolean, required)
      - `source` (string)
    - `permission_preflight` (object, required)
      - `provider` (string, required)
      - `repository` (string, required)
      - `status` (string, required)
      - `token_scope` (string, required)
      - `permissions` (array of string, required)
    - `pull_requests` (object, required)
      - `status` (string, required)
      - `matches` (array of object, required)
        - `number` (integer, required)
        - `url` (string, required)
        - `state` (string, required)
        - `draft` (boolean, required)
        - `merged` (boolean, required)
        - `head_ref` (string, required)
        - `head_repo` (string, required)
        - `base_ref` (string, required)
      - `ambiguous` (boolean, required)
      - `error` (string)
    - `actions` (array of object, required)
      - `type` (string, required)
      - `target` (string, required)
      - `mutation` (boolean, required)
- `400`: Bad Request.
- `401`: Unauthorized.
- `402`: Payment Required. `pro_required`: VMs need Pro; start Pro with cool billing upgrade, or fix a lapsed subscription with cool billing portal, or use the Account page.
- `403`: Forbidden.
- `404`: Not Found.
- `409`: Conflict.
- `429`: Too Many Requests. If the problem code is api_request_rate_exceeded, wait for Retry-After seconds; other problem codes describe a separate limit.
- `500`: Internal Server Error.
- `default`: A machine-readable API error with a stable code and recovery instruction.

An error is an `application/problem+json` document with a stable `code`; [API errors](/docs/api-reference/errors) says how to handle one.

## Example

```sh
curl -X POST "https://api.cool.computer/api/workspaces/switch/plan" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  --data '{"repo":"octo-org/website","branch":"main"}'
```
