Toolcog home
Search ⌘ + K

Command Palette

Search for a command to run...

Sign In

Create a codespace in a repository

POST /repos/{owner}/{repo}/codespaces
Copy endpoint
https://api.github.com

Creates a codespace owned by the authenticated user in the specified repository.

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

Parameters

path Path Parameters

Name Type
owner required

The account owner of the repository. The name is not case sensitive.
string
repo required

The name of the repository without the .git extension. The name is not case sensitive.
string

Request Body

application/json required
{
ref?: string;
location?: string;
geo?: "EuropeWest" | "SoutheastAsia" | "UsEast" | "UsWest";
client_ip?: string;
machine?: string;
devcontainer_path?: string;
multi_repo_permissions_opt_out?: boolean;
working_directory?: string;
idle_timeout_minutes?: number;
display_name?: string;
retention_period_minutes?: number;
} | null

Responses

201 application/json

Response when the codespace was successfully created

interface Codespace {
id: number;
name: string;
display_name?: string | null;
environment_id: string | null;
owner: SimpleUser

A GitHub user.

interface SimpleUser {
name?: string | null;
email?: string | null;
login: string;
id: number;
node_id: string;
avatar_url: string;
gravatar_id: string | null;
url: string;
html_url: string;
followers_url: string;
following_url: string;
gists_url: string;
starred_url: string;
subscriptions_url: string;
organizations_url: string;
repos_url: string;
events_url: string;
received_events_url: string;
type: string;
site_admin: boolean;
starred_at?: string;
user_view_type?: string;
}
;
billable_owner: SimpleUser

A GitHub user.

interface SimpleUser {
name?: string | null;
email?: string | null;
login: string;
id: number;
node_id: string;
avatar_url: string;
gravatar_id: string | null;
url: string;
html_url: string;
followers_url: string;
following_url: string;
gists_url: string;
starred_url: string;
subscriptions_url: string;
organizations_url: string;
repos_url: string;
events_url: string;
received_events_url: string;
type: string;
site_admin: boolean;
starred_at?: string;
user_view_type?: string;
}
;
repository: MinimalRepository

Minimal Repository

interface MinimalRepository {
id: number;
node_id: string;
name: string;
full_name: string;
owner: SimpleUser;
private: boolean;
html_url: string;
description: string | null;
fork: boolean;
url: string;
archive_url: string;
assignees_url: string;
blobs_url: string;
branches_url: string;
collaborators_url: string;
comments_url: string;
commits_url: string;
compare_url: string;
contents_url: string;
contributors_url: string;
deployments_url: string;
downloads_url: string;
events_url: string;
forks_url: string;
git_commits_url: string;
git_refs_url: string;
git_tags_url: string;
git_url?: string;
issue_comment_url: string;
issue_events_url: string;
issues_url: string;
keys_url: string;
labels_url: string;
languages_url: string;
merges_url: string;
milestones_url: string;
notifications_url: string;
pulls_url: string;
releases_url: string;
ssh_url?: string;
stargazers_url: string;
statuses_url: string;
subscribers_url: string;
subscription_url: string;
tags_url: string;
teams_url: string;
trees_url: string;
clone_url?: string;
mirror_url?: string | null;
hooks_url: string;
svn_url?: string;
homepage?: string | null;
language?: string | null;
forks_count?: number;
stargazers_count?: number;
watchers_count?: number;
size?: number;
default_branch?: string;
open_issues_count?: number;
is_template?: boolean;
topics?: string[];
has_issues?: boolean;
has_projects?: boolean;
has_wiki?: boolean;
has_pages?: boolean;
has_downloads?: boolean;
has_discussions?: boolean;
archived?: boolean;
disabled?: boolean;
visibility?: string;
pushed_at?: string | null;
created_at?: string | null;
updated_at?: string | null;
permissions?: {
admin?: boolean;
maintain?: boolean;
push?: boolean;
triage?: boolean;
pull?: boolean;
};
role_name?: string;
temp_clone_token?: string;
delete_branch_on_merge?: boolean;
subscribers_count?: number;
network_count?: number;
code_of_conduct?: CodeOfConduct;
license?: {
key?: string;
name?: string;
spdx_id?: string;
url?: string;
node_id?: string;
} | null;
forks?: number;
open_issues?: number;
watchers?: number;
allow_forking?: boolean;
web_commit_signoff_required?: boolean;
security_and_analysis?: SecurityAndAnalysis;
custom_properties?: { };
}
;
machine: CodespaceMachine

A description of the machine powering a codespace.

interface CodespaceMachine {
name: string;
display_name: string;
operating_system: string;
storage_in_bytes: number;
memory_in_bytes: number;
cpus: number;
prebuild_availability: "none" | "ready" | "in_progress" | null;
}
| null;
devcontainer_path?: string | null;
prebuild: boolean | null;
created_at: string;
updated_at: string;
last_used_at: string;
state: "Unknown" | "Created" | "Queued" | "Provisioning" | "Available" | "Awaiting" | "Unavailable" | "Deleted" | "Moved" | "Shutdown" | "Archived" | "Starting" | "ShuttingDown" | "Failed" | "Exporting" | "Updating" | "Rebuilding";
url: string;
git_status: {
ahead?: number;
behind?: number;
has_unpushed_changes?: boolean;
has_uncommitted_changes?: boolean;
ref?: string;
};
location: "EastUs" | "SouthEastAsia" | "WestEurope" | "WestUs2";
idle_timeout_minutes: number | null;
web_url: string;
machines_url: string;
start_url: string;
stop_url: string;
publish_url?: string | null;
pulls_url: string | null;
recent_folders: string[];
runtime_constraints?: { allowed_port_privacy_settings?: string[] | null; };
pending_operation?: boolean | null;
pending_operation_disabled_reason?: string | null;
idle_timeout_notice?: string | null;
retention_period_minutes?: number | null;
retention_expires_at?: string | null;
last_known_stop_notice?: string | null;
}
202 application/json

