Jira API Integration Research

Date: 2026-04-10 Product: Atlassian Jira (Cloud + Data Center) Purpose: Evaluate Jira's API capabilities for Orcha integration

1. Summary -- Capability Matrix

Overall assessment: Jira has a comprehensive, mature REST API with full read/write support for all Orcha integration needs. No vendor engagement required -- all capabilities are publicly documented and self-service.

2. API Landscape

API Layers

Authentication Methods

Rate Limits (Cloud)

Three independent systems enforced simultaneously:

Response: HTTP 429 with Retry-After header. Orcha should implement exponential backoff.

Key Documentation Links

• Platform REST API v3: developer.atlassian.com/cloud/jira/platform/rest/v3/intro/
• Jira Software REST API: developer.atlassian.com/cloud/jira/software/rest/
• OpenAPI spec: developer.atlassian.com/cloud/jira/platform/swagger-v3.v3.json
• OAuth 2.0 guide: developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/
• Rate limiting: developer.atlassian.com/cloud/jira/platform/rate-limiting/

3. Write Verification

Confidence: HIGH. Jira's REST API is comprehensively writable. Nearly every object supports full CRUD.

Confirmed Write Endpoints

Main gap: No native bulk-update endpoint. Bulk updates require iterating individual PUT calls.

4. iPaaS Findings

iPaaS Capability Matrix

*Celigo via Universal Connector (HTTP)

Ranking by Jira write breadth: Workato > Make.com > n8n > Celigo > Zapier

Key finding: No undocumented capabilities revealed by iPaaS connectors. All iPaaS write operations map to documented Jira REST API endpoints. The connectors simplify access (field mapping, upsert logic, pagination) but do not expose hidden APIs.

5. Alternative Channels

Webhook Details

• Events supported: issue_created, issue_updated, issue_deleted, comment_, worklog_, project_, sprint_, version_, attachment_, issuelink_, user_
• JQL filtering: Yes -- webhooks can be scoped to specific projects/issue types via JQL
• Field filtering: Yes -- fieldIdsFilter narrows to specific field changes (e.g., only status)
• Programmatic registration: Only via Connect/OAuth 2.0 apps (not Basic Auth)
• Manual registration: Customer's Jira admin creates at Settings > System > WebHooks
• Delivery: HTTPS POST, JSON payload, limited retries with backoff, no guaranteed ordering

6. Licensing & Access Requirements

Cost to Customer: $0 additional for API access

API access is included in all Jira Cloud plans, including Free. There are no separate API licenses, per-call charges, or transaction packages.

What the Customer Must Buy/Enable Before Integration Can Start

Customer Admin Setup Checklist

1. Log in to id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token", label it "Orcha Integration"
3. Copy the token and provide it to Orcha along with:
   • Jira domain (e.g., yourcompany.atlassian.net)
   • Email address associated with the token
4. Ensure the token user has appropriate project permissions (Browse, Create, Transition, Attach)
5. For initial setup (custom field creation): user needs Administer Jira global permission
6. (Optional) Configure webhook: Jira Admin > System > WebHooks > Create, point to Orcha endpoint
7. (Optional) If IP allowlisting is enabled (Premium/Enterprise): whitelist Orcha's IP range

Ongoing Costs

• None beyond existing Jira subscription. No per-call charges, no transaction packages.
• Rate limits are generous for typical integration patterns (~100 req/s burst, 65K-500K points/hr).

7. Orcha-Specific Deep Dive

Integration Capability Summary

Example: Full Invoice Lifecycle

1. SETUP (one-time)
   GET /rest/api/3/project/search          --> discover customer's projects
   GET /rest/api/3/field                    --> discover custom fields
   POST /rest/api/3/field                   --> create "Cost Center" select field (if needed)
   POST /rest/api/3/field/{id}/context/{ctx}/option --> populate cost center options

2. INVOICE INGESTION
   POST /rest/api/3/issue                   --> create issue with invoice metadata
   POST /rest/api/3/issue/{key}/attachments  --> attach invoice PDF
   POST /rest/api/3/issue/{key}/comment      --> add processing notes

