> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/ona/getting-started)
and [its API](https://ona.com/docs/api-reference).
## Authentication
To authenticate requests, the Gitpod API utilizes [Access Token](/classic/user/configure/user-settings/access-tokens). In the [Gitpod settings](https://gitpod.io/tokens), 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 `.
Example cURL command:
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.OrganizationService/ListOrganizations' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{}'
```
## Resource: Workspaces
### Create and start a workspace
Creates and starts a new workspace from a [context URL](/classic/user/introduction/gitpod-tutorial/1-start-your-workspace#open-your-repository) such as repositories, issues, pull requests, files URL.
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.WorkspaceService/CreateAndStartWorkspace' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{
"contextUrl": {
"url": "",
"workspaceClass": "g1-standard",
"editor": {
"name": "code",
"version": "latest"
}
},
"metadata": {
"ownerId": "",
"organizationId": ""
}
}'
```
```json Response theme={null}
{
"workspaceId": ""
}
```
**Request Parameters**:
| Parameter | Description | Type | Required |
| :-------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----: | :------: |
| `contextUrl.url` | [Context URL](/classic/user/introduction/gitpod-tutorial/1-start-your-workspace#open-your-repository) ( Repository, Issues, Pull Request URL) | string | true |
| `contextUrl.workspaceClass` | [Workspace class](/classic/user/configure/workspaces/workspace-classes) (`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.
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.WorkspaceService/ListWorkspaces' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{
"organizationId": ""
}'
```
```json Response theme={null}
{
"pagination": {
"total": 2
},
"workspaces": [
{
"id": "",
"metadata": {
"ownerId": "",
"organizationId": "",
"configurationId": "",
"name": "",
"originalContextUrl": ""
},
"spec": {
"initializer": {
"specs": [
{
"git": {
"remoteUri": "",
"targetMode": "CLONE_TARGET_MODE_REMOTE_COMMIT",
"cloneTarget": "",
"checkoutLocation": "",
"config": {}
}
}
]
},
"type": "WORKSPACE_TYPE_REGULAR",
"ports": [
{
"port": "",
"admission": "ADMISSION_LEVEL_OWNER_ONLY",
"url": "",
"protocol": "PROTOCOL_HTTP"
}
],
"git": {},
"timeout": {
"disconnected": ""
},
"admission": "ADMISSION_LEVEL_OWNER_ONLY",
"class": "",
"editor": {
"name": "",
"version": ""
}
},
"status": {
"statusVersion": "",
"phase": {
"name": "PHASE_STOPPED",
"lastTransitionTime": "2024-02-03T19:34:24.939Z"
},
"workspaceUrl": "",
"conditions": {},
"gitStatus": {
"cloneUrl": "",
"branch": "",
"latestCommit": ""
},
"instanceId": ""
}
},
{
"id": "",
"metadata": {
"ownerId": "",
"organizationId": "",
"configurationId": "",
"name": "",
"originalContextUrl": ""
},
"spec": {
"initializer": {
"specs": [
{
"git": {
"remoteUri": "",
"targetMode": "CLONE_TARGET_MODE_REMOTE_COMMIT",
"cloneTarget": "",
"checkoutLocation": "",
"config": {}
}
}
]
},
"type": "WORKSPACE_TYPE_REGULAR",
"ports": [
{
"port": "",
"admission": "ADMISSION_LEVEL_OWNER_ONLY",
"url": "",
"protocol": "PROTOCOL_HTTP"
}
],
"git": {},
"timeout": {
"disconnected": ""
},
"admission": "ADMISSION_LEVEL_OWNER_ONLY",
"class": "",
"editor": {
"name": "",
"version": ""
}
},
"status": {
"statusVersion": "",
"phase": {
"name": "PHASE_STOPPED",
"lastTransitionTime": "2024-02-03T10:46:55.354Z"
},
"workspaceUrl": "",
"conditions": {},
"gitStatus": {
"cloneUrl": "",
"branch": "",
"latestCommit": ""
},
"instanceId": ""
}
}
]
}
```
**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.
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.WorkspaceService/GetWorkspace' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{
"workspaceId": ""
}'
```
```json Response theme={null}
{
"workspace": {
"id": "",
"metadata": {
"ownerId": "",
"organizationId": "",
"configurationId": "",
"name": "",
"originalContextUrl": ""
},
"spec": {
"initializer": {
"specs": [
{
"git": {
"remoteUri": "",
"targetMode": "CLONE_TARGET_MODE_REMOTE_COMMIT",
"cloneTarget": "",
"checkoutLocation": "",
"config": {}
}
}
]
},
"type": "WORKSPACE_TYPE_REGULAR",
"ports": [
{
"port": "",
"admission": "ADMISSION_LEVEL_OWNER_ONLY",
"url": "",
"protocol": "PROTOCOL_HTTP"
}
],
"git": {},
"timeout": {
"disconnected": ""
},
"admission": "ADMISSION_LEVEL_OWNER_ONLY",
"class": "",
"editor": {
"name": "",
"version": ""
}
},
"status": {
"statusVersion": "",
"phase": {
"name": "PHASE_STOPPED",
"lastTransitionTime": "2024-02-03T19:34:24.939Z"
},
"workspaceUrl": "",
"conditions": {},
"gitStatus": {
"cloneUrl": "",
"branch": "",
"latestCommit": ""
},
"instanceId": ""
}
}
}
```
**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).
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.WorkspaceService/StartWorkspace' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{
"workspaceId": ""
}'
```
```json Response theme={null}
{
"workspace": {
"id": "",
"metadata": {
"ownerId": "",
"organizationId": "",
"configurationId": "",
"name": "",
"originalContextUrl": ""
},
"spec": {
"initializer": {
"specs": [
{
"git": {
"remoteUri": "",
"targetMode": "CLONE_TARGET_MODE_REMOTE_COMMIT",
"cloneTarget": "",
"checkoutLocation": "",
"config": {}
}
}
]
},
"type": "WORKSPACE_TYPE_REGULAR",
"ports": [
{
"port": "",
"admission": "ADMISSION_LEVEL_OWNER_ONLY",
"url": "",
"protocol": "PROTOCOL_HTTP"
}
],
"git": {},
"timeout": {
"disconnected": ""
},
"admission": "ADMISSION_LEVEL_OWNER_ONLY",
"class": "",
"editor": {
"name": "",
"version": ""
}
},
"status": {
"statusVersion": "",
"phase": {
"name": "PHASE_STOPPED",
"lastTransitionTime": "2024-02-03T19:34:24.939Z"
},
"workspaceUrl": "",
"conditions": {},
"gitStatus": {
"cloneUrl": "",
"branch": "",
"latestCommit": ""
},
"instanceId": ""
}
}
}
```
**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).
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.WorkspaceService/StopWorkspace' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{
"workspaceId": ""
}'
```
```json Response theme={null}
{}
```
**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.
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.WorkspaceService/DeleteWorkspace' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{
"workspaceId": ""
}'
```
```json Response theme={null}
{}
```
**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`.
```bash cURL theme={null}
curl -X POST \
"https://api.gitpod.io/gitpod.v1.WorkspaceService/ListWorkspaceSessions" \
--header "Authorization: Bearer $TOKEN" \
--header 'content-type: application/json' \
--data-raw '{
"organizationId": "",
"pagination": {
"pageSize": 20,
"page": 0
},
"from": "2024-01-13T07:06:45.659Z",
"to": "2024-07-13T07:06:48.659Z"
}'
}'
```
```json Response theme={null}
{
"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](https://github.com/gitpod-io/gitpod/blob/main/components/public-api/gitpod/v1/organization.proto) for more details.
### Create an organization
Creates an organization.
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.OrganizationService/CreateOrganization' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{
"name": ""
}'
```
```json Response theme={null}
{
"organization": {
"id": "",
"name": "",
"creationTime": "2023-03-13T11:42:16.700Z",
"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.
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.OrganizationService/ListOrganizations' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{}'
```
```json Response theme={null}
{
"organizations": [
{
"id": "",
"name": "",
"creationTime": "2023-01-04T16:02:14.327Z",
"slug": ""
},
{
"id": "",
"name": "",
"creationTime": "2023-03-13T11:42:16.700Z",
"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.
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.OrganizationService/GetOrganization' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{
"organizationId": ""
}'
```
```json Response theme={null}
{
"organization": {
"id": "",
"name": "",
"creationTime": "2023-03-13T11:42:16.700Z",
"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.
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.OrganizationService/DeleteOrganization' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{
"organizationId": ""
}'
```
```json Response theme={null}
{}
```
**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.
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.OrganizationService/GetOrganizationSettings' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{
"organizationId": ""
}'
```
```json Response theme={null}
{
"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](/classic/user/configure/orgs/policies#workspace-timeouts)) | 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](/classic/user/configure/orgs/policies#limit-the-amount-of-concurrently-running-workspaces-per-user)) | Int32 |
| `settings.onboardingSettings` | Onboarding settings (see the [Organization Onboarding](/classic/user/configure/orgs/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](/classic/user/configure/orgs/settings#git-commit-annotation)) | Boolean |
### Update an organization's settings
Performs a partial update of an organization's settings.
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.OrganizationService/UpdateOrganizationSettings' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{
"organizationId": "",
"settings": {
"defaultWorkspaceImage": "docker.io/gitpod/workspace-full"
}
}'
```
```json Response theme={null}
{
"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](#get-an-organizations-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](/classic/user/configure/orgs/policies#workspace-timeouts)) | 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](/classic/user/configure/orgs/policies#limit-the-amount-of-concurrently-running-workspaces-per-user)) | Int32 | |
| `onboardingSettings` | Onboarding settings (see the [Organization Onboarding](/classic/user/configure/orgs/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](/classic/user/configure/orgs/settings#git-commit-annotation)) | Boolean | |
**Response Parameters**:
| Parameter | Description | Type |
| :--------: | :--------------: | :----: |
| `settings` | Updated settings | Object |
### Join an organization
Joins an organization.
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.OrganizationService/JoinOrganization' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{
"invitationId": ""
}'
```
```json Response theme={null}
{
"organizationId": ""
}
```
**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.
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.OrganizationService/ResetOrganizationInvitation' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{
"organizationId": ""
}'
```
```json Response theme={null}
{
"invitationId": ""
}
```
**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](/classic/user/configure/orgs/members#member-roles).
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.OrganizationService/ListOrganizationMembers' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{
"organizationId": ""
}'
```
```json Response theme={null}
{
"members": [
{
"userId": "",
"role": "",
"memberSince": "2022-12-22T09:50:50.234Z",
"avatarUrl": "",
"fullName": "",
"email": ""
},
{
"userId": "",
"role": "",
"memberSince": "2022-12-22T09:45:41.465Z",
"avatarUrl": "",
"fullName": "",
"email": ""
}
{
"userId": "",
"role": "",
"memberSince": "2023-12-22T09:45:41.465Z",
"avatarUrl": "",
"fullName": "",
"email": ""
}
],
"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
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.OrganizationService/UpdateOrganizationMember' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{
"organizationId": "",
"userId": "",
"role": ""
}'
```
```json Response theme={null}
{
"member": {
"userId": "",
"role": "",
"memberSince": "2022-12-22T09:45:41.465Z",
"avatarUrl": "",
"fullName": "",
"email": ""
}
}
```
**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.
```bash cURL theme={null}
curl -X POST \
'https://api.gitpod.io/gitpod.v1.OrganizationService/DeleteOrganizationMember' \
--header 'Authorization: Bearer ' \
--header 'content-type: application/json' \
--data-raw '{
"organizationId": "",
"userId": ""
}'
```
```json Response theme={null}
{}
```
**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.
```bash cURL theme={null}
curl -X POST \
"https://api.gitpod.io/gitpod.v1.AuditLogService/ListAuditLogs" \
--header "Authorization: Bearer $TOKEN" \
--header 'content-type: application/json' \
--data-raw '{
"organizationId": "",
"pagination": {
"pageSize": 200,
"page": 0
},
"from": "2024-01-13T07:06:45.659Z",
"to": "2024-07-13T07:06:48.659Z"
}'
```
```json Response theme={null}
{
"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](/classic/user/configure/repositories).
You can also view the protocol buffer definitions [here](https://github.com/gitpod-io/gitpod/blob/main/components/public-api/gitpod/v1/configuration.proto) for more details.
### Create Configuration
Imports a repository into Gitpod.
```bash cURL theme={null}
curl -X POST \
"https://api.gitpod.io/gitpod.v1.ConfigurationService/CreateConfiguration" \
--header "Authorization: Bearer $TOKEN" \
--header 'content-type: application/json' \
--data-raw '{
"organizationId": "",
"cloneUrl": ""
}'
```
```json Response theme={null}
{
"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.
```bash cURL theme={null}
curl -X POST \
"https://api.gitpod.io/gitpod.v1.ConfigurationService/GetConfiguration" \
--header "Authorization: Bearer $TOKEN" \
--header 'content-type: application/json' \
--data-raw '{
"configurationId": ""
}'
```
```json Response theme={null}
{
"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.
```bash cURL theme={null}
curl -X POST \
"https://api.gitpod.io/gitpod.v1.ConfigurationService/ListConfigurations" \
--header "Authorization: Bearer $TOKEN" \
--header 'content-type: application/json' \
--data-raw '{
"organizationId": "",
"pagination": {
"token": ""
},
"sort": [
{"field":"name","order":"SORT_ORDER_ASC"}
]
}'
```
```json Response theme={null}
{
"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.
```bash cURL theme={null}
curl -X POST \
"https://api.gitpod.io/gitpod.v1.ConfigurationService/UpdateConfiguration" \
--header "Authorization: Bearer $TOKEN" \
--header 'content-type: application/json' \
--data-raw '{
"configurationId": "",
"name": ""
}'
```
```json Response theme={null}
{
"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.
```bash cURL theme={null}
curl -X POST \
"https://api.gitpod.io/gitpod.v1.ConfigurationService/DeleteConfiguration" \
--header "Authorization: Bearer $TOKEN" \
--header 'content-type: application/json' \
--data-raw '{
"configurationId": ""
}'
```
```json Response theme={null}
{}
```
**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](/classic/user/configure/repositories/environment-variables).
You can also view the protocol buffer definitions [here](https://github.com/gitpod-io/gitpod/blob/main/components/public-api/gitpod/v1/envvar.proto) for more details.
### Create Configuration Environment Variable
Creates an environment variable for a configuration.
```bash cURL theme={null}
curl -X POST \
"https://api.gitpod.io/gitpod.v1.EnvironmentVariableService/CreateConfigurationEnvironmentVariable" \
--header "Authorization: Bearer $TOKEN" \
--header 'content-type: application/json' \
--data-raw '{
"configurationId": "",
"name": "",
"value": "",
"admission": ""
}'
```
```json Response theme={null}
{
"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.
```bash cURL theme={null}
curl -X POST \
"https://api.gitpod.io/gitpod.v1.EnvironmentVariableService/ListConfigurationEnvironmentVariables" \
--header "Authorization: Bearer $TOKEN" \
--header 'content-type: application/json' \
--data-raw '{
"configurationId": ""
}'
```
```json Response theme={null}
{
"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.
```bash cURL theme={null}
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": ""
}'
```
```json Response theme={null}
{}
```
**Request Parameters**:
| Parameter | Description | Type | Required |
| :------------------------ | :-------------------------------- | :----- | :------- |
| `environment_variable_id` | The ID of an environment variable | string | true |
**Response Parameters**: none