# Jira API

Source: https://userguide.qualytics.io/settings/integrations/ticketing/jira/api/

Programmatic management of the **Jira integration** itself: connecting it, reading it back, changing its settings, and disconnecting it. Requests share the same base URL and Bearer token authentication as the rest of the platform API.

- **Base URL.** Your deployment's platform host (for example, `https://<your-tenant>.qualytics.io/api`).
- **Auth.** Bearer token in the `Authorization` header. See [Access Tokens](https://userguide.qualytics.io/settings/access-tokens/getting-started/) to create one.
- **Content type.** `application/json` on every request that carries a body.

> **Note: Permissions**
>
> Every endpoint on this page requires the **Manager** role. See [Permissions](https://userguide.qualytics.io/settings/integrations/ticketing/jira/deep-dive/permissions/).

> **Tip: Complete API Reference**
>
> The endpoints below are illustrative. For the full request and response schemas, live examples, and every field that each endpoint accepts, see the interactive API reference at [demo.qualytics.io/api/docs](https://demo.qualytics.io/api/docs).

> **Info: Looking for tickets and links?**
>
> Creating a ticket for an anomaly, searching tickets, and managing the links between anomalies and issues are anomaly operations, not integration ones. They live on the [Anomalies API](https://userguide.qualytics.io/anomalies/api/#search-tickets) page.

## Integration Endpoints

| Operation | Method | Endpoint | Description |
| --- | --- | --- | --- |
| Create Integration | POST | `/api/integrations` | Connect Jira. The credentials are validated against the instance before the integration is stored. |
| List Integrations | GET | `/api/integrations` | Return every connected integration, ticketing included. |
| Get Integration | GET | `/api/integrations/{id}` | Return one integration. Credentials are never returned in plain text. |
| Update Integration | PUT | `/api/integrations/{id}` | Change the URL, the credentials, the allowed projects, or the sync settings. |
| Get Integration History | GET | `/api/integrations/{id}/history` | Return the change log of the integration, one entry per saved version, with the user who made each change. |
| Disconnect Integration | DELETE | `/api/integrations/{id}` | Remove the integration and every anomaly-ticket link with it. The issues in Jira are untouched. |

## Connection Form Endpoints

These are what the settings modal calls while you fill it in. The `POST` variants take the credentials being typed, so they work before anything is saved, while the `GET` variants read through a saved integration.

| Operation | Method | Endpoint | Description |
| --- | --- | --- | --- |
| Get Integration Specifications | GET | `/api/integrations-specifications` | Return the field specification each integration type's form is built from. |
| List Projects (unsaved) | POST | `/api/integrations/ticketing/projects` | List the projects reachable with the credentials in the request body. |
| List Projects (saved) | GET | `/api/integrations/{id}/ticketing/projects` | List the projects reachable with a saved integration's credentials. |
| List Ticket Statuses (unsaved) | POST | `/api/integrations/ticketing/statuses` | List the ticket statuses reachable with the credentials in the request body, used to build the status mapping. |
| List Ticket Statuses (saved) | GET | `/api/integrations/{id}/ticketing/statuses` | The same list, through a saved integration. |
| List Issue Types (unsaved) | POST | `/api/integrations/ticketing/projects/{project_key}/issue-types` | List the issue types that can be created in one project, with the credentials in the request body. Add `?integration_id={id}` to use a saved integration's instance URL and credentials instead of the ones in the body. |
| List Issue Types (saved) | GET | `/api/integrations/{id}/ticketing/projects/{project_key}/issue-types` | The same list, through a saved integration. |
| Get Ticketing Webhook | GET | `/api/integrations/ticketing/webhook` | Return the webhook URL to register in Jira so issue changes reach Qualytics immediately. The secret is minted on the first call. |

## Request Fields

The create and update bodies share the same shape. Only `type` is create-only.

> **Warning: parameters is replaced, not merged**
>
> An update stores the `parameters` object exactly as sent, so any key you leave out is dropped. Send the whole object, including `projects` and `default_project_key`, even when you are only changing a sync setting. Omitting `parameters` entirely leaves the stored one untouched.

The credentials are only re-tested against Jira when the request changes `api_url` or sends a token, so a request that changes projects or sync settings alone is saved without a connection test. The same values are described as they appear in the interface on [Add Jira Connection](https://userguide.qualytics.io/settings/integrations/ticketing/jira/how-tos/connection/add-connection/#fields).

| Field | Type | Description |
| --- | --- | --- |
| `type` | `string` | `jira`. Required on create, and cannot be changed afterwards. |
| `api_url` | `string` | The Jira instance URL. A trailing slash is stripped. |
| `api_access_token` | `string` | The credentials, as `email:api_token`. Stored encrypted and never returned. |
| `parameters.projects` | `array` | The projects Qualytics may create issues in, each `{ "id": ..., "key": ..., "name": ..., "issue_type": ... }`. At least one is required. |
| `parameters.projects[].issue_type` | `string` | Optional. The issue type created in that project, by name, exactly as the issue-type endpoints return it. Leave it out to create `Task` issues. An empty string is refused. |
| `parameters.default_project_key` | `string` | The project used when a caller names none. It has to be one of `parameters.projects`. |
| `parameters.post_updates` | `bool` | Two-way sync. Absent means on. When false the integration is read only and nothing is written to Jira. |
| `parameters.sync_statuses` | `bool` | Whether anomaly and issue statuses move together. Defaults to off. |
| `parameters.status_mapping` | `object` | Anomaly status to ticket status, for example `{"Active": "To Do", "Resolved": "Done"}`. A `null` value leaves that anomaly status unmapped. Required to be non-empty when `sync_statuses` is on. |

## Sample Requests

> **Example: Connect Jira**
>
> ```bash
> curl -X POST "https://<your-tenant>.qualytics.io/api/integrations" \
>   -H "Authorization: Bearer $QUALYTICS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "type": "jira",
>     "api_url": "https://your-domain.atlassian.net",
>     "api_access_token": "user@example.com:your_api_token",
>     "parameters": {
>       "projects": [{ "id": "10001", "key": "DATAQ", "name": "Data Quality" }],
>       "default_project_key": "DATAQ"
>     }
>   }'
> ```
>
> Returns the stored integration. The credentials are not echoed back.

> **Example: List the issue types of a project**
>
> ```bash
> curl -X GET "https://<your-tenant>.qualytics.io/api/integrations/2/ticketing/projects/HELP/issue-types" \
>   -H "Authorization: Bearer $QUALYTICS_TOKEN"
> ```
>
> ```json
> [
>   { "id": "10008", "name": "Service request", "description": "Request help from the service desk." },
>   { "id": "10009", "name": "Incident", "description": "Report a system outage or problem." }
> ]
> ```
>
> Sub-task types are left out. Some service projects list their built-in types with a `[System]` prefix, and that prefix is part of the name. A project the account cannot create issues in returns `400` naming the project. On a Jira Service Management project that is usually a missing agent seat. See [Jira Service Management Projects](https://userguide.qualytics.io/settings/integrations/ticketing/jira/deep-dive/requirements/#jira-service-management-projects).

> **Example: Create service requests in a service project**
>
> ```bash
> curl -X PUT "https://<your-tenant>.qualytics.io/api/integrations/2" \
>   -H "Authorization: Bearer $QUALYTICS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "parameters": {
>       "projects": [
>         { "id": "10001", "key": "DATAQ", "name": "Data Quality" },
>         { "id": "10002", "key": "HELP", "name": "IT Help Desk", "issue_type": "Service request" }
>       ],
>       "default_project_key": "DATAQ"
>     }
>   }'
> ```
>
> Tickets in `HELP` are created as service requests, and tickets in `DATAQ` stay `Task` issues because that project names no type.

> **Example: Turn on status sync with a mapping**
>
> ```bash
> curl -X PUT "https://<your-tenant>.qualytics.io/api/integrations/2" \
>   -H "Authorization: Bearer $QUALYTICS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "parameters": {
>       "projects": [{ "id": "10001", "key": "DATAQ", "name": "Data Quality" }],
>       "default_project_key": "DATAQ",
>       "sync_statuses": true,
>       "status_mapping": {
>         "Active": "To Do",
>         "Acknowledged": "In Progress",
>         "Resolved": "Done"
>       }
>     }
>   }'
> ```
>
> Turning `sync_statuses` on with nothing mapped is refused, so send the mapping in the same request.

> **Example: Make the integration read only**
>
> ```bash
> curl -X PUT "https://<your-tenant>.qualytics.io/api/integrations/2" \
>   -H "Authorization: Bearer $QUALYTICS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "parameters": {
>       "post_updates": false,
>       "projects": [{ "id": "10001", "key": "DATAQ", "name": "Data Quality" }],
>       "default_project_key": "DATAQ"
>     }
>   }'
> ```
>
> The projects are repeated because `parameters` is stored exactly as sent. Sending `post_updates` on its own would drop them, and the request is then refused with `422` because a Jira integration has to name at least one project. Read the integration first when you do not know what it currently holds.
>
> Reading issues back continues. To silence a single issue instead, use the ticket link endpoint on the [Anomalies API](https://userguide.qualytics.io/anomalies/api/#search-tickets).

> **Example: Read the webhook URL**
>
> ```bash
> curl -X GET "https://<your-tenant>.qualytics.io/api/integrations/ticketing/webhook" \
>   -H "Authorization: Bearer $QUALYTICS_TOKEN"
> ```
>
> Returns `{ "url": "...", "supported": true }`. The URL embeds a secret, so treat it as a credential. See [Register the Jira Webhook](https://userguide.qualytics.io/settings/integrations/ticketing/jira/how-tos/connection/register-webhook/).

> **Example: Disconnect Jira**
>
> ```bash
> curl -X DELETE "https://<your-tenant>.qualytics.io/api/integrations/2" \
>   -H "Authorization: Bearer $QUALYTICS_TOKEN"
> ```
>
> Removes the integration and every anomaly-ticket link. The issues stay in Jira.

*Last updated: October 27, 2026.*
