Create a Jira Issue via API: Steps, Payloads, and Tips
Need to create Jira issues via API without frustrating errors? Get the steps, payloads, and tips for the create jira issue api process. Read now.
Creating a Jira issue through the API sounds simple: send a request, get an issue key, and move on. But a missing field, incorrect issue type, or malformed description can turn that quick task into a frustrating debugging session.
Authentication errors and unclear API responses make the process harder, especially when you’re creating issues from a form, script, or another service. The good news? A reliable request follows a few predictable steps. Here’s how to prepare the fields, send the request, read the response, and handle common errors.
How to Create a Jira Issue Through the API
To create a Jira Cloud issue, send a POST request to /rest/api/3/issue with valid authentication and a JSON body containing the project, issue type, and summary.
Confirm the project and issue type. Find the project key, such as ENG, and an issue type that project allows, such as Task or Bug. The project’s configuration determines which issue types and fields are available.
Check required fields and permissions. The account used for the request needs permission to create issues in the project. It may also need access to any issue type, workflow, or custom field involved.
Prepare authentication. For Jira Cloud, a common option is Basic authentication using the account email address and an API token. OAuth 2.0 is another option for integrations that need delegated access.
Build a valid request body. Include the project key, issue type, and summary. Add other fields only when they are supported and valid for that project and issue type.
Send the POST request. Use the Jira Cloud REST API v3 endpoint and set the content type to JSON. Keep credentials outside scripts that you share or commit.
Check the response. A successful create request typically returns HTTP 201 with the new issue’s ID and key. Save the key, such as ENG-42, if a later step needs to reference the issue.
Here’s why: the request can be syntactically correct and still fail when a project field is unavailable or a required value is missing. Validate the field configuration before adding optional details.

Example Jira Cloud Request and Payload
This example creates a task in a Jira Cloud project. Replace the sample project key, issue type, email, and token with values for your account.
curl --request POST \
--url "https://your-domain.atlassian.net/rest/api/3/issue" \
--user "you@example.com:YOUR_API_TOKEN" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
"fields": {
"project": {
"key": "ENG"
},
"issuetype": {
"name": "Task"
},
"summary": "Add an export option to the report"
}
}'
For Jira Cloud API v3, descriptions use Atlassian Document Format (ADF). Add a description like this when your integration needs to include details:
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Add a CSV export option to the monthly report."
}
]
}
]
}
Place the description object inside fields, alongside project, issuetype, and summary. Keep the JSON structure exact: a missing brace or a string where Jira expects an object can cause a validation error.
But here's the truth: this payload is a starting point, not a universal template. Your project may require components, a reporter, an assignee, or custom fields before Jira accepts the request.
Which Fields Should You Include?
Start with the smallest valid payload. In many projects, the essential fields are the project, issue type, and summary. A short summary such as “Fix checkout timeout” gives the issue a clear purpose.
Add optional fields to support how your team works. For example, a bug might include a priority, labels, and a description that explains how to reproduce the problem. A task might need a component or an assignee instead.
Custom fields and field identifiers
Custom fields often use identifiers such as customfield_10042. The correct identifier and value format depend on the field type and project configuration. A single-select field, for example, may expect an option object rather than plain text.
Use Jira’s create-issue metadata to inspect available issue types and fields for the relevant project. This helps you check required fields and accepted values before sending a request.
Descriptions and version differences
Jira Cloud REST API v3 expects ADF for rich text descriptions. Jira Server or Data Center integrations may use different API versions and payload formats, so confirm the API version for your Jira installation.
Let me explain: copying a payload from a different Jira version can lead to confusing errors. Match the endpoint and field format to the environment where you’re creating the issue.
Authentication, Permissions, and Safe API Use
For a quick Jira Cloud integration, an API token paired with an account email is a common authentication method. OAuth can suit an app that needs user-authorized access across accounts.
Store credentials in a secure environment variable or secrets manager. Don’t place a live token in browser code, a public repository, or a request example shared with a broad team.
Permissions matter as much as credentials. A valid login can still receive a permission error if the account cannot create issues in the selected project or access a required field.
You might be wondering: how can you tell an authentication problem from a project configuration problem? Check the HTTP status and response body, then verify the account, project key, and field requirements separately.
Understand API Responses and Handle Errors
A successful request usually returns HTTP 201 and a response containing the new issue’s ID and key. Capture that key rather than guessing it from the project’s issue sequence.
When Jira rejects a request, its response often identifies a field with an invalid or missing value. Read the response body before changing the payload; it may point directly to the field that needs attention.
400 Bad Request: Check JSON syntax, required fields, field formats, and allowed values. An issue type name that differs from the project’s configuration can also cause rejection.
401 Unauthorized: Confirm the account name and token, and check that your authorization header is formed correctly.
403 Forbidden: Check project permissions and whether the account can create the requested issue type.
404 Not Found: Verify the Jira site address, endpoint path, project key, and access to the requested resource.
429 Too Many Requests: Slow the request rate and respect any retry guidance returned by the service.
If a network timeout occurs, Jira may have created the issue even though your script never received the response. Before retrying, search for a matching issue or use a dependable integration pattern that avoids accidental duplicates.
Practical Tips for Reliable Issue Creation
Keep the first request small, then add fields one at a time. This makes it easier to identify which value causes a failure and avoids debugging a large payload all at once.
Test with a non-production project before connecting the request to a live form or automated workflow. For example, submit a sample task, confirm its project and issue type, and inspect the result in Jira.
Log the response status, issue key, and safe error details. Never log API tokens or other credentials. If a request fails, a record of the response helps you distinguish a permission issue from an invalid field.
Plan for retries carefully. A client timeout does not prove that Jira rejected the request. Checking for a matching issue before retrying can prevent duplicates when a response is delayed.
Project Management Beyond Jira: ONES.com
ONES.com brings project management and knowledge management together in a unified platform powered by ONES Assistant. ONES Project handles project management, while ONES Wiki provides knowledge management; the products are sold separately.

