Jira Create Issue API: 5 Steps with JSON Examples in Python
Need to automate Jira tickets without failed requests? Use the jira create issue api in 5 steps with JSON and Python examples. Read now to get started.
Creating a Jira issue through the REST API can save time when you need to turn a form submission, alert, or deployment event into tracked work. But a single missing field or incorrect description format can stop the request before an issue appears. That gets frustrating when your script runs unattended and the failure is easy to miss. Here's the truth: the process is straightforward once you know the right endpoint, required fields, authentication method, and response to expect. In this guide, I’ll walk you through five practical steps, with JSON and Python examples you can adapt. You’ll also learn how to check project requirements, protect your API token, and troubleshoot common errors before they derail your automation.
How to create a Jira issue with the REST API
For Jira Cloud, send an authenticated POST request to /rest/api/3/issue. The JSON body needs a project, issue type, summary, and any other fields your project requires. Follow these five steps to build and verify the request.
- Confirm your Jira site and project details. Identify your Jira Cloud site URL, project key, and issue type. For example, a project might use the key
OPS, with Task as an available issue type.
- Check required fields. Review the project’s issue creation screen or Jira’s create metadata endpoint. Field requirements can differ by project, issue type, and configuration.
- Prepare authentication. For Jira Cloud, use your Atlassian account email and an API token. Store the token securely rather than placing it directly in your script.
- Build and send the JSON request. Include the required fields in the body, then send a
POST request to the Jira REST API endpoint.
- Check the response. A successful creation usually returns HTTP
201 and includes the new issue’s key, such as OPS-123.

Step 1: Choose the correct endpoint
For Jira Cloud REST API v3, the issue creation endpoint is:
POST https://your-domain.atlassian.net/rest/api/3/issue
Replace your-domain with the domain for your Jira site. Keep the API version consistent with the environment and endpoint you use.
Jira Data Center and older Jira Server installations may use a different API version, configuration, or authentication method. Check your instance’s REST API guidance before reusing a Cloud example.
Step 2: Identify required fields
Jira needs a project, issue type, and summary to create a basic issue. Your project may also require fields such as priority, assignee, component, or a custom field.
You can inspect creation metadata for a project and issue type with a request like this:
GET https://your-domain.atlassian.net/rest/api/3/issue/createmeta?projectKeys=OPS&issuetypeNames=Task&expand=projects
Metadata and permissions affect what you can create. If your project uses custom workflows or required fields, confirm the field names and accepted values before you write the request body.
Step 3: Prepare a JSON body
This example creates a task in the OPS project. Jira Cloud API v3 expects rich-text descriptions in Atlassian Document Format (ADF).
{
"fields": {
"project": {
"key": "OPS"
},
"issuetype": {
"name": "Task"
},
"summary": "Check the nightly deployment",
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Review the deployment result and report any failed checks."
}
]
}
]
}
}
}
The fields object contains the issue details. The project key and issue type name must match values available in your Jira project.
For a simple one-line summary, use a string. For a description in Jira Cloud v3, provide ADF content rather than assuming a plain string will work.
Step 4: Send the request with Python
Install the requests package if you haven’t already. Set your site URL, Atlassian email, and API token as environment variables before running the script.
import os
import requests
from requests.auth import HTTPBasicAuth
site_url = os.environ["JIRA_SITE_URL"].rstrip("/")
email = os.environ["JIRA_EMAIL"]
api_token = os.environ["JIRA_API_TOKEN"]
url = f"{site_url}/rest/api/3/issue"
payload = {
"fields": {
"project": {"key": "OPS"},
"issuetype": {"name": "Task"},
"summary": "Check the nightly deployment",
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Review the deployment result and report any failed checks."
}
]
}
]
}
}
}
response = requests.post(
url,
json=payload,
headers={"Accept": "application/json"},
auth=HTTPBasicAuth(email, api_token),
timeout=30
)
if response.status_code == 201:
issue = response.json()
print(f"Created {issue['key']}: {issue['self']}")
else:
print(f"Request failed: HTTP {response.status_code}")
print(response.text)
Using json=payload lets the Python library encode the body as JSON. The timeout also helps prevent a script from waiting indefinitely if the connection stalls.
Step 5: Verify the result
When creation succeeds, Jira usually returns 201 Created and a response containing the issue key and issue URL. Log the key so you can connect the new Jira issue to the event that triggered it.
If the response indicates an error, inspect its status code and message. A 400 often points to invalid or missing fields, while a 401 or 403 usually indicates an authentication or permission problem.
Understand the request and response
A Jira issue creation request has three practical parts: the endpoint, authentication, and a JSON body. The body tells Jira which project and issue type to use, then supplies the summary and any additional fields.
Think of the request as a carefully completed issue form sent over HTTP. If the project requires a priority, for example, your body may need a priority object such as {"priority":{"name":"High"}}. The exact accepted value depends on your Jira configuration.
On success, Jira returns an issue key you can use in later API calls. Your automation could print OPS-123, attach it to an alert, or include it in a notification to the team.
Authentication and permissions to check
Jira Cloud supports API token authentication with your Atlassian account email. In the Python example, HTTPBasicAuth sends those credentials over HTTPS. Create a token through your Atlassian account and give it only the access needed for the task.
Keep credentials in environment variables or a secrets manager. Avoid committing tokens to a code repository, writing them to logs, or sharing them in a screenshot. If a token is exposed, revoke it and replace it.
Authentication alone does not guarantee issue creation. The account also needs permission to create issues in the target project. For example, a token can be valid while the account lacks the project permission required to create a task.
Make your JSON match Jira’s field formats
Field formats are a common source of failed requests. Jira Cloud’s API v3 uses ADF for rich-text descriptions, while fields such as project and issue type use nested objects. A plain string may work for a summary but fail for a field that expects a structured value.
Custom fields add another consideration. Jira often identifies them with keys such as customfield_10042, and their required values depend on the field type. A single-select field, for instance, may expect an object containing an option value.
Start with the smallest valid request, then add fields one at a time. If the minimal issue works but a longer request fails, you have narrowed the problem to one of the added fields or its format.
Handle errors and make automation reliable
Do not treat every non-success response as the same problem. Check the HTTP status and response body, then log enough information to diagnose the issue without exposing credentials or sensitive content.
- 400 Bad Request: Check required fields, project and issue type values, and the structure of custom fields or ADF content.
- 401 Unauthorized: Confirm the account email and API token, and verify that the token is still valid.
- 403 Forbidden: Check whether the account has permission to create issues in that project.
- 404 Not Found: Confirm the site URL, API path, and access to the requested project or endpoint.
For repeated automation, avoid creating duplicate issues when a request is retried after a network timeout. One approach is to record a unique event identifier in an agreed field, then check whether that identifier already has an associated issue before creating another.
Use sensible retry behavior for temporary connection problems, but don’t blindly retry validation or permission errors. Those need a change to the request or account access, not another identical attempt.
Jira issue management solution: ONES.com

