Toolcog home
Search ⌘ + K

Command Palette

Search for a command to run...

Sign In

Create a codespace for the authenticated user

POST /user/codespaces
Copy endpoint
https://api.github.com

Creates a new codespace, owned by the authenticated user.

This endpoint requires either a repository_id OR a pull_request but not both.

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

Request Body

application/json required
{
repository_id: number;
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;
} | {
pull_request: { pull_request_number: number;repository_id: number; };
location?: string;
geo?: "EuropeWest" | "SoutheastAsia" | "UsEast" | "UsWest";
machine?: string;
devcontainer_path?: string;
working_directory?: string;
idle_timeout_minutes?: number;
}

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

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; }