If you’re evaluating how your team manages issues and project work, ONES Project is a Jira alternative with Jira-compatible workflows. The aim is to support familiar planning and tracking practices while giving teams deployment choices and built-in capabilities.
Core capabilities
Scattered project tracking → Jira-compatible workflows → teams can carry familiar issue-management patterns into their project work.
Limited progress visibility → built-in reporting → project leads can review work progress without relying on a collection of reporting add-ons.
Rigid processes → custom workflows → teams can adapt issue stages to match how requests move through their work.
Inconsistent issue details → custom fields → teams can capture information relevant to their own projects.
Unclear sprint planning → sprint management → agile teams can organize planned work and review sprint progress.
Repetitive manual tasks → automation → teams can automate supported workflow actions and reduce routine handling.
Plugin sprawl → native capabilities → built-in reporting, custom workflows, fields, sprint management, and automation can reduce reliance on extra plugins.
Deployment constraints → four deployment options → teams can choose Cloud, On-Premise, Private Cloud, or Air-gapped deployment.
Concerns about self-hosted capability gaps → feature parity → the self-hosted version has full feature parity with the cloud version.
Where teams may apply it
A software team can use ONES Project to organize issues, plan sprints, and adapt workflows to its delivery process. Built-in reporting can help the team review progress without assembling a separate reporting setup.
An organization with deployment restrictions can consider On-Premise, Private Cloud, or Air-gapped deployment options. Teams that also need knowledge management can evaluate ONES Wiki separately for that purpose.
ONES.com offers a free plan for up to 30 seats. Choose the product and deployment arrangement that fit your team’s needs, then assess the workflow capabilities your projects require.
Common Challenges When Creating Jira Issues
The request works in one project but fails in another. Projects can have different required fields and issue types. Inspect the target project’s create-issue metadata and adjust the payload for its configuration.
A description is rejected. Jira Cloud API v3 expects an ADF structure for rich text. Build the description in the expected format instead of sending a plain string.
The account authenticates but cannot create an issue. Authentication confirms identity; it does not grant every project permission. Ask a Jira administrator to check the account’s project access and create-issue permission.
A retry creates a duplicate. A timeout can occur after Jira creates the issue. Before retrying, look for a matching issue or apply a reliable duplicate-checking process.
FAQs
What endpoint creates an issue in Jira Cloud?
Use POST /rest/api/3/issue for Jira Cloud. Send a JSON request body with the project, issue type, and summary inside the fields object. The site address comes before the endpoint, such as https://your-domain.atlassian.net. Jira Server and Data Center may use different REST API versions, so check the version supported by your installation.
What fields are required to create a Jira issue?
The project, issue type, and summary are common required fields. Your Jira project may also require additional fields, such as a component, priority, or custom field. Requirements can differ between projects and issue types. Inspect the create-issue metadata for the target project before building a payload, especially when you’re creating issues across several projects.
How do I authenticate a Jira API request?
For Jira Cloud, a common method is Basic authentication using your account email and an API token. OAuth 2.0 is another option for apps that need delegated access. Keep tokens in a secure environment or secrets manager, and avoid exposing them in browser code or shared examples. Authentication does not replace project permissions; the account still needs permission to create the issue.
Why does Jira return a 400 error when I create an issue?
A 400 response commonly means the request body or one of its field values is invalid. Check the JSON structure, required fields, issue type, and field formats. For Jira Cloud API v3, confirm that the description uses Atlassian Document Format when supplied. The response body may identify the field Jira could not validate, which can narrow down the fix.
Conclusion
Creating an issue through Jira’s API comes down to a valid endpoint, permitted authentication, and a payload that matches the project’s configuration. Start with the required fields, check the response, and add optional details only when the request succeeds.
When the process gets frustrating, slow down and inspect the status code and response body before changing everything. A careful test and sensible retry handling can prevent failed requests and duplicate issues. With those habits, you can create Jira issues through the API more reliably and choose project workflows that fit your team.