# Editors

## ListEditors

**post** `/gitpod.v1.EditorService/ListEditors`

Lists all available code editors, optionally filtered to those allowed in an organization.

Use this method to:

- View supported editors
- Get editor capabilities
- Browse editor options
- Check editor availability

### Examples

- List editors:

  Shows all available editors with pagination.

  ```yaml
  pagination:
    pageSize: 20
  ```

- List editors available to the organization:

  Shows all available editors that are allowed by the policies enforced in the organization with pagination.

  ```yaml
  pagination:
    pageSize: 20
  filter:
    allowedByPolicy: true
  ```

### Query Parameters

- `token: optional string`

- `pageSize: optional number`

### Body Parameters

- `filter: optional object { allowedByPolicy }`

  filter contains the filter options for listing editors

  - `allowedByPolicy: optional boolean`

    allowed_by_policy filters the response to only editors that are allowed by the policies enforced in the organization

- `pagination: optional object { token, pageSize }`

  pagination contains the pagination options for listing environments

  - `token: optional string`

    Token for the next set of results that was returned as next_token of a
    PaginationResponse

  - `pageSize: optional number`

    Page size is the maximum number of results to retrieve per page.
    Defaults to 25. Maximum 100.

### Returns

- `editors: array of Editor`

  editors contains the list of editors

  - `id: string`

  - `installationInstructions: string`

  - `name: string`

  - `urlTemplate: string`

  - `alias: optional string`

  - `iconUrl: optional string`

  - `shortDescription: optional string`

  - `versions: optional array of EditorVersion`

    versions contains the list of available versions for this editor

    - `version: string`

      version is the version string of the editor
      Examples for JetBrains: 2025.2

- `pagination: optional object { nextToken }`

  pagination contains the pagination options for listing environments

  - `nextToken: optional string`

    Token passed for retrieving the next set of results. Empty if there are no
    more results

### Example

```http
curl https://app.gitpod.io/api/gitpod.v1.EditorService/ListEditors \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
```

#### Response

```json
{
  "editors": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "installationInstructions": "installationInstructions",
      "name": "name",
      "urlTemplate": "urlTemplate",
      "alias": "alias",
      "iconUrl": "iconUrl",
      "shortDescription": "shortDescription",
      "versions": [
        {
          "version": "version"
        }
      ]
    }
  ],
  "pagination": {
    "nextToken": "nextToken"
  }
}
```

## ResolveEditorURL

**post** `/gitpod.v1.EditorService/ResolveEditorURL`

Resolves the URL for accessing an editor in a specific environment.

Use this method to:

- Get editor access URLs
- Launch editors for environments
- Set up editor connections
- Configure editor access

### Examples

- Resolve editor URL:

  Gets the URL for accessing an editor in an environment.

  ```yaml
  editorId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
  organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
  ```

### Body Parameters

- `editorId: string`

  editorId is the ID of the editor to resolve the URL for

- `environmentId: string`

  environmentId is the ID of the environment to resolve the URL for

- `organizationId: string`

  organizationId is the ID of the organization to resolve the URL for

- `version: optional string`

  version is the editor version to use
  If not provided, the latest version will be installed

  Examples for JetBrains: 2025.2

### Returns

- `url: string`

  url is the resolved editor URL

### Example

```http
curl https://app.gitpod.io/api/gitpod.v1.EditorService/ResolveEditorURL \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "editorId": "d2c94c27-3b76-4a42-b88c-95a85e392c68",
          "environmentId": "07e03a28-65a5-4d98-b532-8ea67b188048",
          "organizationId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
        }'
```

#### Response

```json
{
  "url": "url"
}
```

## GetEditor

**post** `/gitpod.v1.EditorService/GetEditor`

Gets details about a specific editor.

Use this method to:

- View editor information
- Get editor configuration

### Examples

- Get editor details:

  Retrieves information about a specific editor.

  ```yaml
  id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  ```

### Body Parameters

- `id: string`

  id is the ID of the editor to get

### Returns

- `editor: Editor`

  editor contains the editor

  - `id: string`

  - `installationInstructions: string`

  - `name: string`

  - `urlTemplate: string`

  - `alias: optional string`

  - `iconUrl: optional string`

  - `shortDescription: optional string`

  - `versions: optional array of EditorVersion`

    versions contains the list of available versions for this editor

    - `version: string`

      version is the version string of the editor
      Examples for JetBrains: 2025.2

### Example

```http
curl https://app.gitpod.io/api/gitpod.v1.EditorService/GetEditor \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "id": "d2c94c27-3b76-4a42-b88c-95a85e392c68"
        }'
```

#### Response

```json
{
  "editor": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "installationInstructions": "installationInstructions",
    "name": "name",
    "urlTemplate": "urlTemplate",
    "alias": "alias",
    "iconUrl": "iconUrl",
    "shortDescription": "shortDescription",
    "versions": [
      {
        "version": "version"
      }
    ]
  }
}
```

## Domain Types

### Editor

- `Editor object { id, installationInstructions, name, 5 more }`

  - `id: string`

  - `installationInstructions: string`

  - `name: string`

  - `urlTemplate: string`

  - `alias: optional string`

  - `iconUrl: optional string`

  - `shortDescription: optional string`

  - `versions: optional array of EditorVersion`

    versions contains the list of available versions for this editor

    - `version: string`

      version is the version string of the editor
      Examples for JetBrains: 2025.2

### Editor Version

- `EditorVersion object { version }`

  - `version: string`

    version is the version string of the editor
    Examples for JetBrains: 2025.2

### Editor Resolve URL Response

- `EditorResolveURLResponse object { url }`

  - `url: string`

    url is the resolved editor URL

### Editor Retrieve Response

- `EditorRetrieveResponse object { editor }`

  - `editor: Editor`

    editor contains the editor

    - `id: string`

    - `installationInstructions: string`

    - `name: string`

    - `urlTemplate: string`

    - `alias: optional string`

    - `iconUrl: optional string`

    - `shortDescription: optional string`

    - `versions: optional array of EditorVersion`

      versions contains the list of available versions for this editor

      - `version: string`

        version is the version string of the editor
        Examples for JetBrains: 2025.2