REST API endpoints for Codespaces machines

About Codespaces machines

You can determine which machine types are available to create a codespace, either on a given repository or as an authenticated user. For more information, see Changing the machine type for your codespace.

You can also use this information when changing the machine of an existing codespace by updating its machine property. The machine update will take place the next time the codespace is restarted. For more information, see Changing the machine type for your codespace.

List available machine types for a repository

List the machine types available for a given repository based on its configuration.

OAuth app tokens and personal access tokens (classic) need the codespace scope to use this endpoint.

Fine-grained access tokens for "List available machine types for a repository"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Codespaces metadata" repository permissions (read)

Parameters for "List available machine types for a repository"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository without the `.git` extension. The name is not case sensitive.

Query parameters
Name, Type, Description
`location` string The location to check for available machines. Assigned by IP if not provided.
`client_ip` string IP for location auto-detection when proxying a request
`ref` string The branch or commit to check for prebuild availability and devcontainer restrictions.

HTTP response status codes for "List available machine types for a repository"

Status code	Description
`200`	OK
`304`	Not modified
`401`	Requires authentication
`403`	Forbidden
`404`	Resource not found
`500`	Internal Error

Code samples for "List available machine types for a repository"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/repos/{owner}/{repo}/codespaces/machines

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/codespaces/machines

Response

Status: 200

{
  "total_count": 2,
  "machines": [
    {
      "name": "standardLinux",
      "display_name": "4 cores, 16 GB RAM, 64 GB storage",
      "operating_system": "linux",
      "storage_in_bytes": 68719476736,
      "memory_in_bytes": 17179869184,
      "cpus": 4
    },
    {
      "name": "premiumLinux",
      "display_name": "8 cores, 32 GB RAM, 64 GB storage",
      "operating_system": "linux",
      "storage_in_bytes": 68719476736,
      "memory_in_bytes": 34359738368,
      "cpus": 8
    }
  ]
}

List machine types for a codespace

List the machine types a codespace can transition to use.

OAuth app tokens and personal access tokens (classic) need the codespace scope to use this endpoint.

Fine-grained access tokens for "List machine types for a codespace"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Codespaces metadata" repository permissions (read)

Parameters for "List machine types for a codespace"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`codespace_name` string Required The name of the codespace.

HTTP response status codes for "List machine types for a codespace"

Status code	Description
`200`	OK
`304`	Not modified
`401`	Requires authentication
`403`	Forbidden
`404`	Resource not found
`500`	Internal Error

Code samples for "List machine types for a codespace"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/user/codespaces/{codespace_name}/machines

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/user/codespaces/CODESPACE_NAME/machines

Response

Status: 200

{
  "total_count": 2,
  "machines": [
    {
      "name": "standardLinux",
      "display_name": "4 cores, 16 GB RAM, 64 GB storage",
      "operating_system": "linux",
      "storage_in_bytes": 68719476736,
      "memory_in_bytes": 17179869184,
      "cpus": 4
    },
    {
      "name": "premiumLinux",
      "display_name": "8 cores, 32 GB RAM, 64 GB storage",
      "operating_system": "linux",
      "storage_in_bytes": 68719476736,
      "memory_in_bytes": 34359738368,
      "cpus": 8
    }
  ]
}