Value proposition
ONES.com brings project management and knowledge management together in one platform powered by ONES Assistant. ONES Project is its project management product and a Jira alternative; ONES Wiki is its knowledge management product and a Confluence alternative. They’re sold separately, so you can select the product that fits your team.
If your API integration has highlighted a wider need for project workflows, reporting, or deployment flexibility, ONES Project may be worth evaluating. You can try it free for up to 30 seats and choose Cloud, On-Premise, Private Cloud, or Air-gapped deployment.
Core capabilities
- Jira workflow migration concerns: ONES Project supports Jira-compatible workflows, helping teams carry familiar processes into another project management environment.
- Heavy reliance on add-ons: Built-in capabilities can reduce the need for plugins to cover common project management needs.
- Limited workflow flexibility: Custom workflows let teams shape issue movement around their approval or delivery process.
- Rigid issue fields: Custom fields let teams capture details suited to their work, such as a service area or release milestone.
- Sprint planning overhead: Sprint management supports teams that plan and track work in iterative cycles.
- Manual repeated actions: Automation can handle routine workflow tasks, reducing the need for someone to repeat them by hand.
- Scattered project visibility: Built-in reporting helps teams review project progress without relying on a separate reporting add-on.
- Deployment constraints: Cloud and self-hosted deployments offer options for different operating environments, with feature parity between them.
Application scenarios
A software team reviewing Jira alternatives: A team can assess ONES Project’s Jira-compatible workflows, sprint management, custom fields, and reporting against its existing project process. That makes it easier to identify what needs to carry over and where the team may simplify its setup.
A team with restricted network requirements: An organization that cannot use a public cloud service can evaluate On-Premise, Private Cloud, or Air-gapped deployment. It can also consider ONES Wiki separately if it wants a knowledge management product alongside project management.
Common challenges and practical fixes
- Issue creation fails because of a missing required field. Check the project’s requirements for the selected issue type, then add the missing field in the format Jira expects.
- The description is rejected. For Jira Cloud API v3, format rich-text descriptions as ADF. Test a short paragraph before adding links, formatting, or multiple content blocks.
- The credentials work in a browser but fail in Python. Use the Atlassian account email with an API token for Jira Cloud. Confirm the script reads the intended environment variables.
- The script creates duplicate issues after a timeout. Before retrying, check whether the original request created an issue. An event identifier can help your automation recognize repeats.
- The request succeeds for one project but fails for another. Project permissions and required fields can differ. Verify the target project’s configuration rather than assuming the same JSON works everywhere.
FAQs
What is the Jira issue creation endpoint?
For Jira Cloud REST API v3, send a POST request to /rest/api/3/issue on your Jira site. Include a JSON body with the project, issue type, summary, and other required fields. Jira Server or Data Center environments may use different API versions or settings, so verify the endpoint for your specific installation.
Which fields are required to create a Jira issue?
A basic issue generally needs a project, issue type, and summary. Your project may require more fields, such as priority or a custom field. Check the project’s issue creation requirements or Jira’s create metadata endpoint before sending the request. Required values and field formats can differ between projects and issue types.
How do I authenticate to Jira Cloud from Python?
For Jira Cloud, use your Atlassian account email and an API token with HTTP Basic authentication over HTTPS. In Python, requests provides this through HTTPBasicAuth(email, api_token). Keep the token outside your script, such as in an environment variable, and make sure the account has permission to create issues in the project.
Why does Jira reject my description field?
Jira Cloud REST API v3 expects rich-text descriptions in Atlassian Document Format. A plain text string may be rejected when the endpoint expects an ADF object with a document type, version, and content array. Start with a simple paragraph structure, then add more formatting only after the basic request succeeds.
Conclusion
Creating a Jira issue through the REST API comes down to five steps: confirm the endpoint, check required fields, prepare authentication, send valid JSON, and verify Jira’s response. The Python example gives you a starting point, while the troubleshooting guidance helps you find the cause when a request fails.
But here's the truth: reliable automation takes more than one successful request. Protect your token, match Jira’s field formats, and account for retries so a temporary network problem doesn’t create duplicate work. With those safeguards in place, you can turn recurring events into trackable issues with less manual effort.