# Jira

> Source: https://docs.clonepartner.com/connectors/jira/

<!-- sources: src/connectors/jira.ts, references/envoy/connectors.md -->

# Jira

The `jira` connector calls the Jira Cloud REST API with Basic auth, automatic pagination across Jira's three paging styles, rate limiting, and retries.

## When to use it

Use `jira` to export issues, comments, worklogs, and attachments from a Jira Cloud site, or to create and update records during a migration. Methods take raw API paths, so any REST v2/v3 endpoint is reachable.

## Configuration

| Key | Type | Required | Default | Description |
|---|---|---|---|---|
| `base_url` | string | Yes | — | Jira site URL (e.g. `https://your-domain.atlassian.net`) |
| `email` | string | Yes | — | Atlassian account email for Basic auth |
| `api_token` | string | Yes | — | Atlassian API token (stored as a secret) |
| `rate_limit` | number | No | 10 | Max requests per second |

## Methods

| Method | Arguments | Returns | Behavior |
|---|---|---|---|
| `find` | `resource` (required), `query`, `items_key`, `page_size`, `paginate` | array | Streams records page by page from a collection endpoint, auto-paginating to the end |
| `find_one` | `resource` (required), `id` (required), `query` | object | Fetches a single record by ID or key |
| `create` | `resource` (required), `data` (required) | object | Creates a record (POST) |
| `update` | `resource` (required), `id` (required), `data` (required) | object | Updates a record by ID or key (PUT) |
| `delete` | `resource` (required), `id` (required) | void | Deletes a record by ID or key |
| `execute` | `path` (required), `method` (required), `data`, `query`, `headers` | object | Raw HTTP request for endpoints not covered by the helpers |
| `download` | `url` (required), `filename`, `content_type` | object | Downloads a binary attachment (pass the attachment object's `content` URL) and returns it base64-encoded; cross-origin redirects to signed media URLs are followed |

### Pagination

`find` handles Jira's paging styles automatically:

- token paging (`nextPageToken` + `isLast`, e.g. `rest/api/3/search/jql`);
- offset paging (`startAt` + `maxResults` + `total`);
- `Link` header paging with `rel="next"`.

The record array inside each response is located by `items_key`, auto-detected from the candidates `issues`, `values`, `results`, `comments`, and `worklogs` when omitted. Bare-array endpoints are returned as-is unless `paginate: offset` is set, which pages via `startAt`/`maxResults` until a partial page is returned (e.g. `rest/api/3/users/search`). `page_size` defaults to 100.

## Example

```yaml
name: export_project_issues
connectors:
  source:
    type: jira
steps:
  - name: read_issues
    type: call_method
    config: |
      {
        "connector": "source",
        "method": "find",
        "args": {
          "resource": "rest/api/3/search/jql",
          "query": { "jql": "project = ENG ORDER BY created ASC" }
        }
      }
```

The matching `connectors.yaml` entry for CLI runs:

```yaml
source:
  type: jira
  config:
    base_url: https://your-domain.atlassian.net
    email: integration@example.com
    api_token: ${JIRA_API_TOKEN}
```

## Behavior notes

- Requests are throttled to `rate_limit` per second with a token bucket. `429` responses honor the `Retry-After` header and `5xx` responses use exponential backoff, up to 5 retries; network errors also retry.
- `find` yields each record as it is parsed, so downstream steps process large exports with backpressure.
- `download` returns the file content base64-encoded together with filename and content type, ready to hand to another connector's upload method or to [transfer_file](/reference/steps/transfer-file/).

## Related

- [Connectors overview](/connectors/) — all compiled connector types
- [Freshdesk](/connectors/freshdesk/) — a similar REST connector with the same method shape
- [Reading and writing data](/building/reading-and-writing-data/) — calling connector methods from steps