Gitpod Public API

The Gitpod Public API grants direct access to Gitpod data for use cases such as integration into other 3rd party applications.

This document addresses a basic subset of the Gitpod Classic HTTP API. For more powerful access to Gitpod, check out Ona and its API.

Authentication

To authenticate requests, the Gitpod API utilizes Access Token. In the Gitpod settings, you can view and manage your PATs. Keep in mind that your access tokens have a lot of power, so protect them carefully! Avoid disclosing your private Access Tokens in areas that are open to the public, such as GitHub, client-side code, and so forth. To Authenticate you will need to pass an Access Token as an Authorization request header bearer token in the format Bearer <YOUR_ACCESS_TOKEN>. Example cURL command:

cURL

curl -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/ListOrganizations' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{}'

Resource: Workspaces

Create and start a workspace

Creates and starts a new workspace from a context URL such as repositories, issues, pull requests, files URL.

curl -X POST \
  'https://api.gitpod.io/gitpod.v1.WorkspaceService/CreateAndStartWorkspace' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "contextUrl": {
    "url": "<CONTEXT_URL>",
    "workspaceClass": "g1-standard",
    "editor": {
      "name": "code",
      "version": "latest"
    }
  },
  "metadata": {
    "ownerId": "<USER_ID>",
    "organizationId": "<ORG_ID>"
  }
}'

{
	"workspaceId": "<WORKSPACE_ID>"
}

Request Parameters:

Parameter	Description	Type	Required
`contextUrl.url`	Context URL ( Repository, Issues, Pull Request URL)	string	true
`contextUrl.workspaceClass`	Workspace class (`g1-standard` or `g1-large`. Additionally, `g1-xlarge` or `g1-xxlarge` for Enterprise)	string	true
`contextUrl.editor.name`	IDE to be used for the workspace (`code`, `code-desktop`, `intellij`, `goland`, `phpstorm`, `pycharm`, `rubymine`, `webstorm`, `rider`, `clion`, `rustrover`)	string	false
`contextUrl.editor.version`	Version of the editor you’d like to use (default: `stable`, option: `latest`)	string	false
`metadata.ownerId`	User ID of the owner	string	true
`metadata.organizationId`	Organization ID	string	true

Response Parameters:

Parameter	Description	Type
`workspace.id`	The ID of the workspace	string
`workspace.metadata`	The metadata of the workspace	WorkspaceMetadata
`workspace.metadata.ownerId`	The ID of the user that owns the workspace	string
`workspace.metadata.organizationId`	The ID of the organization that the workspace belongs to	string
`workspace.metadata.configurationId`	The ID of the project or configuration that the workspace belongs to	string
`workspace.metadata.name`	The name of the workspace	string
`workspace.metadata.originalContextUrl`	The original context URL of the workspace	string
`workspace.spec`	The specifications of the workspace	WorkspaceSpec
`workspace.spec.initializer`	Initializer specifications for the workspace	InitializerSpec
`workspace.spec.initializer.specs`	Array of specifications for the initializer	[InitializerSpecs] (array)
`workspace.spec.initializer.specs[0].git`	Git configuration for the initializer	GitSpec
`workspace.spec.type`	The type of the workspace	string
`workspace.spec.ports`	Array of port configurations for the workspace	[PortsSpec] (array)
`workspace.spec.timeout`	Timeout configuration for the workspace	TimeoutSpec
`workspace.spec.admission`	Admission level for the workspace	string
`workspace.spec.class`	Resource class allocated to the workspace	string
`workspace.spec.editor`	Editor configuration for the workspace	EditorSpec
`workspace.status`	The status of the workspace	WorkspaceStatus
`workspace.status.phase`	Current phase of the workspace	PhaseSpec
`workspace.status.gitStatus`	Git status information for the workspace	GitStatusSpec
`workspace.status.instanceId`	The instance ID of the workspace	string

List all workspaces

Lists all the workspaces belongs to the authenticated user in the required organization.

curl -X POST \
  'https://api.gitpod.io/gitpod.v1.WorkspaceService/ListWorkspaces' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>"
}'

{
	"pagination": {
		"total": 2
	},
	"workspaces": [
		{
			"id": "<WORKSPACE_ID>",
			"metadata": {
				"ownerId": "<USER_ID>",
				"organizationId": "<ORG_ID>",
				"configurationId": "<PROJECT_OR_CONFIGURATION_ID>",
				"name": "<WORKSPACE_NAME>",
				"originalContextUrl": "<CONTEXT_URL>"
			},
			"spec": {
				"initializer": {
					"specs": [
						{
							"git": {
								"remoteUri": "<REMOTE_URI>",
								"targetMode": "CLONE_TARGET_MODE_REMOTE_COMMIT",
								"cloneTarget": "<CLONE_TARGET_COMMIT_ID>",
								"checkoutLocation": "<CHECKOUT_DIR_NAME_DEFAULTS_TO_REPO_NAME>",
								"config": {}
							}
						}
					]
				},
				"type": "WORKSPACE_TYPE_REGULAR",
				"ports": [
					{
						"port": "<PORT_NUMBER>",
						"admission": "ADMISSION_LEVEL_OWNER_ONLY",
						"url": "<PORT_URL>",
						"protocol": "PROTOCOL_HTTP"
					}
				],
				"git": {},
				"timeout": {
					"disconnected": "<TIMEOUT_TIME>"
				},
				"admission": "ADMISSION_LEVEL_OWNER_ONLY",
				"class": "<WORKSPACE_CLASS>",
				"editor": {
					"name": "<EDITOR_NAME>",
					"version": "<EDITOR_VERSION_LATEST_OR_STABLE>"
				}
			},
			"status": {
				"statusVersion": "<STATUS_VERSION>",
				"phase": {
					"name": "PHASE_STOPPED",
					"lastTransitionTime": "2024-02-03T19:34:24.939Z"
				},
				"workspaceUrl": "<WORKSPACE_URL>",
				"conditions": {},
				"gitStatus": {
					"cloneUrl": "<CLONE_URL>",
					"branch": "<BRANCH_NAME>",
					"latestCommit": "<LAST_COMMIT>"
				},
				"instanceId": "<INSTANCE_ID>"
			}
		},
		{
			"id": "<WORKSPACE_ID>",
			"metadata": {
				"ownerId": "<USER_ID>",
				"organizationId": "<ORG_ID>",
				"configurationId": "<PROJECT_OR_CONFIGURATION_ID>",
				"name": "<WORKSPACE_NAME>",
				"originalContextUrl": "<CONTEXT_URL>"
			},
			"spec": {
				"initializer": {
					"specs": [
						{
							"git": {
								"remoteUri": "<REMOTE_URI>",
								"targetMode": "CLONE_TARGET_MODE_REMOTE_COMMIT",
								"cloneTarget": "<CLONE_TARGET_COMMIT_ID>",
								"checkoutLocation": "<CHECKOUT_DIR_NAME_DEFAULTS_TO_REPO_NAME>",
								"config": {}
							}
						}
					]
				},
				"type": "WORKSPACE_TYPE_REGULAR",
				"ports": [
					{
						"port": "<PORT_NUMBER>",
						"admission": "ADMISSION_LEVEL_OWNER_ONLY",
						"url": "<PORT_URL>",
						"protocol": "PROTOCOL_HTTP"
					}
				],
				"git": {},
				"timeout": {
					"disconnected": "<TIMEOUT_TIME>"
				},
				"admission": "ADMISSION_LEVEL_OWNER_ONLY",
				"class": "<WORKSPACE_CLASS>",
				"editor": {
					"name": "<EDITOR_NAME>",
					"version": "<EDITOR_VERSION_LATEST_OR_STABLE>"
				}
			},
			"status": {
				"statusVersion": "<STATUS_VERSION>",
				"phase": {
					"name": "PHASE_STOPPED",
					"lastTransitionTime": "2024-02-03T10:46:55.354Z"
				},
				"workspaceUrl": "<WORKSPACE_URL>",
				"conditions": {},
				"gitStatus": {
					"cloneUrl": "<CLONE_URL>",
					"branch": "<BRANCH_NAME>",
					"latestCommit": "<LAST_COMMIT>"
				},
				"instanceId": "<INSTANCE_ID>"
			}
		}
	]
}

