---
title: "Search plugin integration connections"
method: POST
path: "/plugin-integrations/{integrationId}/connections/search"
tags: ["plugin-integration-connections"]
---

# Search plugin integration connections

`POST /plugin-integrations/{integrationId}/connections/search`

Performs a filtered search over plugin integration connections using a POST request.
This endpoint supports the same filtering capabilities as `GET /v2/plugin-integrations/{integrationId}/connections`,
but accepts filters in the request body instead of query parameters.
It's useful when filtering by a long list of entity IDs or when URL length limits become a problem.

## Path parameters

- `integrationId` string, uuid, required

## Query parameters

- `pageCursor` string

## Request body

- object
  - `data` object
    - `filter` ConnectionsSearchFilter — Filter criteria for searching plugin integration connections.
      - `state` ConnectionStateName[] — Filter by connection state.
      - `entityId` string[] — Filter by entity IDs.

## Response `200`

A paginated list of plugin integration connections

- object
  - `data` PluginIntegrationConnection[], required
    - `id` string, uuid, required — The Productboard entity ID this connection belongs to.
    - `type` 'pluginIntegrationConnection', required — Resource type identifier.
    - `fields` PluginIntegrationConnectionFields, required — Domain attributes of a plugin integration connection.
      - `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.
    - `links` PluginIntegrationConnectionLinks, required — Links for this connection resource.
      - `self` string, uri, required — URL to retrieve this connection.
  - `links` ListLinks, required
    - `next` string, nullable, required

## 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)