{"openapi":"3.1.1","info":{"title":"Jira Integrations","description":"Productboard API v2 for managing Jira integrations and their connections to Productboard entities. Use these endpoints to list and get Jira integrations, check their status, and browse entity-to-issue connections.","version":"2.0.0","contact":{"name":"Productboard Support","url":"https://support.productboard.com","email":"support@productboard.com"},"license":{"name":"Proprietary","url":"https://www.productboard.com/terms"}},"servers":[{"url":"https://api.productboard.com/v2","description":"Production server"}],"security":[{"BearerAuth":[]},{"OAuth2":["entities:read","write:entities","entities:delete"]}],"tags":[{"name":"jira-integrations","description":"Operations related to Jira integrations and their connections."}],"paths":{"/jira-integrations":{"get":{"summary":"List Jira integrations","description":"Returns detail of all Jira integrations.\n\nThis API is paginated using cursor-based pagination. The client should follow the `links.next` link in the response to fetch the next page.\n","operationId":"listJiraIntegrations","security":[{"BearerAuth":["jira-integrations:read"]}],"tags":["jira-integrations"],"parameters":[{"$ref":"#/components/parameters/PageCursor"}],"responses":{"200":{"$ref":"#/components/responses/JiraIntegrationListResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"408":{"$ref":"#/components/responses/RequestTimeoutResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}},"/jira-integrations/{integrationId}":{"get":{"summary":"Get Jira integration","description":"Returns detail of a specific Jira integration identified by its UUID. Use this endpoint to retrieve comprehensive information about a single integration including its name, status, creation timestamp, and related resource links.\n","operationId":"getJiraIntegration","security":[{"BearerAuth":["jira-integrations:read"]}],"tags":["jira-integrations"],"parameters":[{"$ref":"#/components/parameters/IntegrationId"}],"responses":{"200":{"$ref":"#/components/responses/JiraIntegrationResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"408":{"$ref":"#/components/responses/RequestTimeoutResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}},"/jira-integrations/{integrationId}/connections":{"get":{"summary":"List Jira integration connections","description":"Returns detail of all Productboard feature - Jira issue connections for given integration. It also allows to find a connection by Jira issue key or ID.\n\nThis API is paginated using cursor-based pagination. The client should follow the `links.next` link in the response to fetch the next page.\n","operationId":"listJiraIntegrationConnections","security":[{"BearerAuth":["jira-integrations:read"]}],"tags":["jira-integrations"],"parameters":[{"$ref":"#/components/parameters/IntegrationId"},{"$ref":"#/components/parameters/PageCursor"},{"name":"issueKey","in":"query","required":false,"description":"If specified, the resource returns only connection for given Jira issue (if any).","schema":{"type":"string"}},{"name":"issueId","in":"query","required":false,"description":"If specified, the resource returns only connection for given Jira issue (if any).","schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/JiraIntegrationConnectionListResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"408":{"$ref":"#/components/responses/RequestTimeoutResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}},"/jira-integrations/{integrationId}/connections/{entityId}":{"get":{"summary":"Get Jira integration connection","description":"Returns detail of a specific Productboard feature - Jira issue connection identified by integration UUID and entity UUID. Use this endpoint to retrieve information about the link between a Productboard feature and its corresponding Jira issue.\n","operationId":"getJiraIntegrationConnection","security":[{"BearerAuth":["jira-integrations:read"]}],"tags":["jira-integrations"],"parameters":[{"$ref":"#/components/parameters/IntegrationId"},{"$ref":"#/components/parameters/EntityId"}],"responses":{"200":{"$ref":"#/components/responses/JiraIntegrationConnectionResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"408":{"$ref":"#/components/responses/RequestTimeoutResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}}},"components":{"parameters":{"EntityId":{"name":"entityId","in":"path","required":true,"description":"Entity identifier.","schema":{"type":"string","format":"uuid","example":"00000000-0000-0000-0000-000000000000"}},"IntegrationId":{"name":"integrationId","in":"path","required":true,"description":"Jira integration identifier.","schema":{"type":"string","format":"uuid","example":"00000000-0000-0000-0000-000000000000"}},"PageCursor":{"name":"pageCursor","in":"query","required":false,"description":"Cursor for pagination. Use the value from `links.next` to fetch the next page.","schema":{"type":"string"}}},"schemas":{"JiraIntegration":{"type":"object","description":"Jira integration data.","required":["id","type","createdAt","fields","links"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true,"description":"Unique identifier for the Jira integration.","example":"00000000-0000-0000-0000-000000000000"},"type":{"type":"string","const":"jiraIntegration","description":"Resource type identifier.","example":"jiraIntegration"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the integration was created.","example":"2020-12-30T06:38:36.406002Z"},"fields":{"$ref":"#/components/schemas/JiraIntegrationFields"},"links":{"$ref":"#/components/schemas/JiraIntegrationLinks"}}},"JiraIntegrationFields":{"type":"object","required":["name","integrationStatus"],"properties":{"name":{"type":"string","description":"Name of the integration.","minLength":1,"maxLength":255,"example":"My great integration"},"integrationStatus":{"type":"string","description":"Status of the integration column in the Productboard UI.","enum":["enabled","disabled"],"example":"enabled"}}},"JiraIntegrationLinks":{"type":"object","required":["self","connections","html"],"properties":{"self":{"type":"string","format":"uri","description":"Link to the Jira integration.","example":"https://api.productboard.com/v2/jira-integrations/00000000-0000-0000-0000-000000000000"},"connections":{"type":"string","format":"uri","description":"Link to the list of Jira integration connections.","example":"https://api.productboard.com/v2/jira-integrations/00000000-0000-0000-0000-000000000000/connections"},"html":{"type":"string","format":"uri","description":"Link to the Jira integration settings page in the Productboard UI.","example":"https://example.productboard.com/settings/integrations/jira/00000000-0000-0000-0000-000000000000"}}},"JiraIntegrationConnection":{"type":"object","description":"Jira integration connection data.","required":["id","type","fields","links"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true,"description":"Feature identifier (serves as connection identifier).","example":"00000000-0000-0000-0000-000000000000"},"type":{"type":"string","const":"jiraIntegrationConnection","description":"Resource type identifier.","example":"jiraIntegrationConnection"},"fields":{"$ref":"#/components/schemas/JiraIntegrationConnectionFields"},"links":{"$ref":"#/components/schemas/JiraIntegrationConnectionLinks"}}},"JiraIntegrationConnectionFields":{"type":"object","description":"Represents a link between a Productboard feature and a Jira issue.","required":["issueKey","issueId"],"properties":{"issueKey":{"type":"string","description":"Jira issue KEY.","example":"JIRA-123"},"issueId":{"type":"string","description":"Jira issue ID.","example":"123456"}}},"JiraIntegrationConnectionLinks":{"type":"object","required":["self"],"properties":{"self":{"type":"string","format":"uri","description":"Link to the connection.","example":"https://api.productboard.com/v2/jira-integrations/00000000-0000-0000-0000-000000000000/connections/00000000-0000-0000-0000-000000000000"}}},"JiraIntegrationListResponse":{"type":"object","description":"List of Jira integrations.","required":["data","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/JiraIntegration"}},"links":{"$ref":"#/components/schemas/ListLinks"}}},"JiraIntegrationResponse":{"type":"object","description":"Single Jira integration.","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/JiraIntegration"}}},"JiraIntegrationConnectionListResponse":{"type":"object","description":"List of Jira integration connections.","required":["data","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/JiraIntegrationConnection"}},"links":{"$ref":"#/components/schemas/ListLinks"}}},"JiraIntegrationConnectionResponse":{"type":"object","description":"Single Jira integration connection.","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/JiraIntegrationConnection"}}},"ListLinks":{"type":"object","required":["next"],"properties":{"next":{"type":["string","null"]}}},"ErrorSource":{"type":"object","description":"An object containing references to the source of the error. It helps with location of the problematic field or parameter.\n","properties":{"pointer":{"type":"string","description":"JSON Pointer [RFC6901] to the associated entity in the request document.\n","example":"/data/fields/status"},"parameter":{"type":"string","description":"Query parameter causing the error.\nUsed when the error is related to a query parameter rather than request body.\n","example":"pageCursor"}}},"Error":{"type":"object","description":"Individual error object containing the details and context.\n","required":["code","title","detail"],"properties":{"code":{"type":"string","description":"A unique, machine-readable and stable code that identifies this error.\nMust be consistent across all services and provide clear categorization.\nFormat: `category.subcategory.specificError`\n","examples":["auth.accessDenied","resource.notFound"]},"title":{"type":"string","description":"A short, human-readable summary of the problem that doesn't change\nfrom occurrence to occurrence of the problem. Should provide immediate\nunderstanding of the error type.\n","maxLength":255,"example":"Missing required field"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem.\nMay include suggestions for resolution but should not expose sensitive information.\n","maxLength":1000,"example":"Field 'status' is required."},"source":{"$ref":"#/components/schemas/ErrorSource"}}},"ErrorResponse":{"type":"object","description":"Standard error response structure.\n","required":["id","errors"],"properties":{"id":{"type":"string","description":"A unique identifier for this specific occurrence of the problem.\nIt carries unique request/response ID which allows client\nand server to reference the exact instance of the error\nin logs or support communication.\n"},"errors":{"type":"array","description":"Array of error objects, multiple errors can be returned.","items":{"$ref":"#/components/schemas/Error"},"minItems":1}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API token authentication. Use your API token as the value of the Authorization header"},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication. Use this for user-authorized access to Productboard API.","flows":{"authorizationCode":{"authorizationUrl":"https://app.productboard.com/oauth/authorize","tokenUrl":"https://app.productboard.com/oauth/token","scopes":{"entities:read":"Read access to entities (features, components, initiatives, etc.)","write:entities":"Write access to create and modify entities","entities:delete":"Delete entities"}}}}},"responses":{"JiraIntegrationListResponse":{"description":"A paginated list of Jira integrations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JiraIntegrationListResponse"},"example":{"data":[{"id":"a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d","type":"jiraIntegration","createdAt":"2024-01-15T10:30:00.000Z","fields":{"name":"My Jira Cloud Integration","integrationStatus":"enabled"},"links":{"self":"https://api.productboard.com/v2/jira-integrations/a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d","connections":"https://api.productboard.com/v2/jira-integrations/a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d/connections","html":"https://example.productboard.com/settings/integrations/jira/a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"}},{"id":"f6e5d4c3-b2a1-4c5d-8e9f-0a1b2c3d4e5f","type":"jiraIntegration","createdAt":"2024-02-20T14:45:30.000Z","fields":{"name":"Jira Server Integration","integrationStatus":"disabled"},"links":{"self":"https://api.productboard.com/v2/jira-integrations/f6e5d4c3-b2a1-4c5d-8e9f-0a1b2c3d4e5f","connections":"https://api.productboard.com/v2/jira-integrations/f6e5d4c3-b2a1-4c5d-8e9f-0a1b2c3d4e5f/connections","html":"https://example.productboard.com/settings/integrations/jira/f6e5d4c3-b2a1-4c5d-8e9f-0a1b2c3d4e5f"}}],"links":{"next":null}}}}},"JiraIntegrationResponse":{"description":"Jira integration details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JiraIntegrationResponse"},"example":{"data":{"id":"a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d","type":"jiraIntegration","createdAt":"2024-01-15T10:30:00.000Z","fields":{"name":"My Jira Cloud Integration","integrationStatus":"enabled"},"links":{"self":"https://api.productboard.com/v2/jira-integrations/a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d","connections":"https://api.productboard.com/v2/jira-integrations/a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d/connections","html":"https://example.productboard.com/settings/integrations/jira/a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"}}}}}},"JiraIntegrationConnectionListResponse":{"description":"A paginated list of Jira integration connections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JiraIntegrationConnectionListResponse"},"example":{"data":[{"id":"b2c3d4e5-f6a1-4b5c-9d0e-1f2a3b4c5d6e","type":"jiraIntegrationConnection","fields":{"issueKey":"PROJ-123","issueId":"10001"},"links":{"self":"https://api.productboard.com/v2/jira-integrations/a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d/connections/b2c3d4e5-f6a1-4b5c-9d0e-1f2a3b4c5d6e"}},{"id":"c3d4e5f6-a1b2-4c5d-0e1f-2a3b4c5d6e7f","type":"jiraIntegrationConnection","fields":{"issueKey":"PROJ-456","issueId":"10002"},"links":{"self":"https://api.productboard.com/v2/jira-integrations/a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d/connections/c3d4e5f6-a1b2-4c5d-0e1f-2a3b4c5d6e7f"}},{"id":"d4e5f6a1-b2c3-4d5e-1f2a-3b4c5d6e7f8a","type":"jiraIntegrationConnection","fields":{"issueKey":"PROJ-789","issueId":"10003"},"links":{"self":"https://api.productboard.com/v2/jira-integrations/a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d/connections/d4e5f6a1-b2c3-4d5e-1f2a-3b4c5d6e7f8a"}}],"links":{"next":"https://api.productboard.com/v2/jira-integrations/a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d/connections?pageCursor=MTAw"}}}}},"JiraIntegrationConnectionResponse":{"description":"Jira integration connection details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JiraIntegrationConnectionResponse"},"example":{"data":{"id":"b2c3d4e5-f6a1-4b5c-9d0e-1f2a3b4c5d6e","type":"jiraIntegrationConnection","fields":{"issueKey":"PROJ-123","issueId":"10001"},"links":{"self":"https://api.productboard.com/v2/jira-integrations/a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d/connections/b2c3d4e5-f6a1-4b5c-9d0e-1f2a3b4c5d6e"}}}}}},"BadRequestResponse":{"description":"Bad Request - Invalid input format or malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"schemaInvalid":{"summary":"Request does not satisfy schema","value":{"id":"req-1234567890","errors":[{"code":"request.invalid","title":"Request schema invalid","detail":"The request does not satisfy the required schema. Field 'type' is required but was not provided.","source":{"pointer":"/data/type"}}]}},"fieldInvalid":{"summary":"Invalid field value type","value":{"id":"req-1234567891","errors":[{"code":"request.invalid","title":"Request schema invalid","detail":"Field 'fields/name' must be a string with maximum length of 255 characters, but received a number.","source":{"pointer":"/data/fields/name"}}]}},"malformedJson":{"summary":"Malformed JSON syntax","value":{"id":"req-1234567892","errors":[{"code":"request.malformed","title":"Request malformed","detail":"The request body contains invalid JSON syntax. Expected ',' or '}' at line 5, column 12."}]}},"invalidContentType":{"summary":"Invalid content type","value":{"id":"req-1234567893","errors":[{"code":"request.malformed","title":"Request malformed","detail":"The Content-Type header must be 'application/json'. Received 'text/plain'."}]}}}}}},"UnauthorizedResponse":{"description":"Unauthorized - Missing or invalid authentication credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missingCredentials":{"summary":"Missing authentication credentials","value":{"id":"req-2234567890","errors":[{"code":"auth.invalid","title":"Invalid authentication","detail":"Authentication credentials are missing."}]}},"invalidToken":{"summary":"Invalid or expired token","value":{"id":"req-2234567891","errors":[{"code":"auth.invalid","title":"Invalid authentication","detail":"The provided authentication credentials are invalid or have expired. Please obtain new credentials and try again."}]}},"revokedCredentials":{"summary":"Revoked credentials","value":{"id":"req-2234567892","errors":[{"code":"auth.invalid","title":"Invalid authentication","detail":"The authentication credentials have been revoked. Please contact your workspace administrator."}]}}}}}},"ForbiddenResponse":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"permissionDenied":{"summary":"Permission denied for resource","value":{"id":"req-3234567890","errors":[{"code":"auth.accessDenied","title":"Access denied","detail":"You do not have permission to perform this operation on the specified resource. Contact your workspace administrator to request access."}]}},"insufficientScope":{"summary":"Insufficient OAuth scopes","value":{"id":"req-3234567891","errors":[{"code":"auth.accessDenied","title":"Access denied","detail":"Your authentication token lacks the required OAuth scopes to perform this operation. Please re-authenticate with the necessary scopes."}]}},"readOnlyRole":{"summary":"Read-only role restriction","value":{"id":"req-3234567892","errors":[{"code":"auth.accessDenied","title":"Access denied","detail":"Your user role does not permit this operation. Please contact your workspace administrator."}]}}}}}},"RequestTimeoutResponse":{"description":"Request Timeout - The server did not receive a complete request within the allowed time","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"requestTimeout":{"summary":"Request timeout","value":{"id":"req-5234567890","errors":[{"code":"request.timeout","title":"Request timeout","detail":"The request took too long to process and was terminated. Try simplifying your request or try again later."}]}}}}}},"TooManyRequestsResponse":{"description":"Too Many Requests - API rate limit exceeded, reduce request frequency and retry after the indicated time","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"rateLimitExceeded":{"summary":"Rate limit exceeded","value":{"id":"req-7234567890","errors":[{"code":"rate.limitExceeded","title":"Rate limit exceeded","detail":"You have exceeded the allowed number of API requests. Please wait before making additional requests."}]}}}}}},"InternalServerErrorResponse":{"description":"Internal Server Error - An unexpected error occurred on the server, please retry or contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"internalServerError":{"summary":"Unexpected server error","value":{"id":"req-8234567890","errors":[{"code":"internal.serverError","title":"Internal server error","detail":"An unexpected error occurred while processing your request. Please try again later. If the problem persists, contact support with the correlation ID."}]}}}}}},"NotFoundResponse":{"description":"Not Found - The requested resource does not exist or is not accessible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"resourceNotFoundById":{"summary":"Resource not found by ID","value":{"id":"req-4234567890","errors":[{"code":"resource.notFound","title":"Resource not found","detail":"The requested resource could not be found or you do not have permission to access it."}]}},"routeNotFound":{"summary":"API route not found","value":{"id":"req-4234567893","errors":[{"code":"route.notFound","title":"Route not found","detail":"The requested URL path does not match any defined API route. Please check the API documentation for valid endpoints."}]}}}}}}}},"x-readme":{"samples-languages":["shell","javascript","ruby"]}}