Request Parameters:

Parameter	Description	Type	Required
`organizationId`	The ID of the organization that the workspace belongs to.	string	true
`pinned`	Whether to return only pinned workspaces.	boolean	false
`searchTerm`	A search term to filter the workspaces by.	string	false
`pagination.page`	It specifies the page number of the results we expect (default: 1)	Int32	false
`pagination.pageSize`	It limits the maximum number of results we expect (default: 25, maximum: 100)	Int32	false

Response Parameters:

Parameter	Description	Type
`pagination.total`	Total number of organizations	Int32
`pagination.nextToken`	Next page token for pagination, Empty if there are no more results	string
`workspaces`	List of workspaces	[]Workspace (array)
`workspaces[0].id`	The ID of the workspace	string
`workspaces[0].metadata`	The metadata of the workspace	WorkspaceMetadata
`workspaces[0].metadata.ownerId`	The ID of the user that owns the workspace	string
`workspaces[0].metadata.organizationId`	The ID of the organization that the workspace belongs to	string
`workspaces[0].metadata.configurationId`	The ID of the project or configuration that the workspace belongs to	string
`workspaces[0].metadata.name`	The name of the workspace	string
`workspaces[0].metadata.originalContextUrl`	The original context URL of the workspace	string
`workspaces[0].spec`	The specifications of the workspace	WorkspaceSpec
`workspaces[0].spec.initializer`	Initializer specifications for the workspace	InitializerSpec
`workspaces[0].spec.initializer.specs`	Array of specifications for the initializer	[InitializerSpecs] (array)
`workspaces[0].spec.initializer.specs[0].git`	Git configuration for the initializer	GitSpec
`workspaces[0].spec.type`	The type of the workspace	string
`workspaces[0].spec.ports`	Array of port configurations for the workspace	[PortsSpec] (array)
`workspaces[0].spec.timeout`	Timeout configuration for the workspace	TimeoutSpec
`workspaces[0].spec.admission`	Admission level for the workspace	string
`workspaces[0].spec.class`	Resource class allocated to the workspace	string
`workspaces[0].spec.editor`	Editor configuration for the workspace	EditorSpec
`workspaces[0].status`	The status of the workspace	WorkspaceStatus
`workspaces[0].status.phase`	Current phase of the workspace	PhaseSpec
`workspaces[0].status.gitStatus`	Git status information for the workspace	GitStatusSpec
`workspaces[0].status.instanceId`	The instance ID of the workspace	string

Get a workspace

Returns details about a specific workspace.

curl -X POST \
  'https://api.gitpod.io/gitpod.v1.WorkspaceService/GetWorkspace' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "workspaceId": "<WORKSPACE_ID>"
}'

{
	"workspace": {
		"id": "<WORKSPACE_ID>",
		"metadata": {
			"ownerId": "<USER_ID>",
			"organizationId": "<ORG_ID>",
			"configurationId": "<PROJECT_OR_CONFIGURATION_ID>",
			"name": "<WORKSPACE_NAME>",
			"originalContextUrl": "<CONTEXT_URL>"
		},
		"spec": {
			"initializer": {
				"specs": [
					{
						"git": {
							"remoteUri": "<REMOTE_URI>",
							"targetMode": "CLONE_TARGET_MODE_REMOTE_COMMIT",
							"cloneTarget": "<CLONE_TARGET_COMMIT_ID>",
							"checkoutLocation": "<CHECKOUT_DIR_NAME_DEFAULTS_TO_REPO_NAME>",
							"config": {}
						}
					}
				]
			},
			"type": "WORKSPACE_TYPE_REGULAR",
			"ports": [
				{
					"port": "<PORT_NUMBER>",
					"admission": "ADMISSION_LEVEL_OWNER_ONLY",
					"url": "<PORT_URL>",
					"protocol": "PROTOCOL_HTTP"
				}
			],
			"git": {},
			"timeout": {
				"disconnected": "<TIMEOUT_TIME>"
			},
			"admission": "ADMISSION_LEVEL_OWNER_ONLY",
			"class": "<WORKSPACE_CLASS>",
			"editor": {
				"name": "<EDITOR_NAME>",
				"version": "<EDITOR_VERSION_LATEST_OR_STABLE>"
			}
		},
		"status": {
			"statusVersion": "<STATUS_VERSION>",
			"phase": {
				"name": "PHASE_STOPPED",
				"lastTransitionTime": "2024-02-03T19:34:24.939Z"
			},
			"workspaceUrl": "<WORKSPACE_URL>",
			"conditions": {},
			"gitStatus": {
				"cloneUrl": "<CLONE_URL>",
				"branch": "<BRANCH_NAME>",
				"latestCommit": "<LAST_COMMIT>"
			},
			"instanceId": "<INSTANCE_ID>"
		}
	}
}

Request Parameters:

Parameter	Description	Type	Required
`workspaceId`	Workspace ID	string	true

Response Parameters:

Parameter	Description	Type
`workspace.id`	The ID of the workspace	string
`workspace.metadata`	The metadata of the workspace	WorkspaceMetadata
`workspace.metadata.ownerId`	The ID of the user that owns the workspace	string
`workspace.metadata.organizationId`	The ID of the organization that the workspace belongs to	string
`workspace.metadata.configurationId`	The ID of the project or configuration that the workspace belongs to	string
`workspace.metadata.name`	The name of the workspace	string
`workspace.metadata.originalContextUrl`	The original context URL of the workspace	string
`workspace.spec`	The specifications of the workspace	WorkspaceSpec
`workspace.spec.initializer`	Initializer specifications for the workspace	InitializerSpec
`workspace.spec.initializer.specs`	Array of specifications for the initializer	[InitializerSpecs] (array)
`workspace.spec.initializer.specs[0].git`	Git configuration for the initializer	GitSpec
`workspace.spec.type`	The type of the workspace	string
`workspace.spec.ports`	Array of port configurations for the workspace	[PortsSpec] (array)
`workspace.spec.timeout`	Timeout configuration for the workspace	TimeoutSpec
`workspace.spec.admission`	Admission level for the workspace	string
`workspace.spec.class`	Resource class allocated to the workspace	string
`workspace.spec.editor`	Editor configuration for the workspace	EditorSpec
`workspace.status`	The status of the workspace	WorkspaceStatus
`workspace.status.phase`	Current phase of the workspace	PhaseSpec
`workspace.status.gitStatus`	Git status information for the workspace	GitStatusSpec
`workspace.status.instanceId`	The instance ID of the workspace	string

Start a workspace

Starts an older workspace (instance).

curl -X POST \
  'https://api.gitpod.io/gitpod.v1.WorkspaceService/StartWorkspace' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "workspaceId": "<WORKSPACE_ID>"
}'

