organizations

Creates, updates, deletes, gets or lists an organizations resource.

Overview

Name	organizations
Type	Resource
Id	github.codespaces.organizations

Fields

The following fields are returned by SELECT queries:

get_codespaces_for_user_in_org

Response

Name	Datatype	Description
codespaces	array
total_count	integer

list_in_organization

Response

Name	Datatype	Description
id	integer (int64)
name	string	Automatically generated name of this codespace. (example: monalisa-octocat-hello-world-g4wpq6h95q)
environment_id	string	UUID identifying this codespace's environment. (example: 26a7c758-7299-4a73-b978-5a92a7ae98a0)
display_name	string	Display name for this codespace. (example: bookish space pancake)
billable_owner	object	A GitHub user. (title: Simple User)
created_at	string (date-time)	(example: 2011-01-26T19:01:12Z)
devcontainer_path	string	Path to devcontainer.json from repo root used to create Codespace. (example: .devcontainer/example/devcontainer.json)
git_status	object	Details about the codespace's git repository.
idle_timeout_minutes	integer	The number of minutes of inactivity after which this codespace will be automatically stopped.
idle_timeout_notice	string	Text to show user when codespace idle timeout minutes has been overriden by an organization policy
last_known_stop_notice	string	The text to display to a user when a codespace has been stopped for a potentially actionable reason. (example: you've used 100% of your spending limit for Codespaces)
last_used_at	string (date-time)	Last known time this codespace was started. (example: 2011-01-26T19:01:12Z)
location	string	The initally assigned location of a new codespace. (EastUs, SouthEastAsia, WestEurope, WestUs2) (example: WestUs2)
machine	object	A description of the machine powering a codespace. (title: Codespace machine)
machines_url	string (uri)	API URL to access available alternate machine types for this codespace.
owner	object	A GitHub user. (title: Simple User)
pending_operation	boolean	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_reason	string	Text to show user when codespace is disabled by a pending operation
prebuild	boolean	Whether the codespace was created from a prebuild.
publish_url	string (uri)	API URL to publish this codespace to a new repository.
pulls_url	string (uri)	API URL for the Pull Request associated with this codespace, if any.
recent_folders	array
repository	object	Minimal Repository (title: Minimal Repository)
retention_expires_at	string (date-time)	When a codespace will be auto-deleted based on the "retention_period_minutes" and "last_used_at" (example: 2011-01-26T20:01:12Z)
retention_period_minutes	integer	Duration in minutes after codespace has gone idle in which it will be deleted. Must be integer minutes between 0 and 43200 (30 days).
runtime_constraints	object
start_url	string (uri)	API URL to start this codespace.
state	string	State of this codespace. (Unknown, Created, Queued, Provisioning, Available, Awaiting, Unavailable, Deleted, Moved, Shutdown, Archived, Starting, ShuttingDown, Failed, Exporting, Updating, Rebuilding) (example: Available)
stop_url	string (uri)	API URL to stop this codespace.
updated_at	string (date-time)	(example: 2011-01-26T19:01:12Z)
url	string (uri)	API URL for this codespace.
web_url	string (uri)	URL to access this codespace on the web.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_codespaces_for_user_in_org	select	org, username	per_page, page	Lists the codespaces that a member of an organization has for repositories in that organization. OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.
list_in_organization	select	org	per_page, page	Lists the codespaces associated to a specified organization. OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.
set_codespaces_access	replace	org, visibility		Sets which users can access codespaces in an organization. This is synonymous with granting or revoking codespaces access permissions for users according to the visibility. OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.
delete_from_organization	delete	org, username, codespace_name		Deletes a user's codespace. OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.
delete_codespaces_access_users	delete	org		Codespaces for the specified users will no longer be billed to the organization. To use this endpoint, the access settings for the organization must be set to selected_members. For information on how to change this setting, see "Manage access control for organization codespaces." OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.
set_codespaces_access_users	exec	org, selected_usernames		Codespaces for the specified users will be billed to the organization. To use this endpoint, the access settings for the organization must be set to selected_members. For information on how to change this setting, see "Manage access control for organization codespaces." OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.
stop_in_organization	exec	org, username, codespace_name		Stops a user's codespace. OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
codespace_name	string	The name of the codespace.
org	string	The organization name. The name is not case sensitive.
username	string	The handle for the GitHub user account.
page	integer	The page number of the results to fetch. For more information, see "Using pagination in the REST API."
per_page	integer	The number of results per page (max 100). For more information, see "Using pagination in the REST API."

SELECT examples

get_codespaces_for_user_in_org

Lists the codespaces that a member of an organization has for repositories in that organization.

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

SELECT
codespaces,
total_count
FROM github.codespaces.organizations
WHERE org = '{{ org }}' -- required
AND username = '{{ username }}' -- required
AND per_page = '{{ per_page }}'
AND page = '{{ page }}'
;

list_in_organization

Lists the codespaces associated to a specified organization.

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

SELECT
id,
name,
environment_id,
display_name,
billable_owner,
created_at,
devcontainer_path,
git_status,
idle_timeout_minutes,
idle_timeout_notice,
last_known_stop_notice,
last_used_at,
location,
machine,
machines_url,
owner,
pending_operation,
pending_operation_disabled_reason,
prebuild,
publish_url,
pulls_url,
recent_folders,
repository,
retention_expires_at,
retention_period_minutes,
runtime_constraints,
start_url,
state,
stop_url,
updated_at,
url,
web_url
FROM github.codespaces.organizations
WHERE org = '{{ org }}' -- required
AND per_page = '{{ per_page }}'
AND page = '{{ page }}'
;

REPLACE examples

set_codespaces_access

Sets which users can access codespaces in an organization. This is synonymous with granting or revoking codespaces access permissions for users according to the visibility.
OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

REPLACE github.codespaces.organizations
SET 
visibility = '{{ visibility }}',
selected_usernames = '{{ selected_usernames }}'
WHERE 
org = '{{ org }}' --required
AND visibility = '{{ visibility }}' --required;

DELETE examples

delete_from_organization

Deletes a user's codespace.

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

DELETE FROM github.codespaces.organizations
WHERE org = '{{ org }}' --required
AND username = '{{ username }}' --required
AND codespace_name = '{{ codespace_name }}' --required
;

delete_codespaces_access_users

Codespaces for the specified users will no longer be billed to the organization.

To use this endpoint, the access settings for the organization must be set to selected_members.
For information on how to change this setting, see "Manage access control for organization codespaces."

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

DELETE FROM github.codespaces.organizations
WHERE org = '{{ org }}' --required
;

Lifecycle Methods

set_codespaces_access_users

Codespaces for the specified users will be billed to the organization.

To use this endpoint, the access settings for the organization must be set to selected_members.
For information on how to change this setting, see "Manage access control for organization codespaces."

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

EXEC github.codespaces.organizations.set_codespaces_access_users 
@org='{{ org }}' --required 
@@json=
'{
"selected_usernames": "{{ selected_usernames }}"
}'
;

stop_in_organization

Stops a user's codespace.

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

EXEC github.codespaces.organizations.stop_in_organization 
@org='{{ org }}' --required, 
@username='{{ username }}' --required, 
@codespace_name='{{ codespace_name }}' --required
;