GitHub API (unofficial showcase)
POST/user/codespaces

Create a codespace for the authenticated user

Creates a codespace owned by the authenticated user for a repository or pull request. Provide either repository_id or pull_request, but not both, and use geo to select a region when needed. A 202 response indicates that creation partially failed and is being retried in the background.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

12 body fields

Codespace creation details. Provide either repository_id or pull_request, but not both.

repository_idintegerrequired
Repository id for this codespace
refstringoptional
Git ref (typically a branch name) for this codespace
locationstringoptional
The requested location for a new codespace. Best efforts are made to respect this upon creation. Assigned by IP if not provided.
geostringoptional
The geographic area for this codespace. If not specified, the value is assigned by IP. This property replaces `location`, which is closing down.
Allowed:EuropeWestSoutheastAsiaUsEastUsWest
client_ipstringoptional
IP for location auto-detection when proxying a request
machinestringoptional
Machine type to use for this codespace
devcontainer_pathstringoptional
Path to devcontainer.json config to use for this codespace
multi_repo_permissions_opt_outbooleanoptional
Whether to authorize requested permissions from devcontainer.json
working_directorystringoptional
Working directory for this codespace
idle_timeout_minutesintegeroptional
Time in minutes before codespace stops from inactivity
display_namestringoptional
Display name for this codespace
retention_period_minutesintegeroptional
Duration in minutes after codespace has gone idle in which it will be deleted. Must be integer minutes between 0 and 43200 (30 days).

6 status codes
201Returns the created codespace object, including its identifier, name, owner, repository, machine, state, and API URL.
idintegerrequired
namestringrequired
Automatically generated name of this codespace.
display_namestringoptional
Display name for this codespace.
environment_idstringrequired
UUID identifying this codespace's environment.
ownerobjectrequired
A GitHub user.
billable_ownerobjectrequired
A GitHub user.
repositoryobjectrequired
Minimal Repository
machineobjectrequired
A description of the machine powering a codespace.
devcontainer_pathstringoptional
Path to devcontainer.json from repo root used to create Codespace.
prebuildbooleanrequired
Whether the codespace was created from a prebuild.
created_atstringrequired
updated_atstringrequired
last_used_atstringrequired
Last known time this codespace was started.
statestringrequired
State of this codespace.
Allowed:UnknownCreatedQueuedProvisioningAvailableAwaitingUnavailableDeletedMovedShutdownArchivedStarting
urlstringrequired
API URL for this codespace.
git_statusobjectrequired
Details about the codespace's git repository.
locationstringrequired
The initally assigned location of a new codespace.
Allowed:EastUsSouthEastAsiaWestEuropeWestUs2
idle_timeout_minutesintegerrequired
The number of minutes of inactivity after which this codespace will be automatically stopped.
web_urlstringrequired
URL to access this codespace on the web.
machines_urlstringrequired
API URL to access available alternate machine types for this codespace.
start_urlstringrequired
API URL to start this codespace.
stop_urlstringrequired
API URL to stop this codespace.
publish_urlstringoptional
API URL to publish this codespace to a new repository.
pulls_urlstringrequired
API URL for the Pull Request associated with this codespace, if any.
recent_foldersarray<string>required
runtime_constraintsobjectoptional
pending_operationbooleanoptional
Whether or not a codespace has a pending async operation. This would mean that the codespace is temporarily unavailable. The only thing that you can do with a codespace in this state is delete it.
pending_operation_disabled_reasonstringoptional
Text to show user when codespace is disabled by a pending operation
idle_timeout_noticestringoptional
Text to show user when codespace idle timeout minutes has been overriden by an organization policy
retention_period_minutesintegeroptional
Duration in minutes after codespace has gone idle in which it will be deleted. Must be integer minutes between 0 and 43200 (30 days).
retention_expires_atstringoptional
When a codespace will be auto-deleted based on the "retention_period_minutes" and "last_used_at"
last_known_stop_noticestringoptional
The text to display to a user when a codespace has been stopped for a potentially actionable reason.
202Returns the codespace object when creation partially failed and is being retried in the background.
idintegerrequired
namestringrequired
Automatically generated name of this codespace.
display_namestringoptional
Display name for this codespace.
environment_idstringrequired
UUID identifying this codespace's environment.
ownerobjectrequired
A GitHub user.
billable_ownerobjectrequired
A GitHub user.
repositoryobjectrequired
Minimal Repository
machineobjectrequired
A description of the machine powering a codespace.
devcontainer_pathstringoptional
Path to devcontainer.json from repo root used to create Codespace.
prebuildbooleanrequired
Whether the codespace was created from a prebuild.
created_atstringrequired
updated_atstringrequired
last_used_atstringrequired
Last known time this codespace was started.
statestringrequired
State of this codespace.
Allowed:UnknownCreatedQueuedProvisioningAvailableAwaitingUnavailableDeletedMovedShutdownArchivedStarting
urlstringrequired
API URL for this codespace.
git_statusobjectrequired
Details about the codespace's git repository.
locationstringrequired
The initally assigned location of a new codespace.
Allowed:EastUsSouthEastAsiaWestEuropeWestUs2
idle_timeout_minutesintegerrequired
The number of minutes of inactivity after which this codespace will be automatically stopped.
web_urlstringrequired
URL to access this codespace on the web.
machines_urlstringrequired
API URL to access available alternate machine types for this codespace.
start_urlstringrequired
API URL to start this codespace.
stop_urlstringrequired
API URL to stop this codespace.
publish_urlstringoptional
API URL to publish this codespace to a new repository.
pulls_urlstringrequired
API URL for the Pull Request associated with this codespace, if any.
recent_foldersarray<string>required
runtime_constraintsobjectoptional
pending_operationbooleanoptional
Whether or not a codespace has a pending async operation. This would mean that the codespace is temporarily unavailable. The only thing that you can do with a codespace in this state is delete it.
pending_operation_disabled_reasonstringoptional
Text to show user when codespace is disabled by a pending operation
idle_timeout_noticestringoptional
Text to show user when codespace idle timeout minutes has been overriden by an organization policy
retention_period_minutesintegeroptional
Duration in minutes after codespace has gone idle in which it will be deleted. Must be integer minutes between 0 and 43200 (30 days).
retention_expires_atstringoptional
When a codespace will be auto-deleted based on the "retention_period_minutes" and "last_used_at"
last_known_stop_noticestringoptional
The text to display to a user when a codespace has been stopped for a potentially actionable reason.
401Returned when the request lacks valid authentication.
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
403Returned when the authenticated user is not permitted to create the codespace or the required token scope is missing.
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
404Returned when the specified repository or pull request cannot be found.
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
503Returned when the service is unavailable.
codestringoptional
messagestringoptional
documentation_urlstringoptional

Error handling

A 401 is returned when the request lacks valid authentication. A 403 is returned when the authenticated user lacks permission, including when an OAuth app token or classic personal access token lacks the codespace scope. A 404 is returned when the specified repository cannot be found, and a 503 indicates that the service is unavailable. Provide either repository_id or pull_request, but not both; pull_request must include pull_request_number and repository_id. geo must be one of EuropeWest, SoutheastAsia, UsEast, or UsWest, and retention_period_minutes must be between 0 and 43200 when provided.