{
	"workspace": {
		"id": "<WORKSPACE_ID>",
		"metadata": {
			"ownerId": "<USER_ID>",
			"organizationId": "<ORG_ID>",
			"configurationId": "<PROJECT_OR_CONFIGURATION_ID>",
			"name": "<WORKSPACE_NAME>",
			"originalContextUrl": "<CONTEXT_URL>"
		},
		"spec": {
			"initializer": {
				"specs": [
					{
						"git": {
							"remoteUri": "<REMOTE_URI>",
							"targetMode": "CLONE_TARGET_MODE_REMOTE_COMMIT",
							"cloneTarget": "<CLONE_TARGET_COMMIT_ID>",
							"checkoutLocation": "<CHECKOUT_DIR_NAME_DEFAULTS_TO_REPO_NAME>",
							"config": {}
						}
					}
				]
			},
			"type": "WORKSPACE_TYPE_REGULAR",
			"ports": [
				{
					"port": "<PORT_NUMBER>",
					"admission": "ADMISSION_LEVEL_OWNER_ONLY",
					"url": "<PORT_URL>",
					"protocol": "PROTOCOL_HTTP"
				}
			],
			"git": {},
			"timeout": {
				"disconnected": "<TIMEOUT_TIME>"
			},
			"admission": "ADMISSION_LEVEL_OWNER_ONLY",
			"class": "<WORKSPACE_CLASS>",
			"editor": {
				"name": "<EDITOR_NAME>",
				"version": "<EDITOR_VERSION_LATEST_OR_STABLE>"
			}
		},
		"status": {
			"statusVersion": "<STATUS_VERSION>",
			"phase": {
				"name": "PHASE_STOPPED",
				"lastTransitionTime": "2024-02-03T19:34:24.939Z"
			},
			"workspaceUrl": "<WORKSPACE_URL>",
			"conditions": {},
			"gitStatus": {
				"cloneUrl": "<CLONE_URL>",
				"branch": "<BRANCH_NAME>",
				"latestCommit": "<LAST_COMMIT>"
			},
			"instanceId": "<INSTANCE_ID>"
		}
	}
}

Request Parameters:

Parameter	Description	Type	Required
`workspaceId`	ID of the workspace to start	string	true

Response Parameters: Returns the same response as GetWorkspace.

Parameter	Description	Type
`workspace.id`	The ID of the workspace	string
`workspace.metadata`	The metadata of the workspace	WorkspaceMetadata
`workspace.metadata.ownerId`	The ID of the user that owns the workspace	string
`workspace.metadata.organizationId`	The ID of the organization that the workspace belongs to	string
`workspace.metadata.configurationId`	The ID of the project or configuration that the workspace belongs to	string
`workspace.metadata.name`	The name of the workspace	string
`workspace.metadata.originalContextUrl`	The original context URL of the workspace	string
`workspace.spec`	The specifications of the workspace	WorkspaceSpec
`workspace.spec.initializer`	Initializer specifications for the workspace	InitializerSpec
`workspace.spec.initializer.specs`	Array of specifications for the initializer	[InitializerSpecs] (array)
`workspace.spec.initializer.specs[0].git`	Git configuration for the initializer	GitSpec
`workspace.spec.type`	The type of the workspace	string
`workspace.spec.ports`	Array of port configurations for the workspace	[PortsSpec] (array)
`workspace.spec.timeout`	Timeout configuration for the workspace	TimeoutSpec
`workspace.spec.admission`	Admission level for the workspace	string
`workspace.spec.class`	Resource class allocated to the workspace	string
`workspace.spec.editor`	Editor configuration for the workspace	EditorSpec
`workspace.status`	The status of the workspace	WorkspaceStatus
`workspace.status.phase`	Current phase of the workspace	PhaseSpec
`workspace.status.gitStatus`	Git status information for the workspace	GitStatusSpec
`workspace.status.instanceId`	The instance ID of the workspace	string

Stop a workspace

Stops a running workspace (instance).

curl -X POST \
  'https://api.gitpod.io/gitpod.v1.WorkspaceService/StopWorkspace' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "workspaceId": "<WORKSPACE_ID>"
}'

{}

Request Parameters:

Parameter	Description	Type	Required
`workspaceId`	Workspace ID that needs to be stopped	string	true

Response: It stops the requested workspace.

Delete a workspace

It deletes the workspace & also stops the workspace if it is running.

curl -X POST \
  'https://api.gitpod.io/gitpod.v1.WorkspaceService/DeleteWorkspace' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "workspaceId": "<WORKSPACE_ID>"
}'

{}

Request Parameters:

Parameter	Description	Type	Required
`workspaceId`	Workspace ID that needs to be deleted	string	true

Response: It deletes the requested workspace.

List workspace sessions

If you are an organization owner, you can list all workspace sessions in the organization. A workspace session is tracked whenever a workspace is started until it is stopped. The responses are paged, and you can specify the page size and page number. The responses are ordered by descending creationTime. You can filter the responses by creationTime range using the from and to arguments. If to is not specified, it defaults to now. If from is not specified, it defaults to 7 days before to.

curl -X POST \
    "https://api.gitpod.io/gitpod.v1.WorkspaceService/ListWorkspaceSessions" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'content-type: application/json' \
    --data-raw '{
        "organizationId": "<ORGANIZATION_ID>",
        "pagination": {
            "pageSize": 20,
            "page": 0
        },
        "from": "2024-01-13T07:06:45.659Z",
        "to": "2024-07-13T07:06:48.659Z"
    }'
}'

