Skip to content

Integrations

This API lists your organization's PM and Git integrations. Git integration IDs are what the Git Repositories endpoints take, for example in the integration_ids filter. PM integration IDs are what the PM Configuration endpoints take.

List Integrations

Lists the organization's PM and Git integrations - live ones by default

For example, GET /api/v1/integrations?type=git lists only the Git integrations, GET /api/v1/integrations?type=pm lists only the PM integrations (Jira and Azure Boards), and GET /api/v1/integrations?provider=github,jira lists only the GitHub and Jira ones.

HTTP request

GET  https://public-api.linearb.io/api/v1/integrations

Query parameter

Parameter name Value Description
type string The integration type, pm or git. Omitted lists both
provider string Only these providers, comma-separated, e.g. github,jira
include_invalid boolean Also list deleted integrations
(Default: false)

Responses

200 - Successful Response

{
  "items": [
    {
      "id": 1001,
      "type": "pm",
      "provider": "jira",
      "name": "Jira",
      "state": "ok",
      "auth_type": "oauth2"
    },
    {
      "id": 1002,
      "type": "pm",
      "provider": "azure_boards",
      "name": "Azure Boards",
      "state": "failing",
      "auth_type": "token",
      "failing_reason": "PM integration failure. Review this integration in Settings > Project Management."
    },
    {
      "id": 34,
      "type": "git",
      "provider": "github",
      "name": "acme-corp",
      "state": "ok"
    }
  ]
}

Each item in items has these fields:

Field Type Description
id integer The integration id. PM integration ids are what the PM configuration endpoints take; Git integration ids are what the Git repository endpoints take
type string pm or git
provider string jira or azure_boards for PM; github, gitlab, bitbucket, bitbucket_server or azure_devops for Git
name string The integration display name
state string The integration state, e.g. ok, failing, in-progress
auth_type string How the integration is connected
failing_reason string Why the integration is failing, in the Health Center wording. Present only when it has one
deleted_at string When the integration was deleted. Present only under include_invalid=true

More about state and PM integrations:

  • state is ok, failing, insufficient-permission, in-progress, inactive, cleanup-requested, cleanup-in-progress or cleanup-failed. Every integration that is not deleted is listed and can be read.

  • An ok, failing or insufficient-permission PM integration can be changed with the PM Configuration endpoints. One that is still being connected (in-progress), inactive, or being removed (cleanup-*) is read-only: a write that names it returns 400 saying why.

400 - Bad Request

Returned, for example, when type is neither pm nor git, or when provider is unknown.

401 - Unauthorized

403 - Forbidden

404 - Not Found

405 - Method Not Allowed

409 - Conflict

422 - Validation Error

500 - Internal Server Error

504 - Gateway Timeout