---
title: "Update plugin integration connection state"
method: PUT
path: "/plugin-integrations/{integrationId}/connections/{entityId}"
tags: ["plugin-integration-connections"]
---

# Update plugin integration connection state

`PUT /plugin-integrations/{integrationId}/connections/{entityId}`

Creates or replaces the connection state for a specific entity within a plugin
integration. This is an **upsert** — if no connection exists it is created; if one
exists it is replaced.

**Connection states:**

| State | Effect |
|---|---|
| `connected` | Entity is linked; push button shows connection details |
| `error` | Connection failed; push button shows error state |
| `progress` | Processing asynchronously; push button shows loading indicator |
| `initial` | Equivalent to deleting the connection; push button resets |

**Async processing flow:**
1. User clicks push button → your endpoint receives an action notification
2. Respond immediately with `state: progress` to show a loading indicator
3. Process the action asynchronously
4. Call this endpoint with the final state (`connected` or `error`)

## Path parameters

- `integrationId` string, uuid, required
- `entityId` string, uuid, required

## Request body

- object
  - `data` object, required
    - `fields` object, required
      - `connection` union, required — The state of a plugin integration connection. Determined by the `state` property. | State | Meaning | Push button appearance | |---|---|---| | `connected` | Entity linked to third-party entity | Shows `label`; click opens `targetUrl` | | `error` | Connection attempt failed | Shows error icon with `message` | | `progress` | Establishing asynchronously | Shows loading indicator | | `initial` | No connection (default) | Shows integration's `initialState.label` |
        - ConnectedState — Represents a successfully established connection. The push button displays custom label, hover text, tooltip, color, and a link to the connected entity.
          - `state` 'connected', required — Connection state discriminator.
          - `label` string, required — Text on the push button when connected. Typically the entity's current status.
          - `hoverLabel` string, required — Text on the push button on hover (temporarily replaces `label`). Typically shows the linked entity's identifier.
          - `tooltip` string, required — Longer tooltip text shown on hover. Ideal for a detailed description of the linked entity.
          - `color` 'gray' | 'blue' | 'green' | 'yellow' | 'orange' | 'red' | 'purple', required — Background color of the push button.
          - `targetUrl` string, uri, required — URL that opens when the user clicks the connected push button. Should link to the connected entity in the third-party system.
        - ErrorState — Represents a failed connection attempt. The push button displays an error icon with the provided message.
          - `state` 'error', required — Connection state discriminator.
          - `message` string, required — Human-readable error message explaining why the connection could not be established. Shown in the error popup in the Productboard UI.
          - `debugDetail` string — Additional debugging information set by Productboard when a push fails on Productboard's side. **Not visible in the UI** — for developer use during integration development only. Never set by the partner.
        - ProgressState — Represents an in-progress connection attempt. The push button shows a loading indicator. Use when processing is asynchronous: respond with `progress` immediately from your action endpoint, then call Configure Connection with the final state once done.
          - `state` 'progress', required — Connection state discriminator.
        - InitialConnectionState — Represents the default, unconnected state. The push button shows the integration's `initialState.label`. Setting a connection to `initial` via Configure Connection is equivalent to deleting it.
          - `state` 'initial', required — Connection state discriminator.

## Response `200`

Connection state set successfully

- object
  - `data` PluginIntegrationConnectionReference, required — Minimal reference to a plugin integration connection, returned in mutation responses.
    - `id` string, uuid, required — The Productboard entity ID this connection belongs to.
    - `links` PluginIntegrationConnectionLinks, required — Links for this connection resource.
      - `self` string, uri, required — URL to retrieve this connection.

## Other responses

- `400` — Bad Request - Invalid input format or malformed request
- `401` — Unauthorized - Missing or invalid authentication credentials
- `403` — Forbidden - Insufficient permissions
- `404` — Not Found - The requested resource does not exist or is not accessible
- `408` — Request Timeout - The server did not receive a complete request within the allowed time
- `422` — Unprocessable Entity - Validation failed (e.g., missing required fields, unknown fields)
- `429` — Too Many Requests - API rate limit exceeded, reduce request frequency and retry after the indicated time
- `500` — Internal Server Error - An unexpected error occurred on the server, please retry or contact support

---

[API](https://skmtc.dev/productboard/apis/notes.md) · [All operations](https://skmtc.dev/productboard/apis/notes/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/productboard/notes/revisions/b4004749b60f/schema)