Gitpod gitpod.v1.IntegrationService API
The gitpod.v1.IntegrationService API from Gitpod — 11 operation(s) for gitpod.v1.integrationservice.
The gitpod.v1.IntegrationService API from Gitpod — 11 operation(s) for gitpod.v1.integrationservice.
openapi: 3.0.0
info:
title: gitpod.v1 gitpod.v1.AccountService gitpod.v1.IntegrationService API
version: v1.0.0
servers:
- url: https://api.gitpod.io
description: Gitpod API
tags:
- name: gitpod.v1.IntegrationService
x-displayName: gitpod.v1.IntegrationService
paths:
/gitpod.v1.IntegrationService/CreateIntegration:
servers: []
post:
description: "Creates a new integration instance within an organization.\n\n Use this method to:\n - Instantiate an integration for an organization\n - Configure integration-specific settings\n - Enable integration capabilities"
operationId: gitpod.v1.IntegrationService.CreateIntegration
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.CreateIntegrationRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.CreateIntegrationResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: CreateIntegration
tags:
- gitpod.v1.IntegrationService
/gitpod.v1.IntegrationService/CreateIntegrationDefinition:
servers: []
post:
description: "Creates a new integration definition.\n Requires service account authentication.\n\n Use this method to:\n - Add new integration types dynamically\n - Configure integration capabilities\n - Set up authentication requirements"
operationId: gitpod.v1.IntegrationService.CreateIntegrationDefinition
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.CreateIntegrationDefinitionRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.CreateIntegrationDefinitionResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: CreateIntegrationDefinition
tags:
- gitpod.v1.IntegrationService
/gitpod.v1.IntegrationService/DeleteIntegration:
servers: []
post:
description: "Deletes an integration instance.\n\n Use this method to:\n - Remove unused integrations\n - Clean up configurations\n - Revoke integration access"
operationId: gitpod.v1.IntegrationService.DeleteIntegration
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.DeleteIntegrationRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.DeleteIntegrationResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: DeleteIntegration
tags:
- gitpod.v1.IntegrationService
/gitpod.v1.IntegrationService/DeleteIntegrationDefinition:
servers: []
post:
description: "Deletes an integration definition.\n Requires service account authentication.\n Fails if any integrations depend on this definition.\n\n Use this method to:\n - Remove unused integration types\n - Clean up deprecated integrations"
operationId: gitpod.v1.IntegrationService.DeleteIntegrationDefinition
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.DeleteIntegrationDefinitionRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.DeleteIntegrationDefinitionResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: DeleteIntegrationDefinition
tags:
- gitpod.v1.IntegrationService
/gitpod.v1.IntegrationService/GetIntegration:
servers: []
post:
description: "Gets details about a specific integration instance.\n\n Use this method to:\n - View integration configuration\n - Check integration status\n - Verify enabled capabilities"
operationId: gitpod.v1.IntegrationService.GetIntegration
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.GetIntegrationRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.GetIntegrationResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: GetIntegration
tags:
- gitpod.v1.IntegrationService
/gitpod.v1.IntegrationService/GetIntegrationDefinition:
servers: []
post:
description: "Gets details about a specific integration definition.\n\n Use this method to:\n - View integration definition configuration\n - Check supported capabilities\n - Verify authentication requirements"
operationId: gitpod.v1.IntegrationService.GetIntegrationDefinition
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.GetIntegrationDefinitionRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.GetIntegrationDefinitionResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: GetIntegrationDefinition
tags:
- gitpod.v1.IntegrationService
/gitpod.v1.IntegrationService/ListIntegrationDefinitions:
servers: []
post:
description: "Lists available integration definitions.\n\n Use this method to:\n - View all available integrations\n - Check integration capabilities\n - Discover supported services"
operationId: gitpod.v1.IntegrationService.ListIntegrationDefinitions
parameters:
- in: query
name: pageSize
schema:
default: 25
maximum: 100
minimum: 0
type: integer
- in: query
name: token
schema:
default: ''
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.ListIntegrationDefinitionsRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.ListIntegrationDefinitionsResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: ListIntegrationDefinitions
tags:
- gitpod.v1.IntegrationService
/gitpod.v1.IntegrationService/ListIntegrations:
servers: []
post:
description: "Lists integration instances for the organization.\n\n Use this method to:\n - View all integrations for an organization\n - Monitor integration configurations"
operationId: gitpod.v1.IntegrationService.ListIntegrations
parameters:
- in: query
name: pageSize
schema:
default: 25
maximum: 100
minimum: 0
type: integer
- in: query
name: token
schema:
default: ''
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.ListIntegrationsRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.ListIntegrationsResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: ListIntegrations
tags:
- gitpod.v1.IntegrationService
/gitpod.v1.IntegrationService/UpdateIntegration:
servers: []
post:
description: "Updates an existing integration instance.\n\n Use this method to:\n - Modify integration settings\n - Enable/disable capabilities\n - Change integration status"
operationId: gitpod.v1.IntegrationService.UpdateIntegration
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.UpdateIntegrationRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.UpdateIntegrationResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: UpdateIntegration
tags:
- gitpod.v1.IntegrationService
/gitpod.v1.IntegrationService/UpdateIntegrationDefinition:
servers: []
post:
description: "Updates an existing integration definition.\n Requires service account authentication.\n\n Use this method to:\n - Modify integration capabilities\n - Update authentication configuration\n - Change integration metadata"
operationId: gitpod.v1.IntegrationService.UpdateIntegrationDefinition
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.UpdateIntegrationDefinitionRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.UpdateIntegrationDefinitionResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: UpdateIntegrationDefinition
tags:
- gitpod.v1.IntegrationService
/gitpod.v1.IntegrationService/ValidateIntegration:
servers: []
post:
description: "Validates an integration's configuration and connectivity.\n\n Runs a set of checks (e.g. app token validity) and returns results for each.\n All checks are always returned; failing checks include a message and an optional action_hint."
operationId: gitpod.v1.IntegrationService.ValidateIntegration
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.ValidateIntegrationRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.ValidateIntegrationResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: ValidateIntegration
tags:
- gitpod.v1.IntegrationService
components:
schemas:
gitpod.v1.IntegrationContextParsingCapability:
additionalProperties: false
description: IntegrationContextParsingCapability defines context parsing capability Additional context parsing configuration can be added here
title: IntegrationContextParsingCapability
type: object
gitpod.v1.ValidationCheck.Check:
enum:
- CHECK_UNSPECIFIED
- CHECK_APP_TOKEN
- CHECK_APP_INSTALLATION
title: Check
type: string
gitpod.v1.IntegrationOAuthConfig:
additionalProperties: false
description: IntegrationOAuthConfig defines OAuth-specific configuration
properties:
authParams:
additionalProperties:
title: value
type: string
description: "auth_params are additional query parameters to include in the OAuth\n authorization URL. Use comma-separated values for multi-value params\n (e.g., \"search:read,chat:write\" for Slack's user_scope)."
title: auth_params
type: object
authUrl:
description: auth_url is the OAuth authorization endpoint URL
title: auth_url
type: string
clientId:
description: client_id is the OAuth client ID (optional if dynamic_registration is enabled)
title: client_id
type: string
clientSecret:
description: client_secret is the OAuth client secret (optional for public clients)
title: client_secret
type: string
dynamicRegistration:
description: "dynamic_registration enables RFC 7591 OAuth 2.0 Dynamic Client Registration.\n When enabled, client credentials are obtained automatically from the authorization\n server's registration endpoint (discovered via RFC 8414 metadata).\n When disabled (default), client_id and client_secret must be pre-configured."
title: dynamic_registration
type: boolean
redirectUrl:
description: redirect_url is the OAuth callback/redirect URL
title: redirect_url
type: string
scopes:
description: scopes are the OAuth scopes to request
items:
type: string
title: scopes
type: array
tokenUrl:
description: token_url is the OAuth token endpoint URL
title: token_url
type: string
title: IntegrationOAuthConfig
type: object
gitpod.v1.IntegrationAPIKeyConfig:
additionalProperties: false
description: IntegrationAPIKeyConfig defines API key authentication configuration Additional API key configuration can be added here
title: IntegrationAPIKeyConfig
type: object
gitpod.v1.ValidateIntegrationRequest:
additionalProperties: false
properties:
integrationId:
minLength: 1
title: integration_id
type: string
title: ValidateIntegrationRequest
type: object
gitpod.v1.ListIntegrationDefinitionsRequest:
additionalProperties: false
properties:
pagination:
$ref: '#/components/schemas/gitpod.v1.PaginationRequest'
title: pagination
title: ListIntegrationDefinitionsRequest
type: object
gitpod.v1.ValidationCheck:
additionalProperties: false
properties:
actionHint:
description: "Machine-readable hint the frontend uses to resolve the issue (e.g. \"app_installation_oauth\").\n Empty when the check passes or no automated fix is available."
title: action_hint
type: string
check:
$ref: '#/components/schemas/gitpod.v1.ValidationCheck.Check'
description: Which check this result is for.
title: check
documentationUrl:
description: "URL to documentation explaining this check failure and resolution steps.\n Empty when the check passes or no docs exist for this check."
title: documentation_url
type: string
message:
description: Human-readable description of the problem. Empty when the check passes.
title: message
type: string
title: ValidationCheck
type: object
gitpod.v1.UpdateIntegrationDefinitionResponse:
additionalProperties: false
properties:
definition:
$ref: '#/components/schemas/gitpod.v1.IntegrationDefinition'
title: definition
required:
- definition
title: UpdateIntegrationDefinitionResponse
type: object
gitpod.v1.Integration:
additionalProperties: false
description: Integration represents an instantiated integration within an organization
properties:
auth:
$ref: '#/components/schemas/gitpod.v1.IntegrationAuthentication'
description: auth defines which authentication methods are enabled for this integration
title: auth
capabilities:
$ref: '#/components/schemas/gitpod.v1.IntegrationCapabilities'
description: capabilities defines which capabilities are enabled for this integration
title: capabilities
enabled:
description: enabled indicates if this integration is currently enabled
title: enabled
type: boolean
host:
description: host is the hostname for this integration (e.g., "linear.app") - optional, inherits from definition
title: host
type: string
id:
description: id is the unique identifier for this integration instance
title: id
type: string
integrationDefinitionId:
description: integration_definition_id references the integration definition ID
title: integration_definition_id
type: string
organizationId:
description: organization_id is the organization this integration belongs to
title: organization_id
type: string
runnerId:
description: runner_id - if set, restricts integration to specific runner
title: runner_id
type: string
required:
- id
- organizationId
- integrationDefinitionId
title: Integration
type: object
connect.error:
additionalProperties: true
description: 'Error type returned by Connect: https://connectrpc.com/docs/go/errors/#http-representation'
properties:
code:
description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
enum:
- canceled
- unknown
- invalid_argument
- deadline_exceeded
- not_found
- already_exists
- permission_denied
- resource_exhausted
- failed_precondition
- aborted
- out_of_range
- unimplemented
- internal
- unavailable
- data_loss
- unauthenticated
example:
- not_found
type: string
message:
description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
type: string
title: Connect Error
type: object
gitpod.v1.ListIntegrationsResponse:
additionalProperties: false
properties:
integrations:
items:
$ref: '#/components/schemas/gitpod.v1.Integration'
title: integrations
type: array
pagination:
$ref: '#/components/schemas/gitpod.v1.PaginationResponse'
title: pagination
required:
- pagination
title: ListIntegrationsResponse
type: object
gitpod.v1.IntegrationAuthentication:
additionalProperties: false
description: IntegrationAuthentication defines authentication requirements and options
properties:
apiKey:
$ref: '#/components/schemas/gitpod.v1.IntegrationAPIKeyConfig'
description: api_key configuration if API key authentication is supported
title: api_key
oauth:
$ref: '#/components/schemas/gitpod.v1.IntegrationOAuthConfig'
description: oauth configuration if OAuth authentication is supported
title: oauth
proprietaryApp:
$ref: '#/components/schemas/gitpod.v1.IntegrationProprietaryAppConfig'
description: proprietary configuration if supported
title: proprietary_app
requiresAuth:
description: requires_auth indicates if authentication is required for this integration
title: requires_auth
type: boolean
title: IntegrationAuthentication
type: object
gitpod.v1.IntegrationProprietaryAppConfig:
additionalProperties: false
description: "IntegrationProprietaryAppConfig defines proprietary application integration configuration.\n Used for app installations that interact with Ona (e.g., GitHub Apps, Linear agent apps)."
properties:
appId:
description: "app_id is the application identifier assigned by the provider (e.g., GitHub App ID).\n Used to authenticate as the application itself."
title: app_id
type: string
appScopes:
description: "app_scopes are OAuth scopes to request when using app installation flows.\n If not set, falls back to the standard OAuth scopes."
items:
type: string
title: app_scopes
type: array
appSlug:
description: "app_slug is the URL-friendly identifier assigned by the provider (e.g., GitHub App slug).\n Used to construct installation URLs like https://github.com/apps/{app_slug}/installations/new."
title: app_slug
type: string
authParams:
additionalProperties:
title: value
type: string
description: "auth_params are additional OAuth authorization parameters to include in the auth URL.\n Example: {\"actor\": \"app\"} for Linear agent installations."
title: auth_params
type: object
clientId:
description: client_id is the app client ID
title: client_id
type: string
clientSecret:
description: client_secret is the app client secret
title: client_secret
type: string
privateKey:
description: "private_key is the PEM-encoded private key used to sign JWTs for app authentication.\n This is sensitive and will be censored in API responses."
title: private_key
type: string
tokenUrl:
description: "token_url is the OAuth token exchange endpoint for app installation flows.\n If not set, falls back to the standard oauth.token_url.\n Slack requires a different token endpoint for app-level vs user-level flows."
title: token_url
type: string
webhookSecret:
description: webhook_secret is the secret used to verify webhook signatures from the app provider
title: webhook_secret
type: string
title: IntegrationProprietaryAppConfig
type: object
gitpod.v1.PaginationRequest:
additionalProperties: false
properties:
pageSize:
description: "Page size is the maximum number of results to retrieve per page.\n Defaults to 25. Maximum 100."
format: int32
maximum: 100
title: page_size
type: integer
token:
description: "Token for the next set of results that was returned as next_token of a\n PaginationResponse"
title: token
type: string
title: PaginationRequest
type: object
gitpod.v1.ValidateIntegrationResponse:
additionalProperties: false
properties:
checks:
description: "checks contains the result of every check performed.\n Passing checks have empty message and action_hint."
items:
$ref: '#/components/schemas/gitpod.v1.ValidationCheck'
title: checks
type: array
valid:
description: valid is true when all checks pass (convenience field).
title: valid
type: boolean
title: ValidateIntegrationResponse
type: object
gitpod.v1.UpdateIntegrationRequest:
additionalProperties: false
properties:
auth:
$ref: '#/components/schemas/gitpod.v1.IntegrationAuthentication'
description: auth defines which authentication methods are enabled for this integration
nullable: true
title: auth
capabilities:
$ref: '#/components/schemas/gitpod.v1.IntegrationCapabilities'
description: capabilities defines which capabilities are enabled for this integration
nullable: true
title: capabilities
enabled:
description: enabled indicates if this integration is enabled
nullable: true
title: enabled
type: boolean
host:
description: host is the hostname for this integration (e.g., "linear.app") - optional, inherits from definition
nullable: true
title: host
type: string
id:
format: uuid
title: id
type: string
title: UpdateIntegrationRequest
type: object
gitpod.v1.DeleteIntegrationRequest:
additionalProperties: false
properties:
id:
format: uuid
title: id
type: string
title: DeleteIntegrationRequest
type: object
gitpod.v1.IntegrationDefinition:
additionalProperties: false
description: "IntegrationDefinition defines a service that can be integrated with\n (e.g. Linear, GitHub, etc.)"
properties:
auth:
$ref: '#/components/schemas/gitpod.v1.IntegrationAuthentication'
description: auth defines the authentication requirements for this integration
title: auth
capabilities:
$ref: '#/components/schemas/gitpod.v1.IntegrationCapabilities'
description: capabilities defines what this integration can do
title: capabilities
description:
description: description provides a human-readable description of the integration
title: description
type: string
experimental:
description: experimental indicates if this integration is experimental and requires feature flag
title: experimental
type: boolean
host:
description: host is the hostname for this integration (e.g., "linear.app")
title: host
type: string
iconUrl:
description: icon_url is the URL for this integration's icon
title: icon_url
type: string
id:
description: id is the unique identifier for this integration definition
title: id
type: string
name:
description: name is the human-readable name for this integration type
title: name
type: string
required:
- id
- name
title: IntegrationDefinition
type: object
gitpod.v1.UpdateIntegrationDefinitionRequest:
additionalProperties: false
properties:
auth:
$ref: '#/components/schemas/gitpod.v1.IntegrationAuthentication'
description: auth defines the authentication requirements for this integration
nullable: true
title: auth
capabilities:
$ref: '#/components/schemas/gitpod.v1.IntegrationCapabilities'
description: capabilities defines what this integration can do
nullable: true
title: capabilities
description:
description: description provides a human-readable description of the integration
nullable: true
title: description
type: string
experimental:
description: experimental indicates if this integration is experimental and requires feature flag
nullable: true
title: experimental
type: boolean
host:
description: host is the hostname for this integration (e.g., "linear.app")
nullable: true
title: host
type: string
iconUrl:
description: icon_url is the URL for this integration's icon
nullable: true
title: icon_url
type: string
id:
minLength: 1
title: id
type: string
name:
description: name is the human-readable name for this integration type
nullable: true
title: name
type: string
title: UpdateIntegrationDefinitionRequest
type: object
gitpod.v1.CreateIntegrationDefinitionRequest:
additionalProperties: false
properties:
auth:
$ref: '#/components/schemas/gitpod.v1.IntegrationAuthentication'
description: auth defines the authentication requirements for this integration
title: auth
capabilities:
$ref: '#/components/schemas/gitpod.v1.IntegrationCapabilities'
description: capabilities defines what this integration can do
title: capabilities
description:
description: description provides a human-readable description of the integration
title: description
type: string
experimental:
description: experimental indicates if this integration is experimental and requires feature flag
title: experimental
type: boolean
host:
description: host is the hostname for this integration (e.g., "linear.app")
title: host
type: string
iconUrl:
description: icon_url is the URL for this integration's icon
title: icon_url
type: string
name:
description: name is the human-readable name for this integration type
minLength: 1
title: name
type: string
title: CreateIntegrationDefinitionRequest
type: object
gitpod.v1.IntegrationLoginCapability:
additionalProperties: false
description: IntegrationLoginCapability defines login/authentication capability Additional login configuration can be added here
title: IntegrationLoginCapability
type: object
gitpod.v1.IntegrationSourceCodeAccessCapability:
additionalProperties: false
description: IntegrationSourceCodeAccessCapability defines source code access capability Additional source code access configuration can be added here
title: IntegrationSourceCodeAccessCapability
type: object
gitpod.v1.CreateIntegrationResponse:
additionalProperties: false
properties:
integration:
$ref: '#/components/schemas/gitpod.v1.Integration'
title: integration
required:
- integration
title: CreateIntegrationResponse
type: object
gitpod.v1.IntegrationAgentClientCapability:
additionalProperties: false
description: "IntegrationAgentClientCapability indicates the integration supports agent client functionality.\n The webhook signing secret is stored in IntegrationProprietaryAppConfig.webhook_secret. Empty - presence of this capability indicates agent client support"
title: IntegrationAgentClientCapability
type: object
gitpod.v1.PaginationResponse:
additionalProperties: false
properties:
nextToken:
description: "Token passed for retrieving the next set of results. Empty if there are no\n more results"
title: next_token
type: string
title: PaginationResponse
type: object
gitpod.v1.UpdateIntegrationResponse:
additionalProperties: false
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gitpod/refs/heads/main/openapi/gitpod-gitpod-v1-integrationservice-api-openapi.yml