{
	"workspaceSessions": [
		{
			"id": "a978a95d-b83d-4e43-97db-a280c473aecd",
			"workspace": {
				"id": "gitpodio-new-hw63y2sk712",
				"metadata": {
					"ownerId": "5be90129-3696-4aa5-86a4-7962fd762eb0",
					"organizationId": "8818c76e-9c91-45e9-94fe-2d312cad0f5a",
					"configurationId": "6894822d-c5dc-4c34-a33f-feabe206fce0",
					"name": "gitpod-io/new - main",
					"originalContextUrl": "https://github.com/gitpod-io/new"
				},
				"spec": {
					"initializer": {
						"specs": [
							{
								"git": {
									"remoteUri": "https://github.com/gitpod-io/new.git",
									"targetMode": "CLONE_TARGET_MODE_REMOTE_COMMIT",
									"cloneTarget": "f77244b5c69e4dad4534f35705c0a754b7421e96",
									"checkoutLocation": "new",
									"config": {}
								}
							}
						]
					},
					"type": "WORKSPACE_TYPE_PREBUILD",
					"ports": [
						{
							"port": "8888",
							"admission": "ADMISSION_LEVEL_OWNER_ONLY",
							"url": "https://8888-gitpodio-new-hw63y2sk712.ws.astley-enterprises.gitpod.cloud",
							"protocol": "PROTOCOL_HTTP"
						},
						{
							"port": "65220",
							"admission": "ADMISSION_LEVEL_OWNER_ONLY",
							"url": "https://65220-gitpodio-new-hw63y2sk712.ws.astley-enterprises.gitpod.cloud",
							"protocol": "PROTOCOL_HTTP"
						},
						{
							"port": "8000",
							"admission": "ADMISSION_LEVEL_OWNER_ONLY",
							"url": "https://8000-gitpodio-new-hw63y2sk712.ws.astley-enterprises.gitpod.cloud",
							"protocol": "PROTOCOL_HTTP"
						},
						{
							"port": "5173",
							"admission": "ADMISSION_LEVEL_OWNER_ONLY",
							"url": "https://5173-gitpodio-new-hw63y2sk712.ws.astley-enterprises.gitpod.cloud",
							"protocol": "PROTOCOL_HTTP"
						}
					],
					"git": {},
					"timeout": {
						"inactivity": "1800s",
						"disconnected": "1800s"
					},
					"admission": "ADMISSION_LEVEL_OWNER_ONLY",
					"class": "g1-xlarge"
				},
				"status": {
					"statusVersion": "1739353580",
					"phase": {
						"name": "PHASE_RUNNING",
						"lastTransitionTime": "2025-02-12T09:46:20.133Z"
					},
					"workspaceUrl": "https://gitpodio-new-hw63y2sk712.ws.astley-enterprises.gitpod.cloud",
					"conditions": {},
					"prebuildResult": {},
					"gitStatus": {
						"cloneUrl": "https://github.com/gitpod-io/new.git",
						"branch": "main",
						"latestCommit": "f77244b5c69e4dad4534f35705c0a754b7421e96"
					},
					"instanceId": "a978a95d-b83d-4e43-97db-a280c473aecd"
				}
			},
			"creationTime": "2025-02-12T09:42:39.122Z",
			"deployedTime": "2025-02-12T09:42:39.602Z",
			"startedTime": "2025-02-12T09:46:20.133Z",
			"metrics": {
				"workspaceImageSize": "3101890673",
				"totalImageSize": "3399041532",
				"initializerMetrics": {
					"git": {
						"duration": "1250000000",
						"size": 25600000
					},
					"prebuild": {
						"duration": "3500000000",
						"size": 156800000
					},
					"snapshot": {
						"duration": "2100000000",
						"size": 85300000
					},
					"backup": {
						"duration": "2800000000",
						"size": 98400000
					},
					"fileDownload": {
						"duration": "950000000",
						"size": 12500000
					}
				}
			},
			"owner": {
				"id": "5be90129-3696-4aa5-86a4-7962fd762eb0",
				"name": "Kum Quat",
				"avatarUrl": "https://upload.wikimedia.org/wikipedia/commons/thumb/7/72/Kumquat_from_Spain.jpg/640px-Kumquat_from_Spain.jpg"
			},
			"context": {
				"ref": "main",
				"refType": "REF_TYPE_BRANCH",
				"revision": "f77244b5c69e4dad4534f35705c0a754b7421e96",
				"repository": {
					"cloneUrl": "https://github.com/gitpod-io/new.git",
					"host": "github.com",
					"owner": "gitpod-io",
					"name": "new"
				}
			}
		},
		{
			"id": "3c0b195b-57a1-4432-b646-2a08b4c0e975",
			"workspace": {
				"id": "gitpodio-new-ogctyxjk8fw",
				"metadata": {
					"ownerId": "5be90129-3696-4aa5-86a4-7962fd762eb0",
					"organizationId": "8818c76e-9c91-45e9-94fe-2d312cad0f5a",
					"configurationId": "6894822d-c5dc-4c34-a33f-feabe206fce0",
					"name": "gitpod-io/new - main",
					"originalContextUrl": "https://github.com/gitpod-io/new"
				},
				"spec": {
					"initializer": {
						"specs": [
							{
								"prebuild": {
									"prebuildId": "16d98207-f2a5-48c7-9a0c-b60bebb7cec3"
								}
							}
						]
					},
					"type": "WORKSPACE_TYPE_REGULAR",
					"ports": [
						{
							"port": "8888",
							"admission": "ADMISSION_LEVEL_OWNER_ONLY",
							"url": "https://8888-gitpodio-new-ogctyxjk8fw.ws.astley-enterprises.gitpod.cloud",
							"protocol": "PROTOCOL_HTTP"
						},
						{
							"port": "65220",
							"admission": "ADMISSION_LEVEL_OWNER_ONLY",
							"url": "https://65220-gitpodio-new-ogctyxjk8fw.ws.astley-enterprises.gitpod.cloud",
							"protocol": "PROTOCOL_HTTP"
						},
						{
							"port": "8000",
							"admission": "ADMISSION_LEVEL_OWNER_ONLY",
							"url": "https://8000-gitpodio-new-ogctyxjk8fw.ws.astley-enterprises.gitpod.cloud",
							"protocol": "PROTOCOL_HTTP"
						},
						{
							"port": "5173",
							"admission": "ADMISSION_LEVEL_OWNER_ONLY",
							"url": "https://5173-gitpodio-new-ogctyxjk8fw.ws.astley-enterprises.gitpod.cloud",
							"protocol": "PROTOCOL_HTTP"
						}
					],
					"git": {},
					"timeout": {
						"inactivity": "3600s",
						"disconnected": "3600s"
					},
					"admission": "ADMISSION_LEVEL_OWNER_ONLY",
					"class": "g1-large",
					"editor": {
						"name": "code",
						"version": "stable"
					}
				},
				"status": {
					"statusVersion": "1739354562",
					"phase": {
						"name": "PHASE_STOPPED",
						"lastTransitionTime": "2025-02-12T10:02:42.228Z"
					},
					"workspaceUrl": "https://gitpodio-new-ogctyxjk8fw.ws.astley-enterprises.gitpod.cloud",
					"conditions": {
						"timeout": "workspace timed out after after being closed (00h05m) took longer than 00h05m"
					},
					"gitStatus": {
						"cloneUrl": "https://github.com/gitpod-io/new.git",
						"branch": "main",
						"latestCommit": "f77244b5c69e4dad4534f35705c0a754b7421e96"
					},
					"instanceId": "3c0b195b-57a1-4432-b646-2a08b4c0e975"
				}
			},
			"creationTime": "2025-02-12T09:42:32.665Z",
			"deployedTime": "2025-02-12T09:42:33.244Z",
			"startedTime": "2025-02-12T09:42:42.231Z",
			"stoppingTime": "2025-02-12T10:02:18.238Z",
			"stoppedTime": "2025-02-12T10:02:42.228Z",
			"metrics": {
				"workspaceImageSize": "3399041532",
				"totalImageSize": "3399041532",
				"initializerMetrics": {
					"prebuild": {
						"duration": "2850000000",
						"size": 142500000
					},
					"fileDownload": {
						"duration": "750000000",
						"size": 8750000
					}
				}
			},
			"owner": {
				"id": "5be90129-3696-4aa5-86a4-7962fd762eb0",
				"name": "Kum Quat",
				"avatarUrl": "https://upload.wikimedia.org/wikipedia/commons/thumb/7/72/Kumquat_from_Spain.jpg/640px-Kumquat_from_Spain.jpg"
			},
			"context": {
				"ref": "main",
				"refType": "REF_TYPE_BRANCH",
				"revision": "f77244b5c69e4dad4534f35705c0a754b7421e96",
				"repository": {
					"cloneUrl": "https://github.com/gitpod-io/new.git",
					"host": "github.com",
					"owner": "gitpod-io",
					"name": "new"
				}
			}
		}
	]
}

Request Parameters:

Parameter	Description	Type	Required
`organizationId`	Organization ID	string	true
`pagination`	Pagination parameters	object	false
`from`	Start of the creationTime range	string	false
`to`	End of the creationTime range	string	false

Response: Returns a list of workspace sessions.

Resource: Organizations

You can also view the protocol buffer definitions here for more details.

Create an organization

Creates an organization.

curl -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/CreateOrganization' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "name": "<ORG_NAME>"
}'

{
	"organization": {
		"id": "<ORG_ID>",
		"name": "<ORG_NAME>",
		"creationTime": "2023-03-13T11:42:16.700Z",
		"slug": "<ORG_SLUG>"
	}
}

Request Parameters:

Parameter	Description	Type	Required
`name`	Organization name	string	true

Response Parameters:

Parameter	Description	Type
`id`	UUID of Organization	string
`name`	Name of Organization	string
`creationTime`	Creation time of Organization	string (timestamp in ISO 8601 format)

List all organizations

Lists all the organizations belonging to the authenticated user.

curl -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/ListOrganizations' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{}'

{
	"organizations": [
		{
			"id": "<ORG_ID>",
			"name": "<ORG_NAME>",
			"creationTime": "2023-01-04T16:02:14.327Z",
			"slug": "<ORG_SLUG>"
		},
		{
			"id": "<ORG_ID>",
			"name": "<ORG_NAME>",
			"creationTime": "2023-03-13T11:42:16.700Z",
			"slug": "<ORG_SLUG>"
		}
	],
	"pagination": {
		"total": 2
	}
}

Request Parameters:

Parameter	Description	Type	Required
`pagination.page`	It specifies the page number of the results we expect (default: 1)	Int32	false
`pagination.pageSize`	It limits the maximum number of results we expect (default: 25, maximum: 100)	Int32	false

Response Parameters:

Parameter	Description	Type
`organizations`	List of organizations	array
`organizations[0].id`	UUID of the organization	string
`organizations[0].name`	Name of the organization	string
`organizations[0].creationTime`	Creation time of the organization	string (timestamp in ISO 8601 format)
`organizations[0].slug`	Slug of the organization	string
`pagination.total`	Total number of organizations	Int32
`pagination.nextToken`	Next page token for pagination, Empty if there are no more results	string

Get an organization

Returns the details about a single organization.

curl -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/GetOrganization' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>"
}'

