---
title: "ValidateIntegration"
method: POST
path: "/gitpod.v1.IntegrationService/ValidateIntegration"
tags: ["gitpod.v1.IntegrationService"]
---

# ValidateIntegration

`POST /gitpod.v1.IntegrationService/ValidateIntegration`

Validates an integration's configuration and connectivity.

 Runs a set of checks (e.g. app token validity) and returns results for each.
 All checks are always returned; failing checks include a message and an optional action_hint.

## Request body

- GitpodV1ValidateIntegrationRequest
  - `integrationId` string

## Response `200`

Success

- GitpodV1ValidateIntegrationResponse
  - `checks` GitpodV1ValidationCheck[] — checks contains the result of every check performed. Passing checks have empty message and action_hint.
    - `actionHint` string — Machine-readable hint the frontend uses to resolve the issue (e.g. "app_installation_oauth"). Empty when the check passes or no automated fix is available.
    - `check` 'CHECK_UNSPECIFIED' | 'CHECK_APP_TOKEN' | 'CHECK_APP_INSTALLATION'
    - `documentationUrl` string — URL to documentation explaining this check failure and resolution steps. Empty when the check passes or no docs exist for this check.
    - `message` string — Human-readable description of the problem. Empty when the check passes.
  - `valid` boolean — valid is true when all checks pass (convenience field).

## Other responses

- `default` — Error

## Changes

> 18 revisions in range; 1 could not be searched.

- **2026-04-02** `dabc0ff98cd7` — 1 warning
  - added the new `CHECK_APP_INSTALLATION` enum value to the `checks/items/check` response property for the response status `200`
- **2026-02-18** `1923b5d38655` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/gitpod-io/apis/gitpod-v1/changes/gitpod.v1.IntegrationService/ValidateIntegration/post.md)

---

[API](https://skmtc.dev/gitpod-io/apis/gitpod-v1.md) · [All operations](https://skmtc.dev/gitpod-io/apis/gitpod-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gitpod-io/gitpod-v1/revisions/44d50c2ac284/schema)