Jira Create Issue API: A Step-by-Step Guide for Developers
Need to create Jira tickets faster? Follow this jira create issue api guide to set up requests, authentication, and fields. Read now.
Creating Jira issues by hand works until your team needs to file dozens of tickets or connect Jira to another service. Then repetitive clicks slow development, and small mistakes can send issues to the wrong project or leave required fields blank.
The Jira Create Issue API lets you create a ticket with an HTTP request. But here's the truth: a successful request depends on more than the endpoint. Authentication, project permissions, issue type, and field formats all need to match your Jira configuration.
This guide walks you through a working Jira Cloud example, explains how to handle common errors, and shows how to verify the new issue. You’ll also see what changes for Jira Data Center and how to keep API credentials safe. By the end, you can create a ticket from a script or service and understand what to check when the request fails.
Create a Jira issue with the REST API
For Jira Cloud, send a POST request to /rest/api/3/issue with authentication and a JSON body. Include the project, issue type, and summary; add any other fields your Jira configuration requires.

1. Confirm your Jira project and issue type
Find the project key, such as ENG, and choose an issue type available in that project, such as Task or Bug. Jira administrators can make fields mandatory or restrict issue types, so the required values can differ across projects.
Check that the account making the request has permission to create issues in the target project. A valid token alone does not grant project access.
2. Create an API token and prepare authentication
For Jira Cloud basic authentication, use the account’s email address and an Atlassian API token. Do not use your normal account password. Store the token in a secret manager or environment variable, and avoid printing it in logs.
The example below expects JIRA_BASE_URL, JIRA_EMAIL, and JIRA_API_TOKEN to be set in your shell. Replace your-domain.atlassian.net with your Jira site address.
3. Send the create request
This minimal request creates a task with a summary. Add a description or other fields when your project requires them.
curl --request POST \
--url "https://your-domain.atlassian.net/rest/api/3/issue" \
--user "$JIRA_EMAIL:$JIRA_API_TOKEN" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
"fields": {
"project": {
"key": "ENG"
},
"issuetype": {
"name": "Task"
},
"summary": "Add retry handling to the payment service"
}
}'
The project key, issue type, and summary are examples. Use values that exist in your Jira site and match the project’s configuration.
4. Add a description when needed
Jira Cloud REST API v3 uses Atlassian Document Format (ADF) for descriptions. A plain text string may be rejected when sent as the description field. Use a structured value like this:
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Add retry handling and test the payment timeout path."
}
]
}
]
}
Place that object inside fields, alongside project, issuetype, and summary. If your project requires additional fields, include them in the same object using the field names or IDs Jira expects.
5. Check the response
A successful create request usually returns HTTP 201 Created. The response includes the new issue’s ID and key, such as ENG-42. Save the key if another step needs to link to or update the issue.
If you receive an error, inspect the status code and response body. Jira often identifies a missing field or invalid value in its error details.
Choose the right endpoint and request format
The API version depends on where Jira runs. Jira Cloud uses REST API v3 for this request. Jira Data Center commonly uses REST API v2, though the exact version and authentication method depend on the installed release and configuration.
For a Data Center instance, the endpoint commonly follows this pattern: https://jira.example.com/rest/api/2/issue. Check your administrator’s configuration before copying Cloud authentication examples, because authentication options can differ.
Request formatting matters, too. Cloud v3 expects ADF for rich-text fields such as descriptions. A simple summary remains a string, while fields such as labels or components have their own expected formats. Treat each field as a specific type rather than assuming every value is plain text.
Build a valid issue payload
Start with the smallest request that works in your project. Add fields one at a time, testing after each change; this makes validation errors easier to pinpoint.
| Field | Typical value | What to check |
project | {"key":"ENG"} | The project exists and the account can create issues there. |
issuetype | {"name":"Task"} | The type is enabled for the chosen project. |
summary | A short string | The value is present and clearly describes the work. |
description | An ADF object in Cloud v3 | The structure matches the REST API version. |
| Custom fields | Field-specific values | Required fields, IDs, allowed options, and value types. |
For example, if a project requires a priority, setting only the summary may return a validation error. Add the priority in the format accepted by that Jira field, then retry with a fresh request.
Handle errors and verify the new ticket
Here’s why: an HTTP status code often narrows the problem quickly. A 400 response usually points to invalid or missing fields. A 401 suggests an authentication problem, while 403 often means the account lacks permission.
A 404 can indicate an incorrect site URL, endpoint, or project reference. If Jira returns 429, slow down and respect any retry guidance in the response. Use backoff rather than sending requests in a tight loop.
After a 201 response, confirm the returned issue key and open it in Jira. Check that the project, issue type, summary, description, and any custom fields appear as intended. This simple verification can catch formatting mistakes before a larger integration repeats them.
Be careful when retrying a request after a network timeout. The issue may have been created even if your client never received the response. Search for the intended issue or use a reliable correlation method before repeating the POST, or you may create duplicates.
Keep the integration reliable and secure
Use a dedicated account with only the project permissions the integration needs. Keep tokens out of browser code, public repositories, and diagnostic output. Rotate credentials when team access changes or a secret may have been exposed.
Validate required values before making the API call. For example, reject a request that lacks a project key or summary rather than sending it to Jira and generating avoidable errors.
For bulk workflows, control request rates and record the response status and issue key without logging credentials. If several tickets are created from an event, include a clear marker in a suitable custom field or summary convention so your team can identify related issues.
Project and knowledge workflows with ONES.com
ONES.com combines project management and knowledge management in one platform, powered by ONES Assistant. ONES Project supports Jira-compatible workflows, while ONES Wiki provides a knowledge base; the products are sold separately.