{
	"organization": {
		"id": "<ORG_ID>",
		"name": "<ORG_NAME>",
		"creationTime": "2023-03-13T11:42:16.700Z",
		"slug": "<ORG_SLUG>"
	}
}

Request Parameters:

Parameter	Description	Type	Required
`organizationId`	Organization ID	string	true

Response Parameters:

Parameter	Description	Type
`id`	UUID of Organization	string
`name`	Name of Organization	string
`creationTime`	Creation time of Organization	string (timestamp in ISO 8601 format)

Delete an organization

Deletes an organization.

curl  -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/DeleteOrganization' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>"
}'

{}

Request Parameters:

Parameter	Description	Type	Required
`organizationId`	Organization ID that needs to be deleted	string	true

Response: It deletes the requested organization.

Get an organization’s settings

Returns the settings of an organization.

curl -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/GetOrganizationSettings' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>"
}'

{
	"settings": {
		"defaultWorkspaceImage": "docker.io/gitpod/workspace-full",
		"allowedWorkspaceClasses": [
			"g1-small",
			"g1-standard",
			"g1-large",
			"g1-xlarge",
			"g1-xxlarge",
			"g1-3xlarge"
		],
		"restrictedEditorNames": ["rider", "clion"],
		"defaultRole": "member",
		"timeoutSettings": {
			"inactivity": "3600s",
			"denyUserTimeouts": false
		},
		"roleRestrictions": [
			{
				"role": "ORGANIZATION_ROLE_COLLABORATOR",
				"permissions": ["ORGANIZATION_PERMISSION_START_ARBITRARY_REPOS"]
			}
		],
		"maxParallelRunningWorkspaces": 6,
		"onboardingSettings": {
			"internalLink": "https://en.wikipedia.org/wiki/Cat_food",
			"recommendedRepositories": [
				"13dfbcce-78c4-47ac-a6be-5b4edf20ecc8",
				"6894822d-c5dc-4c34-a33f-feabe206fce0",
				"598f3acb-d8e0-4901-b1dc-7b0536a3f87d"
			]
		},
		"annotateGitCommits": true
	}
}

Request Parameters:

Parameter	Description	Type	Required
`organizationId`	Organization ID	string	true

Response Parameters:

Parameter	Description	Type
`settings`	Settings of an organization	Object
`settings.workspaceSharingDisabled`	Whether workspace sharing is disabled	Boolean
`settings.defaultWorkspaceImage`	Default workspace image	String
`settings.allowedWorkspaceClasses`	IDs of workspace classes allowed to be used	Array
`settings.restrictedEditorNames`	List of restricted editor names	Array
`settings.pinnedEditorVersions`	Pinned versions for corresponding editors	Map
`settings.defaultRole`	Default role for new members	String
`settings.timeoutSettings`	Timeout settings (see related section in Organization Policies)	Object
`settings.timeoutSettings.inactivity`	Inactivity timeout	String
`settings.timeoutSettings.denyUserTimeouts`	Whether to deny user timeouts	Boolean
`settings.roleRestrictions`	Role restrictions	Array
`settings.maxParallelRunningWorkspaces`	Maximum number of parallel running workspaces (see related section in Organization Policies)	Int32
`settings.onboardingSettings`	Onboarding settings (see the Organization Onboarding documentation)	Object
`settings.onboardingSettings.internalLink`	Internal link for onboarding	String
`settings.onboardingSettings.welcomeMessage`	Welcome message for onboarding	Object
`settings.onboardingSettings.welcomeMessage.enabled`	Whether to show the welcome message to new organization members.	Boolean
`settings.onboardingSettings.welcomeMessage.message`	Welcome message for onboarding	String
`settings.onboardingSettings.welcomeMessage.featuredMemberId`	ID of the member whose avatar will be displayed in the welcome message	String
`settings.onboardingSettings.welcomeMessage.featuredMemberResolvedAvatarUrl`	Avatar URL of the member whose avatar will be displayed in the welcome message	String
`settings.onboardingSettings.recommendedRepositories`	Configuration IDs of recommended repositories for onboarding	Array
`settings.annotateGitCommits`	Whether to annotate Git commits (see Git commit annotation)	Boolean

Update an organization’s settings

Performs a partial update of an organization’s settings.

curl -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/UpdateOrganizationSettings' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>",
  "settings": {
    "defaultWorkspaceImage": "docker.io/gitpod/workspace-full"
  }
}'

{
	"settings": {
		"defaultWorkspaceImage": "docker.io/gitpod/workspace-full",
		"allowedWorkspaceClasses": [
			"g1-small",
			"g1-standard",
			"g1-large",
			"g1-xlarge",
			"g1-xxlarge",
			"g1-3xlarge"
		],
		"restrictedEditorNames": ["rider", "clion"],
		"defaultRole": "member",
		"timeoutSettings": {
			"inactivity": "3600s",
			"denyUserTimeouts": false
		},
		"roleRestrictions": [
			{
				"role": "ORGANIZATION_ROLE_COLLABORATOR",
				"permissions": ["ORGANIZATION_PERMISSION_START_ARBITRARY_REPOS"]
			}
		],
		"maxParallelRunningWorkspaces": 6,
		"onboardingSettings": {
			"internalLink": "https://en.wikipedia.org/wiki/Cat_food",
			"recommendedRepositories": [
				"13dfbcce-78c4-47ac-a6be-5b4edf20ecc8",
				"6894822d-c5dc-4c34-a33f-feabe206fce0",
				"598f3acb-d8e0-4901-b1dc-7b0536a3f87d"
			]
		},
		"annotateGitCommits": true
	}
}

For the response parameters under settings, see the Get an organization’s settings section. Request Parameters:

Parameter	Description	Type	Required
`organizationId`	Organization ID	String	Yes
`workspaceSharingDisabled`	Whether workspace sharing is disabled	Boolean
`settings.defaultWorkspaceImage`	Default workspace image	String
`allowedWorkspaceClasses`	IDs of workspace classes allowed to be used	Array
`updateAllowedWorkspaceClasses`	Whether to update allowed workspace classes	Boolean
`restrictedEditorNames`	List of restricted editor names	Array
`updateRestrictedEditorNames`	Whether to update restricted editor names	Boolean
`pinnedEditorVersions`	Pinned versions for corresponding editors	Map
`updatePinnedEditorVersions`	Whether to update pinned editor versions	Boolean
`defaultRole`	Default role for new members	String
`timeoutSettings`	Timeout settings (see related section in Organization Policies)	Object
`timeoutSettings.inactivity`	Inactivity timeout	String
`timeoutSettings.denyUserTimeouts`	Whether to deny user timeouts	Boolean
`roleRestrictions`	Role restrictions	Array
`updateRoleRestrictions`	Whether to update role restrictions	Boolean
`maxParallelRunningWorkspaces`	Maximum number of parallel running workspaces (see related section in Organization Policies)	Int32
`onboardingSettings`	Onboarding settings (see the Organization Onboarding documentation)	Object
`onboardingSettings.internalLink`	Internal link for onboarding	String
`onboardingSettings.welcomeMessage`	Welcome message for onboarding	Object
`onboardingSettings.welcomeMessage.enabled`	Whether to show the welcome message to new organization members.	Boolean
`onboardingSettings.welcomeMessage.message`	Welcome message for onboarding	String
`onboardingSettings.welcomeMessage.featuredMemberId`	ID of the member whose avatar will be displayed in the welcome message	String
`onboardingSettings.recommendedRepositories`	Configuration IDs of recommended repositories for onboarding	Array
`annotateGitCommits`	Whether to annotate Git commits (see Git commit annotation)	Boolean

Response Parameters:

Parameter	Description	Type
`settings`	Updated settings	Object

Join an organization

Joins an organization.

curl  -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/JoinOrganization' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "invitationId": "<ORG_INVITATION_ID>"
}'

{
	"organizationId": "<ORG_ID>"
}

Request Parameters:

Parameter	Description	Type	Required
`invitationId`	Organization Invitation ID	string	true

Response Parameters:

