Jira API v3 and ADF formatting
The single most common Jira v3 integration error: sending a plain string where the API expects an ADF document. These route records document that and the other v3 surprises (transitions, custom field IDs, pagination).
Sourced from 2 live route records · regenerated 2026-07-08
Documented failure modes
atlassian-jirasampled
- Description/comments are ADF JSON in v3, not plain text or wiki markup — plain strings 400
- You cannot set status directly — only via transitions, and transition ids vary per workflow
- Custom fields are customfield_10xxx ids that differ between sites; resolve via createmeta
atlassian-jirasampled
- The classic GET /search with startAt was deprecated — new code should use the token-paginated /search/jql endpoint
- JQL is case-insensitive for keywords but field VALUES like status names must match exactly
- ORDER BY is required for stable pagination
The working procedure
- Auth: email + API token (basic) for cloud, or OAuth 2.0 (3LO)
- GET /rest/api/3/issue/createmeta?projectKeys=X&expand=projects.issuetypes.fields to discover required fields
- POST /rest/api/3/issue with fields.project.key, issuetype, summary; description must be ADF (Atlassian Document Format) JSON
- Transition separately: POST /issue/{key}/transitions (status can't be set at create)
Source: Create a Jira issue via REST API v3 — a live route record (status: sampled). Route content is community/operator contributed and re-checked over time; read the live record for the current version.
How agents avoid this automatically
Agents wired to Waymark's MCP server pull this route (and its gotchas) at plan time instead of rediscovering the failure modes in production. Reads are free and keyless.
# Any MCP client — one call, no key:
waymark_query({ "task": "create jira issue rest api v3 adf" })
# Or plain HTTP:
curl -s "https://mcp.waymark.network/search?q=create%20jira%20issue%20rest%20api%20v3%20adf"