Jira Cloud

What you need

• Your Jira Cloud site URL, such as https://acme.atlassian.net
• The project key tickets should be created in, such as ENG
• An issue type name that exists in that project, such as Task or Bug
• The Atlassian account email and an API token for that account

BugLoop authenticates with Basic auth over HTTPS using the email and API token, which is the documented mechanism for Jira Cloud REST APIs. The token is encrypted with AES-256-GCM before storage and is not readable through the data API.

Verify before you rely on it

Test connection performs a real authenticated read of the Jira project and reports its name back. That single check confirms three things at once: the credential works, the site URL is right, and the project key exists.

Formatting

Jira Cloud’s v3 API represents rich text as Atlassian Document Format — a structured JSON tree — rather than Markdown. Sending Markdown does not fail loudly; it renders as literal asterisks and hashes, which is worse than an error because only a human reading the ticket notices.

BugLoop converts each report into ADF: headings for each section, bulleted lists for context and custom fields, bold labels. Anything unrecognized degrades to a plain paragraph, so a ticket is never lost to a formatting edge case.

{
  "fields": {
    "project":   { "key": "ENG" },
    "summary":   "[Bug] Checkout button does nothing on Safari",
    "issuetype": { "name": "Bug" },
    "labels":    ["bugloop", "website-feedback"],
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        { "type": "paragraph", "content": [
          { "type": "text", "text": "Clicking Pay has no effect." } ] },
        { "type": "heading", "attrs": { "level": 3 }, "content": [
          { "type": "text", "text": "Steps to reproduce" } ] }
      ]
    }
  }
}

The gotcha worth knowing

The most common failure is not authentication — it is an issue type name that does not exist in the target project, usually because an administrator renamed it. Use the renamed value exactly. Test connection surfaces a bad project key immediately, rather than leaving you to discover it at 2am.

Reference

Endpoint: POST {siteUrl}/rest/api/3/issue. Documented at developer.atlassian.com, with authentication described at basic-auth-for-rest-apis.