Parameter	Description	Type
`organizationId`	UUID of Team	string

Reset organization invitation

Resets/recreates the ID of an organization’s invitation.

curl  -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/ResetOrganizationInvitation' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>"
}'

{
	"invitationId": "<ORG_INVITATION_ID>"
}

Request Parameters:

Parameter	Description	Type	Required
`organizationId`	Organization ID	string	true

Response Parameters:

Parameter	Description	Type
`invitationId`	New invitation id of organization	string

Get list of all organization members

Returns the list of all organization members. And it returns the role of each member, role differs in three categories Owner, Member, Collaborator. Learn more about Member roles.

curl  -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/ListOrganizationMembers' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>"
}'

{
  "members": [
    {
      "userId": "<USER_ID>",
      "role": "<ORG_MEMBER_ROLE>",
      "memberSince": "2022-12-22T09:50:50.234Z",
      "avatarUrl": "<USER_AVATAR_URL>",
      "fullName": "<USER_FULL_NAME>",
      "email": "<USER_EMAIL_ID>"
    },
    {
      "userId": "<USER_ID>",
      "role": "<ORG_MEMBER_ROLE>",
      "memberSince": "2022-12-22T09:45:41.465Z",
      "avatarUrl": "<USER_AVATAR_URL>",
      "fullName": "<USER_FULL_NAME>",
      "email": "<USER_EMAIL_ID>"
    }
    {
      "userId": "<USER_ID>",
      "role": "<ORG_MEMBER_ROLE>",
      "memberSince": "2023-12-22T09:45:41.465Z",
      "avatarUrl": "<USER_AVATAR_URL>",
      "fullName": "<USER_FULL_NAME>",
      "email": "<USER_EMAIL_ID>"
    }
  ],
  "pagination": {
    "total": 3
  }
}

Request Parameters:

Parameter	Description	Type	Required
`organizationId`	Organization ID	string	true

Response Parameters:

Parameter	Description	Type
`members`	List of members in an organization	array
`members[0].userId`	User ID of the member	string
`members[0].role`	Role of the member (`ORGANIZATION_ROLE_OWNER`, `ORGANIZATION_ROLE_MEMBER`, `ORGANIZATION_ROLE_COLLABORATOR`)	string
`members[0].memberSince`	Time since member is part of organization	string (timestamp in ISO 8601 format)
`members[0].avatarUrl`	Avatar URL of member	string
`members[0].fullName`	Full name of member	string
`members[0].email`	Email ID of member	string
`pagination.total`	Total number of organizations	Int32
`pagination.nextToken`	Next page token for pagination, Empty if there are no more results	string

Update an organization member role

Updates an organization member role

curl -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/UpdateOrganizationMember' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>",
    "userId": "<USER_ID>",
    "role": "<ORG_MEMBER_ROLE>"
}'

{
	"member": {
		"userId": "<USER_ID>",
		"role": "<ORG_MEMBER_ROLE>",
		"memberSince": "2022-12-22T09:45:41.465Z",
		"avatarUrl": "<USER_AVATAR_URL>",
		"fullName": "<USER_FULL_NAME>",
		"email": "<USER_EMAIL_ID>"
	}
}

Request Parameters:

Parameter	Description	Type	Required
`organizationId`	Team name	string	true
`userId`	User ID of a team member being updated	string	true
`role`	Role of a team member: (`ORGANIZATION_ROLE_OWNER`, `ORGANIZATION_ROLE_MEMBER`, `ORGANIZATION_ROLE_COLLABORATOR`)	string	true

Response Parameters:

Parameter	Description	Type
`member.userId`	User ID of the member	string
`members.role`	New role of the member (`ORGANIZATION_ROLE_OWNER`, `ORGANIZATION_ROLE_MEMBER`, `ORGANIZATION_ROLE_COLLABORATOR`)	string
`member.memberSince`	Time since member is part of organization	string (timestamp in ISO 8601 format)
`member.avatarUrl`	Avatar URL of member	string
`member.fullName`	Full name of member	string
`member.email`	Email ID of member

Delete or Remove an organization member

Deletes/Removes an organization member.

curl -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/DeleteOrganizationMember' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>",
  "userId": "<USER_ID>"
}'

{}

Request Parameters:

Parameter	Description	Type	Required
`organizationId`	Organization ID	string	true
`userId`	User ID of organization member being removed	string	true

Response: Empty JSON object

Resource: Audit Logs

This is only available in Gitpod Enterprise.

List audit logs

Lists audit logs for the organization of the authenticated user. This API requires organization owner permissions.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.AuditLogService/ListAuditLogs" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
    "organizationId": "<ORGANIZATION_ID>",
    "pagination": {
        "pageSize": 200,
        "page": 0
    },
    "from": "2024-01-13T07:06:45.659Z",
    "to": "2024-07-13T07:06:48.659Z"
}'

{
	"pagination": {
		"total": 5
	},
	"auditLogs": [
		{
			"id": "43d1185c-c2d1-49f9-8da0-200ed0b05dd3",
			"timestamp": "2024-06-24T13:29:38.330Z",
			"action": "gitpod.v1.OrganizationService/getOrganizationSettings",
			"organizationId": "3d5e4ee2-7e5f-468f-b027-276a65518784",
			"actorId": "e2eb4315-1ce5-4c5b-b1a1-d6a891c08a56",
			"args": "[{\"organizationId\":\"3d5e4ee2-7e5f-468f-b027-276a65518784\"}]"
		},
		{
			"id": "782b4b8d-3776-421b-b3f5-13d3580cf785",
			"timestamp": "2024-06-24T13:29:38.289Z",
			"action": "gitpod.v1.OrganizationService/updateOrganizationSettings",
			"organizationId": "3d5e4ee2-7e5f-468f-b027-276a65518784",
			"actorId": "e2eb4315-1ce5-4c5b-b1a1-d6a891c08a56",
			"args": "[{\"defaultRole\":\"\",\"organizationId\":\"3d5e4ee2-7e5f-468f-b027-276a65518784\",\"pinnedEditorVersions\":{},\"defaultWorkspaceImage\":\"\",\"restrictedEditorNames\":[],\"allowedWorkspaceClasses\":[],\"workspaceSharingDisabled\":true,\"updatePinnedEditorVersions\":true,\"updateRestrictedEditorNames\":true}]"
		},
		{
			"id": "dc163d83-27a5-4c34-87e2-c7f478e1e762",
			"timestamp": "2024-06-24T13:29:36.485Z",
			"action": "getBillingModeForTeam",
			"organizationId": "3d5e4ee2-7e5f-468f-b027-276a65518784",
			"actorId": "e2eb4315-1ce5-4c5b-b1a1-d6a891c08a56",
			"args": "[\"3d5e4ee2-7e5f-468f-b027-276a65518784\"]"
		},
		{
			"id": "9a5cf877-23af-4c9d-ba89-ef1847f164fe",
			"timestamp": "2024-06-24T13:29:36.484Z",
			"action": "gitpod.v1.OrganizationService/listOrganizationMembers",
			"organizationId": "3d5e4ee2-7e5f-468f-b027-276a65518784",
			"actorId": "e2eb4315-1ce5-4c5b-b1a1-d6a891c08a56",
			"args": "[{\"pagination\":{\"page\":0,\"token\":\"\",\"pageSize\":1000},\"organizationId\":\"3d5e4ee2-7e5f-468f-b027-276a65518784\"}]"
		},
		{
			"id": "1ac75456-ae7d-4233-9914-32d124fa35c3",
			"timestamp": "2024-06-24T13:29:36.484Z",
			"action": "getTeamProjects",
			"organizationId": "3d5e4ee2-7e5f-468f-b027-276a65518784",
			"actorId": "e2eb4315-1ce5-4c5b-b1a1-d6a891c08a56",
			"args": "[\"3d5e4ee2-7e5f-468f-b027-276a65518784\"]"
		}
	]
}

Request Parameters:

