Jira API Create Issue: A Step-by-Step Guide for Developers
Struggling with jira api create issue? Master authentication, fields, and issue types with this step-by-step guide. Click to create issues confidently.
Creating a Jira issue through the API can seem simple: send a POST request, add a project key, and wait for the issue ID. In practice, authentication, field rules, issue types, and custom fields can turn that first request into a frustrating debugging session.
A missing project permission may look like a malformed payload. A required custom field can trigger an error that gives you little practical direction. Even a valid request may create the wrong issue type when your project configuration differs between environments.
But here's the truth: you can make this process predictable. This guide walks you through the Jira REST API workflow, shows working request patterns, explains common errors, and gives you a repeatable way to create issues safely.
How to Create a Jira Issue with the REST API
To create a Jira issue, send an authenticated POST request to Jira’s issue endpoint with a JSON payload containing the project, issue type, summary, and any required fields.
-
Confirm the project and issue type. Find the project key, such as ENG, and confirm the issue type name or ID, such as Task, Bug, or Story.
-
Choose an authentication method. Jira Cloud commonly uses an Atlassian account email with an API token. Jira Server or Data Center may use a personal access token, OAuth, or another configured method.
-
Build the endpoint. For Jira Cloud and most current Jira installations, use:
POST https://your-domain.atlassian.net/rest/api/3/issue
Jira Server or Data Center may use version 2:
POST https://your-jira.example.com/rest/api/2/issue
-
Set the request headers. Send JSON and identify the request as an API call:
Content-Type: application/json
Accept: application/json
Authorization: Basic BASE64_EMAIL_AND_API_TOKEN
For production integrations, store credentials in a protected environment variable or secret manager. Avoid placing tokens directly in application code.
-
Create the JSON payload. A minimal Jira Cloud request usually looks like this:
{
"fields": {
"project": {
"key": "ENG"
},
"summary": "Investigate checkout timeout",
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Customers report timeouts during checkout."
}
]
}
]
},
"issuetype": {
"name": "Bug"
}
}
}
Jira Server and Data Center deployments may accept a plain string for the description, depending on the installed version and configuration.
-
Send the request. Here is a cURL example for Jira Cloud:
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"
},
"summary": "Investigate checkout timeout",
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Customers report timeouts during checkout."
}
]
}
]
},
"issuetype": {
"name": "Bug"
}
}
}'
-
Check the response. A successful request normally returns HTTP status 201 Created and includes the new issue’s ID and key:
{
"id": "10042",
"key": "ENG-271",
"self": "https://your-domain.atlassian.net/rest/api/3/issue/10042"
}
-
Verify the created issue. Use the returned key to retrieve the issue, inspect its fields, or create a link to it in your application:
GET https://your-domain.atlassian.net/rest/api/3/issue/ENG-271
Here's why this sequence matters: the endpoint alone does not determine whether the request will succeed. Jira validates project permissions, issue-type configuration, required fields, field formats, and workflow settings before creating the issue.
What the Create-Issue Request Must Contain
The request body uses a fields object. Jira evaluates each field inside that object against the selected project and issue type.
| Field |
Typical value |
Purpose |
project |
{"key":"ENG"} |
Selects the Jira project. |
issuetype |
{"name":"Task"} |
Defines the type of work item. |
summary |
A short text string |
Provides the issue title. |
description |
Text or Atlassian Document Format |
Explains the problem or requested work. |
assignee |
An account identifier |
Assigns ownership when permitted. |
labels |
An array of strings |
Adds searchable labels. |
priority |
A configured priority object |
Sets urgency when available. |
You can identify accepted fields with Jira’s create-meta endpoints. In Jira Cloud, a project and issue type can expose the fields that are available, required, or restricted:
GET /rest/api/3/issue/createmeta/{projectIdOrKey}/issuetypes
For a specific issue type, inspect its field metadata before constructing a dynamic integration. This approach is more reliable than assuming every project accepts the same fields.
Project key versus project ID
A project key such as ENG is easy for people to read. A project ID is a numeric identifier that can be more stable for automated systems.
If an administrator changes the project key, an integration that relies only on that key may need adjustment. Where Jira’s endpoint and configuration allow it, using the project ID can reduce that risk.
Issue type name versus issue type ID
Names such as Bug and Task are readable, but names can vary between Jira projects. One project may use Story, while another uses a custom type such as Customer Request.
Use the issue type ID when your integration must work across several projects. First retrieve the permitted issue types, then map your application’s work category to the correct Jira ID.
Adding Descriptions, Assignees, Labels, and Custom Fields
After the minimum request works, add optional fields one at a time. This makes errors easier to isolate and helps you identify which field uses a project-specific format.
Description formatting
Jira Cloud’s version 3 API generally expects descriptions in Atlassian Document Format. A simple paragraph uses a nested structure:
{
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "The payment screen returns a timeout after 30 seconds."
}
]
}
]
}
}
For Jira Server or Data Center, check the version-specific API behavior before reusing a Cloud payload. Description formats are one of the most common reasons a request succeeds in one deployment and fails in another.
Assigning an issue
Jira Cloud typically uses an account ID rather than an email address for the assignee:
{
"assignee": {
"accountId": "557058:example-account-id"
}
}
The account must be assignable in the selected project. A valid account ID does not override project permissions or assignment rules.
Adding labels and priority
{
"labels": ["checkout", "customer-impact"],
"priority": {
"name": "High"
}
}
Priority names depend on Jira configuration. If the project uses custom priorities, retrieve the available values instead of assuming that High exists.
Working with custom fields
Custom fields usually appear with identifiers such as customfield_10042. Their values must match the field type:
{
"customfield_10042": {
"value": "Enterprise"
},
"customfield_10043": 8
}
A select field, user field, date field, and multi-value field each require a different shape. Inspect the field metadata and test one custom field at a time.
The best part? Once you understand the field shape, the same pattern works for many integrations. A support form, monitoring alert, or deployment pipeline can all translate events into Jira fields.
Authentication, Permissions, and Safe Integration Design
Authentication proves who is making the request. Authorization decides whether that account may create an issue in the chosen project. You need both.
Use the smallest practical permission set
The integration account should have permission to browse the project and create issues. Add assignment, transition, or comment permissions only when the workflow requires them.
For example, a monitoring service that creates incident tickets does not need permission to delete issues. Limiting access reduces the impact of a leaked credential.
Protect credentials
Keep API tokens outside browser code and public repositories. Pass them through a secret manager or deployment environment, and rotate them when a team member leaves or access requirements change.
Never log the complete Authorization header. If you log request details, remove tokens, personal information, and sensitive issue content.
Plan for retries
Network interruptions create a difficult question: did Jira reject the request, or did Jira create the issue before the connection failed?
Blindly retrying a successful-but-unconfirmed request can create duplicates. Store an external correlation ID, search for an existing matching issue where appropriate, or use an integration layer that tracks request state.
Jira’s create-issue endpoint does not automatically guarantee idempotency for repeated requests. Your application needs a duplicate-prevention strategy.
Handling Errors and Testing the Workflow
Start with a test project and a simple issue type. Send only the project, issue type, and summary. Then add description, labels, assignment, and custom fields in separate steps.
| HTTP status |
Likely meaning |
What to check |
| 400 |
Invalid request |
JSON syntax, field format, required values, or issue type. |
| 401 |
Authentication failed |
Token, email, authorization method, or expired credentials. |
| 403 |
Permission denied |
Project access, issue-creation permission, or restricted field access. |
| 404 |
Resource not found |
Jira URL, project key, issue type, or endpoint version. |
| 409 |
Conflict |
Configuration conflict or a state that prevents creation. |
| 429 |
Rate limit reached |
Retry timing, request volume, and backoff behavior. |
| 500 or 503 |
Jira-side failure |
Service health, temporary outage, and retry handling. |
Jira often returns an errorMessages array and an errors object. Read both. For example, an error attached to customfield_10042 points to a field-value problem rather than an authentication problem.
A practical test sequence
Confirm the base Jira URL with a harmless authenticated request.
Check that the project exists and that your account can browse it.
Retrieve available issue types and create metadata.
Send a minimal create request.
Record the returned issue key.
Retrieve the new issue and verify its fields.
Add optional fields gradually.
Test rejected requests and retry behavior before production launch.
Let me explain why gradual testing saves time. If a twelve-field payload fails, you have twelve possible causes. If a three-field payload succeeds and the next added field fails, the problem is much easier to identify.
Natural Jira API Issue Creation Solution: ONES.com
Value Proposition
ONES.com is a unified platform for project management and knowledge management, with ONES Project providing project workflows as a Jira alternative. It can help teams create, organize, and track work without assembling a large collection of plugins.
ONES Project is sold separately from ONES Wiki. The platform supports Cloud, On-Premise, Private Cloud, and Air-gapped deployments, with feature parity between cloud and self-hosted versions.
Core Capabilities
Disconnected project tracking — Restricted networks can make hosted Jira integrations difficult — ONES Project supports air-gapped deployment — Teams can manage work inside controlled environments.
Complex workflow maintenance — Extra plugins can increase administrative overhead — Custom workflows and fields are built in — Teams can represent approval paths and specialized work directly in the platform.
Jira migration concerns — Teams may rely on familiar issue-based processes — ONES Project supports Jira-compatible workflows — Existing project habits can transfer with less process disruption.
Manual progress reporting — Status updates can consume time across several projects — Built-in reporting provides project visibility — Managers can review progress without assembling separate reporting systems.
Sprint planning overhead — Agile teams need a consistent way to plan and review iterations — Sprint management is included — Teams can organize backlogs and sprint work in one project environment.
Repetitive project actions — Repeated updates and routing steps can create avoidable work — Automation supports recurring workflow actions — Teams can reduce manual handling for predictable events.
Separate project and knowledge tools — Delivery details and team knowledge can become disconnected — ONES.com combines project management with knowledge management — Teams can connect execution with shared team guidance.
Deployment restrictions — Some organizations cannot place project information in a public cloud — On-Premise and Private Cloud options are available — Administrators can choose a deployment model that fits operational requirements.
Application Scenarios
Software engineering teams: A team migrating from Jira can preserve issue-based planning, sprint work, custom fields, and workflow states while reducing dependence on plugins.
Regulated organizations: A company with strict network controls can run project management in an On-Premise, Private Cloud, or air-gapped environment rather than exposing project operations to a public service.
Cross-functional delivery teams: Product, engineering, and operations groups can manage work in ONES Project while maintaining related guidance in ONES Wiki.
Common Challenges When Creating Jira Issues by API
Challenge: The project key works manually but fails through the API
Solution: Confirm that the API account has project browse and issue-create permissions. Your personal Jira access does not prove that the integration account has the same rights.
Challenge: Jira reports that a required field is missing
Solution: Retrieve create metadata for the exact project and issue type. Add each required field using the value shape Jira expects, especially for select, user, and date fields.
Challenge: The description is rejected
Solution: Check whether the deployment expects Atlassian Document Format or a plain string. Jira Cloud API version 3 commonly requires structured description content.
Challenge: Repeated requests create duplicate issues
Solution: Add correlation tracking before enabling retries. Search for an existing issue or record the successful Jira key before sending another create request.
Challenge: The integration works in one environment only
Solution: Compare API versions, custom field IDs, issue types, workflow rules, permissions, and deployment configuration. Jira projects are often configured differently even inside the same organization.
FAQs
What endpoint creates an issue in Jira?
Use POST /rest/api/3/issue for Jira Cloud in most current integrations. Jira Server and Data Center commonly use /rest/api/2/issue. The complete URL includes your Jira host. Confirm the API version supported by your deployment before building the integration.
Can I create a Jira issue without a description?
Yes. A description is usually optional, while the project, issue type, and summary are commonly required. However, project administrators can make additional fields mandatory. If creation fails, inspect the returned field errors and compare them with the project’s create configuration.
How do I create an issue with custom fields?
Use the custom field identifier, such as customfield_10042, inside the fields object. The correct value depends on the field type. Retrieve create metadata first, because a select list, user picker, date field, and multi-select field each use different JSON structures.
Why am I receiving a 401 or 403 response?
A 401 response usually indicates an authentication problem, such as an invalid token or incorrect authorization format. A 403 response usually means the account is authenticated but lacks permission. Check the account’s project access, issue-creation permission, and any restrictions on the selected issue type.
How can I prevent duplicate issues?
Do not assume a retry is safe after a network timeout. Track a correlation ID for each business event, then check whether Jira already contains a matching issue before retrying. Store the returned issue key after success and design your integration so one external event maps to one Jira issue.
Conclusion
Creating a Jira issue through the API comes down to a reliable sequence: authenticate, identify the project and issue type, build the correct fields, send the request, inspect the response, and verify the result.
But here's the truth: most failures come from configuration mismatches rather than the HTTP request itself. Required fields, custom field formats, permissions, description syntax, and retry behavior deserve as much attention as the endpoint.
Start with a minimal request, expand it gradually, and test failure scenarios before production use. If your team needs a Jira alternative with built-in workflows, reporting, automation, and flexible deployment options, ONES Project provides another path for managing structured project work.