LogoGitpod API Reference

Projects

projects

Methods

Create Project -> { project }
post/gitpod.v1.ProjectService/CreateProject

Creates a new project with specified configuration.

Use this method to:

  • Set up development projects
  • Configure project environments
  • Define project settings
  • Initialize project content

Examples

  • Create basic project:

    Creates a project with minimal configuration.

    name: "Web Application"
initializer:
  specs:
    - git:
        remoteUri: "https://github.com/org/repo"

  • Create project with devcontainer:

    Creates a project with custom development container.

    name: "Backend Service"
initializer:
  specs:
    - git:
        remoteUri: "https://github.com/org/backend"
devcontainerFilePath: ".devcontainer/devcontainer.json"
automationsFilePath: ".gitpod/automations.yaml"
Create Project From Environment -> { project }
post/gitpod.v1.ProjectService/CreateProjectFromEnvironment

Creates a new project using an existing environment as a template.

Use this method to:

  • Clone environment configurations
  • Create projects from templates
  • Share environment setups

Examples

  • Create from environment:

    Creates a project based on existing environment.

    name: "Frontend Project"
environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
Delete Project -> unknown
post/gitpod.v1.ProjectService/DeleteProject

Deletes a project permanently.

Use this method to:

  • Remove unused projects
  • Clean up test projects
  • Delete obsolete configurations

Examples

  • Delete project:

    Permanently removes a project.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
List Projects -> ProjectsPage<
Project
>
post/gitpod.v1.ProjectService/ListProjects

Lists projects with optional filtering.

Use this method to:

  • View all accessible projects
  • Browse project configurations
  • Monitor project status

Examples

  • List projects:

    Shows all projects with pagination.

    pagination:
  pageSize: 20
Get Project -> { project }
post/gitpod.v1.ProjectService/GetProject

Gets details about a specific project.

Use this method to:

  • View project configuration
  • Check project status
  • Get project metadata

Examples

  • Get project details:

    Retrieves information about a specific project.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
Update Project -> { project }
post/gitpod.v1.ProjectService/UpdateProject

Updates a project's configuration.

Use this method to:

  • Modify project settings
  • Update environment class
  • Change project name
  • Configure initializers
  • Configure prebuild settings

Examples

  • Update project name:

    Changes the project's display name.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
name: "New Project Name"

  • Enable prebuilds with daily schedule:

    Configures prebuilds to run daily at 2 AM UTC.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
prebuildConfiguration:
  enabled: true
  environmentClassIds:
    - "b0e12f6c-4c67-429d-a4a6-d9838b5da041"
  timeout: "3600s"
  trigger:
    dailySchedule:
      hourUtc: 2

Domain types

EnvironmentInitializer = { specs }

EnvironmentInitializer specifies how an environment is to be initialized

Project = { environmentClass, id, automationsFilePath, 8 more... }
ProjectMetadata = { createdAt, creator, name, 2 more... }
ProjectPhase = "PROJECT_PHASE_UNSPECIFIED" | "PROJECT_PHASE_ACTIVE" | "PROJECT_PHASE_DELETED"
ProjectPrebuildConfiguration = { enabled, enableJetbrainsWarmup, environmentClassIds, 3 more... }

ProjectPrebuildConfiguration defines how prebuilds are created for a project. Prebuilds create environment snapshots that enable faster environment startup times.

Projects

Environment Clases

projects.environmentClases

Methods

List Project Environment Classes -> ProjectEnvironmentClassesPage<
ProjectEnvironmentClass
>
post/gitpod.v1.ProjectService/ListProjectEnvironmentClasses

Lists environment classes of a project.

Use this method to:

  • View all environment classes of a project

Examples

  • List project environment classes:

    Shows all environment classes of a project.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
pagination:
  pageSize: 20
Update Project Environment Classes -> unknown
post/gitpod.v1.ProjectService/UpdateProjectEnvironmentClasses

Updates all environment classes of a project.

Use this method to:

  • Modify all environment classea of a project

Examples

  • Update project environment classes:

    Updates all environment classes for a project.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
projectEnvironmentClasses:
  - environmentClassId: "b0e12f6c-4c67-429d-a4a6-d9838b5da041"
    order: 0
  - localRunner: true
    order: 1
Projects

Policies

projects.policies

Methods

Create Project Policy -> { policy }
post/gitpod.v1.ProjectService/CreateProjectPolicy

Creates a new policy for a project.

Use this method to:

  • Set up access controls
  • Define group permissions
  • Configure role-based access

Examples

  • Create admin policy:

    Grants admin access to a group.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
role: PROJECT_ROLE_ADMIN
Delete Project Policy -> unknown
post/gitpod.v1.ProjectService/DeleteProjectPolicy

Deletes a project policy.

Use this method to:

  • Remove access controls
  • Revoke permissions
  • Clean up policies

Examples

  • Delete policy:

    Removes a group's access policy.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
List Project Policies -> PoliciesPage<
ProjectPolicy
>
post/gitpod.v1.ProjectService/ListProjectPolicies

Lists policies for a project.

Use this method to:

  • View access controls
  • Check policy configurations
  • Audit permissions

Examples

  • List policies:

    Shows all policies for a project.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
pagination:
  pageSize: 20
query Parameters
token: string
Optional
pageSize: number
Optional
(maximum: 100, minimum: 0, default: 25)
Response fields
pagination: { nextToken }
Optional
policies: Array<
ProjectPolicy
>
Optional
Request example
200Example
Update Project Policy -> { policy }
post/gitpod.v1.ProjectService/UpdateProjectPolicy

Updates an existing project policy.

Use this method to:

  • Modify access levels
  • Change group roles
  • Update permissions

Examples

  • Update policy role:

    Changes a group's access level.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
role: PROJECT_ROLE_EDITOR

Domain types

ProjectPolicy = { groupId, role }
ProjectRole = "PROJECT_ROLE_UNSPECIFIED" | "PROJECT_ROLE_ADMIN" | "PROJECT_ROLE_USER" | 1 more...