Parameter	Description	Type	Required
`organization_id`	The ID of the organization	string	true
`from`	The starting time range for the request (timestamp)	string (timestamp in ISO 8601 format)	false
`to`	The ending time range for the request (timestamp)	string (timestamp in ISO 8601 format)	false
`actor_id`	The ID of the user performing the action	string	false
`action`	The action performed	string	false
`pagination`	Pagination options for the request	object	false

Response Parameters:

Parameter	Description	Type
`pagination`	Pagination details for the response	object
`audit_logs`	List of audit logs that matched the query	array
`audit_logs[0].id`	The unique identifier of the audit log	string
`audit_logs[0].timestamp`	The time when the audit log was created	string (timestamp in ISO 8601 format)
`audit_logs[0].action`	The action that was performed	string
`audit_logs[0].organization_id`	The ID of the organization	string
`audit_logs[0].actor_id`	The ID of the user that performed the action	string
`audit_logs[0].args`	A serialized JSON array of arguments passed	string

Resource: Configurations (aka Repository Settings)

Configurations are the API nomenclature used for interacting with Repositories. You can also view the protocol buffer definitions here for more details.

Create Configuration

Imports a repository into Gitpod.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.ConfigurationService/CreateConfiguration" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORGANIZATION_ID>",
  "cloneUrl": "<CLONE_URL>"
  }'

{
	"configuration": {
		"id": "198c5160-b8b3-4eef-bd2b-7e6fc44fcd2c",
		"organizationId": "8818c76e-9c91-45e9-94fe-2d312cad0f5a",
		"name": "linux",
		"cloneUrl": "https://github.com/torvalds/linux",
		"creationTime": "2025-02-12T14:29:21.469Z",
		"prebuildSettings": {
			"branchMatchingPattern": "**",
			"branchStrategy": "BRANCH_MATCHING_STRATEGY_ALL_BRANCHES",
			"prebuildInterval": 20,
			"triggerStrategy": "PREBUILD_TRIGGER_STRATEGY_ACTIVITY_BASED",
			"cloneSettings": {}
		},
		"workspaceSettings": {}
	}
}

Request Parameters:

Parameter	Description	Type	Required
`organizationId`	The ID of the organization	string	true
`cloneUrl`	The URL of the repository to import	string	true
`name`	The display name of the configuration	string	false

Response Parameters:

Parameter	Description	Type
`configuration`	The created configuration	object

Get Configuration

Retrieves a single configuration.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.ConfigurationService/GetConfiguration" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
  "configurationId": "<CONFIGURATION_ID>"
  }'

{
	"configuration": {
		"id": "160625ae-86b9-46a2-98d0-64c92aee7a06",
		"organizationId": "8818c76e-9c91-45e9-94fe-2d312cad0f5a",
		"name": "awesome-test",
		"cloneUrl": "https://github.com/microsoft/vscode.git",
		"creationTime": "2024-12-11T14:06:42.806Z",
		"prebuildSettings": {
			"enabled": true,
			"branchMatchingPattern": "**",
			"branchStrategy": "BRANCH_MATCHING_STRATEGY_ALL_BRANCHES",
			"workspaceClass": "g1-standard",
			"triggerStrategy": "PREBUILD_TRIGGER_STRATEGY_ACTIVITY_BASED",
			"cloneSettings": {}
		},
		"workspaceSettings": {
			"workspaceClass": "g1-standard",
			"restrictedWorkspaceClasses": [
				"g1-xxlarge",
				"g1-3xlarge",
				"g1-4xlarge"
			],
			"restrictedEditorNames": [
				"rider",
				"webstorm",
				"rubymine",
				"phpstorm",
				"pycharm"
			]
		}
	}
}

Request Parameters:

Parameter	Description	Type	Required
`configurationId`	The ID of the configuration	string	true

Response Parameters:

Parameter	Description	Type
`configuration`	The retrieved configuration	object
`configuration.id`	The ID of the configuration	string
`configuration.organizationId`	The ID of the organization	string
`configuration.name`	The display name of the configuration	string
`configuration.cloneUrl`	The clone URL of the repository	string
`configuration.creationTime`	The time when the configuration was created	string (timestamp in ISO 8601 format)
`configuration.prebuildSettings`	The prebuild settings for the configuration	object
`configuration.workspaceSettings`	The workspace settings for the configuration	object

List Configurations

Lists all configurations for an organization.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.ConfigurationService/ListConfigurations" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORGANIZATION_ID>",
  "pagination": {
    "token": "<NEXT_TOKEN>"
  },
  "sort": [
    {"field":"name","order":"SORT_ORDER_ASC"}
  ]
  }'

{
	"configurations": [
		{
			"id": "14839672-4894-4d41-bd62-d5a1dc4cd2bc",
			"organizationId": "8818c76e-9c91-45e9-94fe-2d312cad0f5a",
			"name": "spring-petclinic-multirepo",
			"cloneUrl": "https://github.com/meysholdt/spring-petclinic-multirepo.git",
			"creationTime": "2024-10-23T07:31:57.508Z",
			"prebuildSettings": {
				"enabled": true,
				"branchMatchingPattern": "**",
				"branchStrategy": "BRANCH_MATCHING_STRATEGY_ALL_BRANCHES",
				"workspaceClass": "g1-large",
				"triggerStrategy": "PREBUILD_TRIGGER_STRATEGY_ACTIVITY_BASED",
				"cloneSettings": {}
			},
			"workspaceSettings": {}
		},
		{
			"id": "94a50e67-6982-48aa-974a-707918d1bf24",
			"organizationId": "8818c76e-9c91-45e9-94fe-2d312cad0f5a",
			"name": "test",
			"cloneUrl": "https://github.com/gitpod-samples/test.git",
			"creationTime": "2024-10-28T10:35:35.279Z",
			"prebuildSettings": {
				"enabled": true,
				"branchMatchingPattern": "main",
				"branchStrategy": "BRANCH_MATCHING_STRATEGY_MATCHED_BRANCHES",
				"workspaceClass": "g1-standard",
				"triggerStrategy": "PREBUILD_TRIGGER_STRATEGY_ACTIVITY_BASED",
				"cloneSettings": {}
			},
			"workspaceSettings": {}
		}
	],
	"pagination": {
		"nextToken": "eyJvZmZzZXQiOjI1fQ=="
	}
}

Request Parameters:

Parameter	Description	Type	Required
`organizationId`	The ID of an organization	string	true
`pagination`	Pagination details for the request	object	false
`pagination.token`	The next token for pagination (value of `nextToken` from the previous response)	string	false
`sort`	Sorting details for the request	array	false
`sort[0].field`	The field to sort by (either `name` or `creationTime`)	string	true
`sort[0].order`	The order to sort by (either `SORT_ORDER_ASC` or `SORT_ORDER_DESC`)	string	true

Response Parameters:

Parameter	Description	Type
`configurations`	A list of configurations	array
`configurations[0].id`	The ID of a configuration	string
`configurations[0].organizationId`	The ID of an organization	string
`configurations[0].name`	The display name of a configuration	string
`configurations[0].cloneUrl`	The clone URL of a repository	string
`configurations[0].creationTime`	The time when a configuration was created	string (timestamp in ISO 8601 format)
`configurations[0].prebuildSettings`	The prebuild settings for a configuration	object
`configurations[0].workspaceSettings`	The workspace settings for a configuration	object
`pagination`	Pagination details for the response	object
`pagination.nextToken`	The next token for pagination	string

Update Configuration

Updates a configuration.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.ConfigurationService/UpdateConfiguration" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
  "configurationId": "<CONFIGURATION_ID>",
  "name": "<NEW_NAME>"
  }'