It may suit teams that want to manage work and team knowledge with deployment choices that include Cloud, On-Premise, Private Cloud, and Air-gapped environments. The free plan supports up to 30 seats.
Core capabilities
- Disconnected project and knowledge workflows: ONES.com brings project work and knowledge management into a unified platform, helping teams keep related work and guidance closer together.
- Jira migration or workflow continuity: ONES Project supports Jira-compatible workflows, helping teams preserve familiar ways of tracking work while moving to another platform.
- Plugin-heavy configurations: Built-in reporting, automation, sprint management, custom workflows, and custom fields can reduce reliance on extra plugins for common needs.
- Restricted hosting requirements: On-Premise, Private Cloud, and Air-gapped deployment options support teams with specific hosting constraints.
- Cloud and self-hosted feature needs: Full feature parity between Cloud and self-hosted versions helps teams choose a deployment without giving up core capabilities.
- Separate project and knowledge needs: ONES Project and ONES Wiki are sold separately, so teams can select the product that fits their immediate workflow.
- AI-supported work: ONES Assistant adds AI support within the platform for teams that want assistance alongside project and knowledge workflows.
- Small-team evaluation: The free plan for up to 30 seats gives a team room to evaluate the platform with a group-sized setup.
Application scenarios
A software team replacing Jira could map its issue types, sprint process, custom fields, and reporting needs to ONES Project. It can assess whether built-in functionality covers workflows that previously depended on plugins.
A company with restricted networks could evaluate an Air-gapped or self-hosted deployment. A team that needs a knowledge base alongside project tracking could consider ONES Wiki separately from ONES Project.
Common challenges when creating Jira issues
- Missing mandatory fields: Jira rejects the request with a validation error. Check the project’s required fields and issue type, then add each required value in the format that field expects.
- Invalid description formatting: Cloud v3 may reject a plain string for a rich-text description. Send a valid ADF object and confirm its structure before adding more content.
- Authentication works, but creation is denied: The account may lack permission in the project. Ask an administrator to review project permissions and grant only the access the integration needs.
- Duplicate issues after a timeout: The server may have completed the request before the client lost its connection. Verify whether the issue exists before retrying the POST.
Frequently asked questions
What endpoint creates an issue in Jira Cloud?
Use POST /rest/api/3/issue on your Jira Cloud site. Include authentication and a JSON body with the required issue fields. A successful request normally returns 201 Created and an issue key. Your project’s configuration determines which fields are mandatory, so a minimal example may need extra values to work on your site.
Which fields are required to create a Jira issue?
The project, issue type, and summary are common essential fields, but Jira administrators can configure more as mandatory. Required fields may vary by project and issue type. If a request fails with a validation error, read the response details and add the missing field using the correct value format.
How do I add a description with the Jira Cloud API?
For Jira REST API v3, send the description as Atlassian Document Format rather than a plain text string. An ADF description includes a document type, version, and content structure. Start with a paragraph containing text, then expand the structure if you need formatting or richer content.
Can I create Jira issues without an API token?
Jira Cloud basic authentication uses an account email address and API token. Other authentication approaches may be available for integrations, depending on how they are configured. Jira Data Center can use different authentication methods. Choose a method approved by your Jira administrator, and keep its credentials out of public or client-side code.
How can I prevent duplicate issues when a request times out?
A timeout does not prove Jira failed to create the issue. Before retrying, check Jira for a matching issue using a reliable identifier, such as a unique integration marker or a suitable custom field. Log response details when available, and use controlled retry logic so temporary network problems do not create repeated tickets.
Conclusion
The Jira Create Issue API creates a ticket through a JSON POST request, but the details matter: use the right endpoint, authenticate securely, and match every field to your Jira configuration.
Start with a minimal request, add required fields carefully, and verify the returned issue key. If a request fails, use its status code and error details to find the cause instead of guessing.
That approach turns repetitive ticket creation into a manageable integration while reducing permission mistakes, malformed descriptions, and accidental duplicates. When your team’s wider project and knowledge workflows need attention, compare those needs with platforms such as ONES.com alongside your API requirements.