Jira Cloud vs Server API differences (rest/api/2 vs 3) in CI

By Daniel Zoghalchali·Latchkey

Jira Cloud and Server/Data Center expose different REST APIs. Cloud offers /rest/api/3 (with Atlassian Document Format for text bodies), while Server/Data Center uses /rest/api/2. Calling the wrong one or the wrong body shape fails.

What this error means

A comment or description POST fails with 400 about the body shape, or a /rest/api/3 path 404s on a Server instance, depending on which platform the CI target is.

HTTP/1.1 400 Bad Request
{"errorMessages":["Operation value must be an Atlassian Document (see the Atlassian Document Format)"],
 "errors":{}}

Common causes

Wrong API version for the platform

Server/Data Center does not serve /rest/api/3. Cloud automations pointed at Server (or the reverse) hit missing paths or unsupported bodies.

Plain string body sent where ADF is required

On Cloud v3, comment and description bodies must be Atlassian Document Format objects, not plain strings, so a string body is rejected.

How to fix it

Use the API version that matches the platform

1. For Jira Cloud use /rest/api/3 and send text as ADF documents.
2. For Server/Data Center use /rest/api/2 and send text as a string.
3. Detect the platform once and branch the base path accordingly.

# Jira Cloud (v3) comment body must be ADF
-d '{"body":{"type":"doc","version":1,
  "content":[{"type":"paragraph","content":[{"type":"text","text":"Deployed"}]}]}}'

Send a plain string on Server v2

On Server/Data Center the same comment is a plain string, which ADF-shaped bodies would break.

# Jira Server (v2)
-d '{"body":"Deployed"}'

How to prevent it

• Pin the correct REST version for your platform and stick to it.
• Wrap text in ADF on Cloud v3; use plain strings on Server v2.
• Keep separate config for Cloud and Data Center targets.

Frequently asked questions

Related guides

References

• GitHub Actions documentation