{
	"configuration": {
		"id": "14839672-4894-4d41-bd62-d5a1dc4cd2bc",
		"organizationId": "8818c76e-9c91-45e9-94fe-2d312cad0f5a",
		"name": "new-name",
		"cloneUrl": "https://github.com/meysholdt/spring-petclinic-multirepo.git",
		"creationTime": "2024-10-23T07:31:57.508Z",
		"prebuildSettings": {
			"enabled": true,
			"branchMatchingPattern": "**",
			"branchStrategy": "BRANCH_MATCHING_STRATEGY_ALL_BRANCHES",
			"workspaceClass": "g1-large",
			"triggerStrategy": "PREBUILD_TRIGGER_STRATEGY_ACTIVITY_BASED",
			"cloneSettings": {}
		},
		"workspaceSettings": {}
	}
}

Request Parameters:

Parameter	Description	Type	Required
`configurationId`	The ID of a configuration	string	true
`name`	The display name of a configuration	string	false
`prebuildSettings`	The prebuild settings for a configuration	object	false
`workspaceSettings`	The workspace settings for a configuration	object	false

Response Parameters:

Parameter	Description	Type
`configuration`	The updated configuration	object
`configuration.id`	The ID of the updated configuration	string
`configuration.organizationId`	The ID of the organization the configuration belongs to	string
`configuration.name`	The display name of the updated configuration	string
`configuration.cloneUrl`	The clone URL of the repository the configuration belongs to	string
`configuration.creationTime`	The time when the configuration was created	string (timestamp in ISO 8601 format)
`configuration.prebuildSettings`	The prebuild settings for the configuration	object
`configuration.workspaceSettings`	The workspace settings for the configuration	object

Delete Configuration

Deletes a configuration.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.ConfigurationService/DeleteConfiguration" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
  "configurationId": "<CONFIGURATION_ID>"
  }'

{}

Request Parameters:

Parameter	Description	Type	Required
`configurationId`	The ID of a configuration	string	true

Response Parameters: none

Resource: Environment Variables

GItpod offers programmatic access to manage environment variables of Imported repositories. You can also view the protocol buffer definitions here for more details.

Create Configuration Environment Variable

Creates an environment variable for a configuration.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.EnvironmentVariableService/CreateConfigurationEnvironmentVariable" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
  "configurationId": "<CONFIGURATION_ID>",
  "name": "<NAME>",
  "value": "<VALUE>",
  "admission": "<ADMISSION>"
  }'

{
	"environmentVariable": {
		"id": "7039e108-9648-43ff-a618-b34bf5327a93",
		"name": "HELLO",
		"configurationId": "13dfbcce-78c4-47ac-a6be-5b4edf20ecc8",
		"admission": "ENVIRONMENT_VARIABLE_ADMISSION_PREBUILD"
	}
}

Request Parameters:

Parameter	Description	Type	Required
`configurationId`	The ID of a configuration	string	true
`name`	The name of an environment variable	string	true
`value`	The value of an environment variable	string	true
`admission`	The “visibility” of an environment variable. Either `ENVIRONMENT_VARIABLE_ADMISSION_EVERYWHERE` (default) or `ENVIRONMENT_VARIABLE_ADMISSION_PREBUILD`	string	false

Response Parameters:

Parameter	Description	Type
`environmentVariable`	The created environment variable	object
`environmentVariable.id`	The ID of the created environment variable	string
`environmentVariable.name`	The name of the created environment variable	string
`environmentVariable.configurationId`	The ID of the configuration the environment variable belongs to	string
`environmentVariable.admission`	The “visibility” of the created environment variable. Either `ENVIRONMENT_VARIABLE_ADMISSION_EVERYWHERE` or `ENVIRONMENT_VARIABLE_ADMISSION_PREBUILD`	string

List Configuration Environment Variables

Lists all environment variables for a configuration.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.EnvironmentVariableService/ListConfigurationEnvironmentVariables" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
  "configurationId": "<CONFIGURATION_ID>"
  }'

{
	"environmentVariables": [
		{
			"id": "3a258fef-df87-4f6d-b4e8-f4a4fa3fe1f1",
			"name": "TZ",
			"configurationId": "13dfbcce-78c4-47ac-a6be-5b4edf20ecc8",
			"admission": "ENVIRONMENT_VARIABLE_ADMISSION_EVERYWHERE"
		},
		{
			"id": "4cc1cb42-8fb1-44bc-be0b-4de02e71e7e9",
			"name": "SECRET_VAR_1",
			"configurationId": "13dfbcce-78c4-47ac-a6be-5b4edf20ecc8",
			"admission": "ENVIRONMENT_VARIABLE_ADMISSION_EVERYWHERE"
		},
		{
			"id": "b330e236-9700-446c-8bd4-4616aab75e91",
			"name": "SECRET_VAR_2",
			"configurationId": "13dfbcce-78c4-47ac-a6be-5b4edf20ecc8",
			"admission": "ENVIRONMENT_VARIABLE_ADMISSION_EVERYWHERE"
		}
	]
}

Request Parameters:

Parameter	Description	Type	Required
`configurationId`	The ID of a configuration	string	true

Response Parameters:

Parameter	Description	Type
`environmentVariables`	A list of environment variables	array
`environmentVariables[0].id`	The ID of an environment variable	string
`environmentVariables[0].name`	The name of an environment variable	string
`environmentVariables[0].configurationId`	The ID of a configuration	string
`environmentVariables[0].admission`	The “visibility” of an environment variable. Either `ENVIRONMENT_VARIABLE_ADMISSION_EVERYWHERE` or `ENVIRONMENT_VARIABLE_ADMISSION_PREBUILD`	string

Delete Configuration Environment Variable

Deletes an environment variable for a configuration.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.EnvironmentVariableService/DeleteConfigurationEnvironmentVariable" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
  "environment_variable_id": "<ENVIRONMENT_VARIABLE_ID>"
  }'

{}

Request Parameters:

Parameter	Description	Type	Required
`environment_variable_id`	The ID of an environment variable	string	true

Response Parameters: none

Introduction

Configure

References

Integrations

Enterprise

Help

Authentication

Resource: Workspaces

Create and start a workspace

List all workspaces

Get a workspace

Start a workspace

Stop a workspace

Delete a workspace

List workspace sessions

Resource: Organizations

Create an organization

List all organizations

Get an organization

Delete an organization

Get an organization’s settings

Update an organization’s settings

Join an organization

Reset organization invitation

Get list of all organization members

Update an organization member role

Delete or Remove an organization member

Resource: Audit Logs

List audit logs

Resource: Configurations (aka Repository Settings)

Create Configuration

Get Configuration

List Configurations

Update Configuration

Delete Configuration

Resource: Environment Variables

Create Configuration Environment Variable

List Configuration Environment Variables

Delete Configuration Environment Variable

​Authentication

​Resource: Workspaces

​Create and start a workspace

​List all workspaces

​Get a workspace

​Start a workspace

​Stop a workspace

​Delete a workspace

​List workspace sessions

​Resource: Organizations

​Create an organization

​List all organizations

​Get an organization

​Delete an organization

​Get an organization’s settings

​Update an organization’s settings

​Join an organization

​Reset organization invitation

​Get list of all organization members

​Update an organization member role

​Delete or Remove an organization member

​Resource: Audit Logs

​List audit logs

​Resource: Configurations (aka Repository Settings)

​Create Configuration

​Get Configuration

​List Configurations

​Update Configuration

​Delete Configuration

​Resource: Environment Variables

​Create Configuration Environment Variable

​List Configuration Environment Variables

​Delete Configuration Environment Variable

Authentication

Resource: Workspaces

Create and start a workspace

List all workspaces

Get a workspace

Start a workspace

Stop a workspace

Delete a workspace

List workspace sessions

Resource: Organizations

Create an organization

List all organizations

Get an organization

Delete an organization

Get an organization’s settings

Update an organization’s settings

Join an organization

Reset organization invitation

Get list of all organization members

Update an organization member role

Delete or Remove an organization member

Resource: Audit Logs

List audit logs

Resource: Configurations (aka Repository Settings)

Create Configuration

Get Configuration

List Configurations

Update Configuration

Delete Configuration

Resource: Environment Variables

Create Configuration Environment Variable

List Configuration Environment Variables

Delete Configuration Environment Variable