3. APPROVAL FLOW
   GET /rest/api/3/issue/{key}/transitions   --> discover "Submit for Approval" transition ID
   POST /rest/api/3/issue/{key}/transitions   --> trigger transition to "Pending Approval"
   -- wait for approval in Jira --
   Webhook fires with status change to "Approved" or "Rejected"
   -- OR --
   GET /rest/api/3/search/jql?jql=project=AP AND status="Approved" AND updated>="-1h"

4. ONGOING SYNC
   JQL polling: status changed after "{last_sync}" AND project = AP
   -- OR --
   Webhook: jira:issue_updated with fieldIdsFilter=["status"]

Technical Considerations

• ADF (Atlassian Document Format): v3 API uses a JSON-based rich text format for descriptions and comments. Not HTML, not Markdown. Orcha must generate ADF or use v2 (which accepts plain text).
• Custom field IDs: Referenced as customfield_NNNNN -- IDs differ per Jira instance. Must discover via GET /field during setup and store the mapping.
• Transition IDs: Workflow-specific and instance-specific. Must be discovered dynamically via GET, never hardcoded.
• No bulk update: Individual PUT calls required for updating multiple issues.
• Cloud vs DC: v3 API is Cloud-only. Data Center customers use v2 with Basic Auth or PATs. Auth flow differs but endpoints are similar.

8. Recommended Path Forward

Architecture Decision

Recommended: Direct REST API Integration

Why: Jira's API is mature, well-documented, includes OpenAPI specs, and covers 100% of Orcha's needs. No iPaaS or middleware layer needed. API access is free on all plans with generous rate limits.

Phased Integration Plan

Phase 1 -- Read & Setup (Week 1-2)

• OAuth 2.0 or Basic Auth connection setup
• Read customer's projects, fields, issue types, users
• Build field mapping UI in Orcha admin
• Create custom fields if needed (cost center, invoice number, etc.)

Phase 2 -- Invoice Push (Week 2-3)

• Create issues from ingested invoices
• Attach invoice PDFs
• Add processing notes as comments
• Set custom field values (cost center, amount, due date)

Phase 3 -- Approval Workflow (Week 3-4)

• Discover and map workflow transitions
• Trigger transitions programmatically
• Set up webhook or polling for status change events
• Sync approval status back to Orcha

Phase 4 -- Ongoing Sync & Reconciliation (Week 4-5)

• JQL-based polling for status changes
• Webhook setup (manual or programmatic via OAuth)
• Error handling, retry logic, rate limit handling
• Reconciliation queries

9. Sources

Official Documentation

• Jira Cloud Platform REST API v3: developer.atlassian.com/cloud/jira/platform/rest/v3/intro/
• Jira Cloud Platform REST API v2: developer.atlassian.com/cloud/jira/platform/rest/v2/intro/
• Jira Software Cloud REST API: developer.atlassian.com/cloud/jira/software/rest/
• Jira Service Management REST API: developer.atlassian.com/cloud/jira/service-desk/rest/
• Jira Data Center REST API: developer.atlassian.com/server/jira/platform/rest/v10002/
• Basic Auth guide: developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/
• OAuth 2.0 (3LO): developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/
• Rate limiting: developer.atlassian.com/cloud/jira/platform/rate-limiting/
• OpenAPI spec: developer.atlassian.com/cloud/jira/platform/swagger-v3.v3.json
• Platform changelog: developer.atlassian.com/cloud/jira/platform/changelog/

iPaaS Connectors

• Zapier Jira app (triggers + actions listing)
• Make.com Jira modules (comprehensive connector with generic API call)
• Workato Jira connector (most enterprise-grade, supports bulk create)
• Celigo Jira connector (upsert capability, universal connector)
• n8n Jira node (open-source, comprehensive operations)

Postman Collections

• Official Atlassian Jira API collection: postman.com/postman/atlassian-jira-api/overview

Pricing

• Atlassian pricing page: atlassian.com/software/jira/pricing
• Atlassian Guard: atlassian.com/software/access/pricing