plugin-integration-connections
Update plugin integration connection state
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:
- User clicks push button → your endpoint receives an action notification
- Respond immediately with state: progress to show a loading indicator
- Process the action asynchronously
- Call this endpoint with the final state (connected or error)
put/plugin-integrations/{integrationId}/connections/{entityId}
Path parameters
integrationIdstring uuid required
Example:00000000-0000-0000-0000-000000000001
UUID of the plugin integration.
entityIdstring uuid required
Example:00000000-0000-0000-0000-000000000002
Entity identifier.
Request body
Example request
{
"data": {
"fields": {
"connection": {
"label": "Done",
"hoverLabel": "Issue 123",
"tooltip": "Issue 123 - Implement XYZ",
"color": "green",
"targetUrl": "https://example.com/issues/123"
}
}
}
}Response
Connection state set successfully
Example response
{
"data": {
"id": "00000000-0000-0000-0000-000000000002",
"links": {
"self": "https://api.productboard.com/v2/plugin-integrations/00000000-0000-0000-0000-000000000001/connections/00000000-0000-0000-0000-000000000002"
}
}
}