Response when the codespace creation partially failed but is being retried in the background

interface Codespace {
id: number;
name: string;
display_name?: string | null;
environment_id: string | null;
owner: SimpleUser

A GitHub user.

interface SimpleUser {
name?: string | null;
email?: string | null;
login: string;
id: number;
node_id: string;
avatar_url: string;
gravatar_id: string | null;
url: string;
html_url: string;
followers_url: string;
following_url: string;
gists_url: string;
starred_url: string;
subscriptions_url: string;
organizations_url: string;
repos_url: string;
events_url: string;
received_events_url: string;
type: string;
site_admin: boolean;
starred_at?: string;
user_view_type?: string;
}
;
billable_owner: SimpleUser

A GitHub user.

interface SimpleUser {
name?: string | null;
email?: string | null;
login: string;
id: number;
node_id: string;
avatar_url: string;
gravatar_id: string | null;
url: string;
html_url: string;
followers_url: string;
following_url: string;
gists_url: string;
starred_url: string;
subscriptions_url: string;
organizations_url: string;
repos_url: string;
events_url: string;
received_events_url: string;
type: string;
site_admin: boolean;
starred_at?: string;
user_view_type?: string;
}
;
repository: MinimalRepository

Minimal Repository

interface MinimalRepository {
id: number;
node_id: string;
name: string;
full_name: string;
owner: SimpleUser;
private: boolean;
html_url: string;
description: string | null;
fork: boolean;
url: string;
archive_url: string;
assignees_url: string;
blobs_url: string;
branches_url: string;
collaborators_url: string;
comments_url: string;
commits_url: string;
compare_url: string;
contents_url: string;
contributors_url: string;
deployments_url: string;
downloads_url: string;
events_url: string;
forks_url: string;
git_commits_url: string;
git_refs_url: string;
git_tags_url: string;
git_url?: string;
issue_comment_url: string;
issue_events_url: string;
issues_url: string;
keys_url: string;
labels_url: string;
languages_url: string;
merges_url: string;
milestones_url: string;
notifications_url: string;
pulls_url: string;
releases_url: string;
ssh_url?: string;
stargazers_url: string;
statuses_url: string;
subscribers_url: string;
subscription_url: string;
tags_url: string;
teams_url: string;
trees_url: string;
clone_url?: string;
mirror_url?: string | null;
hooks_url: string;
svn_url?: string;
homepage?: string | null;
language?: string | null;
forks_count?: number;
stargazers_count?: number;
watchers_count?: number;
size?: number;
default_branch?: string;
open_issues_count?: number;
is_template?: boolean;
topics?: string[];
has_issues?: boolean;
has_projects?: boolean;
has_wiki?: boolean;
has_pages?: boolean;
has_downloads?: boolean;
has_discussions?: boolean;
archived?: boolean;
disabled?: boolean;
visibility?: string;
pushed_at?: string | null;
created_at?: string | null;
updated_at?: string | null;
permissions?: {
admin?: boolean;
maintain?: boolean;
push?: boolean;
triage?: boolean;
pull?: boolean;
};
role_name?: string;
temp_clone_token?: string;
delete_branch_on_merge?: boolean;
subscribers_count?: number;
network_count?: number;
code_of_conduct?: CodeOfConduct;
license?: {
key?: string;
name?: string;
spdx_id?: string;
url?: string;
node_id?: string;
} | null;
forks?: number;
open_issues?: number;
watchers?: number;
allow_forking?: boolean;
web_commit_signoff_required?: boolean;
security_and_analysis?: SecurityAndAnalysis;
custom_properties?: { };
}
;
machine: CodespaceMachine

A description of the machine powering a codespace.

interface CodespaceMachine {
name: string;
display_name: string;
operating_system: string;
storage_in_bytes: number;
memory_in_bytes: number;
cpus: number;
prebuild_availability: "none" | "ready" | "in_progress" | null;
}
| null;
devcontainer_path?: string | null;
prebuild: boolean | null;
created_at: string;
updated_at: string;
last_used_at: string;
state: "Unknown" | "Created" | "Queued" | "Provisioning" | "Available" | "Awaiting" | "Unavailable" | "Deleted" | "Moved" | "Shutdown" | "Archived" | "Starting" | "ShuttingDown" | "Failed" | "Exporting" | "Updating" | "Rebuilding";
url: string;
git_status: {
ahead?: number;
behind?: number;
has_unpushed_changes?: boolean;
has_uncommitted_changes?: boolean;
ref?: string;
};
location: "EastUs" | "SouthEastAsia" | "WestEurope" | "WestUs2";
idle_timeout_minutes: number | null;
web_url: string;
machines_url: string;
start_url: string;
stop_url: string;
publish_url?: string | null;
pulls_url: string | null;
recent_folders: string[];
runtime_constraints?: { allowed_port_privacy_settings?: string[] | null; };
pending_operation?: boolean | null;
pending_operation_disabled_reason?: string | null;
idle_timeout_notice?: string | null;
retention_period_minutes?: number | null;
retention_expires_at?: string | null;
last_known_stop_notice?: string | null;
}

Client Errors

400 application/json

Bad Request

interface BasicError {
message?: string;
documentation_url?: string;
url?: string;
status?: string;
}
401 application/json

Requires authentication

interface BasicError {
message?: string;
documentation_url?: string;
url?: string;
status?: string;
}
403 application/json

Forbidden

interface BasicError {
message?: string;
documentation_url?: string;
url?: string;
status?: string;
}
404 application/json

Resource not found

interface BasicError {
message?: string;
documentation_url?: string;
url?: string;
status?: string;
}

Server Errors

503 application/json

Service unavailable

{ code?: string;message?: string;documentation_url?: string; }