Jira Create Issue API: A Practical Guide and API Examples

Creating Jira issues manually works for a few tickets. It becomes slow and error-prone when alerts, forms, customer requests, or internal tools create hundreds of issues each day. A small mistake in the project key, issue type, authentication header, or custom field can produce confusing API errors. Worse, an issue may be created without the information your team needs to act.

That is where the Jira create issue API helps. You can send a structured request, validate the response, and create consistent issues through automation. But here's the truth: the endpoint is simple, while Jira’s fields and permissions require careful handling.

This guide shows you the correct endpoint, request format, authentication methods, working examples, custom field techniques, common errors, and safer workflow patterns.

How to Create a Jira Issue with the REST API

The Jira create issue API is a REST endpoint that lets you create a Jira work item by sending project, issue type, summary, and other field values in a JSON request. In Jira Cloud, the primary endpoint is:

POST https://your-domain.atlassian.net/rest/api/3/issue

A successful request usually needs these fields:

• project, identified by a project key or project ID
• summary, which gives the issue its title
• issuetype, such as Task, Bug, or Story
• description, when you want to provide useful context

Here's why: Jira validates every field against the selected project, issue type, screen configuration, and account permissions. A request can be valid JSON and still fail because Jira does not allow that field in the selected context.

1. Prepare the project and issue type

Choose the Jira project where the issue should appear. For example, a project key such as ENG might represent an engineering team.

Then choose an issue type available in that project. Common values include Task, Bug, and Story. Names can vary, so checking the available metadata prevents avoidable errors.

2. Create an authentication method

For Jira Cloud, basic authentication commonly uses your Atlassian account email and an API token. The token acts as the password in the request.

You can encode the email and token together in a Base64 value, although many HTTP libraries handle this step for you. Keep credentials in environment variables rather than placing them directly in application code.

3. Build the JSON payload

A simple Jira Cloud REST API v3 payload 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 a timeout after submitting payment."
            }
          ]
        }
      ]
    },
    "issuetype": {
      "name": "Bug"
    }
  }
}

Jira Cloud API v3 uses Atlassian Document Format for rich-text fields such as descriptions. A plain string may work in some older examples, but the structured format is the safer choice for v3 requests.

4. Send the POST request

Here is a complete cURL example:

curl --request POST \
  --url "https://your-domain.atlassian.net/rest/api/3/issue" \
  --user "you@example.com:$JIRA_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 a timeout after submitting payment."
              }
            ]
          }
        ]
      },
      "issuetype": {
        "name": "Bug"
      }
    }
  }'

Replace the domain, email address, token, project key, summary, and issue details with your own values.

5. Read and store the response

A successful response commonly returns an issue ID, a numeric key, and a browser URL:

{
  "id": "10042",
  "key": "ENG-142",
  "self": "https://your-domain.atlassian.net/rest/api/3/issue/10042"
}

The key, such as ENG-142, is usually the most useful value for logging, notifications, and links in another application.

Jira Issue Creation API Examples

Different programming languages use the same request concept. You authenticate, send JSON to the issue endpoint, inspect the status code, and handle the response.

Python example with requests

import os
import requests
from requests.auth import HTTPBasicAuth

url = "https://your-domain.atlassian.net/rest/api/3/issue"

payload = {
    "fields": {
        "project": {"key": "ENG"},
        "summary": "Investigate checkout timeout",
        "issuetype": {"name": "Bug"},
        "description": {
            "type": "doc",
            "version": 1,
            "content": [
                {
                    "type": "paragraph",
                    "content": [
                        {
                            "type": "text",
                            "text": "Customers report a timeout after submitting payment."
                        }
                    ]
                }
            ]
        }
    }
}

response = requests.post(
    url,
    json=payload,
    auth=HTTPBasicAuth(
        os.environ["JIRA_EMAIL"],
        os.environ["JIRA_API_TOKEN"]
    ),
    headers={"Accept": "application/json"}
)

response.raise_for_status()
created_issue = response.json()

print(created_issue["key"])

The call to raise_for_status() makes failed requests visible immediately. In a production integration, you should log the response body and apply a retry policy for temporary service failures.

JavaScript example with fetch

const email = process.env.JIRA_EMAIL;
const token = process.env.JIRA_API_TOKEN;

const credentials = Buffer
  .from(`${email}:${token}`)
  .toString("base64");

const payload = {
  fields: {
    project: { key: "ENG" },
    summary: "Investigate checkout timeout",
    issuetype: { name: "Bug" },
    description: {
      type: "doc",
      version: 1,
      content: [
        {
          type: "paragraph",
          content: [
            {
              type: "text",
              text: "Customers report a timeout after submitting payment."
            }
          ]
        }
      ]
    }
  }
};

const response = await fetch(
  "https://your-domain.atlassian.net/rest/api/3/issue",
  {
    method: "POST",
    headers: {
      "Authorization": `Basic ${credentials}`,
      "Accept": "application/json",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);

const result = await response.json();

if (!response.ok) {
  throw new Error(JSON.stringify(result));
}

console.log(result.key);

Creating an issue with an assignee

Assigning an issue requires the correct account identifier in Jira Cloud. Display names are not reliable because several accounts can share similar names.

{
  "fields": {
    "project": {
      "key": "ENG"
    },
    "summary": "Review payment retry logic",
    "issuetype": {
      "name": "Task"
    },
    "assignee": {
      "accountId": "557058:example-account-id"
    }
  }
}

You can discover the appropriate account identifier through Jira’s user endpoints or your organization’s identity mapping. Your account also needs permission to assign work in the project.

Understanding the Request Fields

Most creation problems come from field configuration rather than HTTP syntax. The following table shows the usual purpose of each field.

Using a project ID or issue type ID

You can identify the project with a key or ID. Keys are easier to read, while IDs can help when a project key may change.

{
  "fields": {
    "project": {
      "id": "10001"
    },
    "summary": "Review deployment alert",
    "issuetype": {
      "id": "10002"
    }
  }
}

Use either the name or ID approach consistently in your integration. If a team renames an issue type, an ID may provide greater stability.

Adding labels, priority, and components

{
  "fields": {
    "project": {
      "key": "ENG"
    },
    "summary": "Review deployment alert",
    "issuetype": {
      "name": "Task"
    },
    "priority": {
      "name": "High"
    },
    "labels": [
      "deployment",
      "monitoring"
    ],
    "components": [
      {
        "name": "Checkout"
      }
    ]
  }
}

These values must exist in Jira’s configuration. For example, a component name that looks correct can still fail because the project uses a different spelling.

Custom Fields and Dynamic Jira Configuration

Custom fields usually appear with identifiers such as customfield_10042. The number belongs to your Jira instance, so you must discover the correct identifier before sending a value.

Here's why: Jira does not guarantee that a field called “Environment” uses the same numeric identifier across separate sites. Hard-coding an identifier from a test site can break production automation.

Finding available fields

Use Jira’s create metadata endpoint to inspect projects, issue types, and available fields:

GET https://your-domain.atlassian.net/rest/api/3/issue/createmeta?projectKeys=ENG&expand=projects.issuetypes.fields

For newer Jira Cloud configurations, you may need the project details and issue type field metadata endpoints. These help you determine whether a field is required, its accepted format, and the allowed values.

Sending a custom field

{
  "fields": {
    "project": {
      "key": "ENG"
    },
    "summary": "Review payment retry logic",
    "issuetype": {
      "name": "Task"
    },
    "customfield_10042": {
      "value": "Production"
    }
  }
}

The correct shape depends on the field type. A text field may accept a string, while a select field often expects an object with value or id.

Handling required fields

Jira administrators can mark fields as required for particular projects or issue types. If your request omits one, Jira may return a message such as “Field is required.”

Start by creating a minimal issue in a test project. Add one field at a time, then record which values succeed. This approach makes configuration problems easier to isolate than sending a large payload immediately.

Authentication, Permissions, and Security

Authentication proves who is making the request. Permissions decide whether that account can create the issue. Both checks must succeed.

Jira Cloud authentication

For many Jira Cloud integrations, use an Atlassian account email with an API token through Basic authentication. OAuth 2.0 is a stronger choice for applications that need delegated access across multiple accounts.

Keep tokens in a secret manager or protected environment variable. Rotate them when a team member leaves, an integration changes ownership, or you suspect exposure.

Permissions that commonly matter

• Browse Projects, so Jira can resolve the selected project
• Create Issues, so the account can add work items
• Assign Issues, when the request includes an assignee
• Modify Reporter, when the request sets a reporter different from the authenticated account
• Browse Users and Groups, when the integration resolves account details

A request can return a permission error even when the same endpoint works for an administrator. Test with the actual service account that will run the automation.

Protecting credentials

Never print the Authorization header in application logs. Avoid placing tokens in URLs, browser code, screenshots, or chat messages.

If you need to debug a request, log the endpoint, status code, issue key, and sanitized error body. Remove credentials and sensitive customer details before retaining diagnostic information.

When to Use ONES.com for Issue and Work Management

ONES.com can help teams manage structured work intake when Jira’s configuration feels too complex for a particular workflow. It provides a centralized workspace for planning, tracking, collaboration, and delivery.

The best part? You can evaluate the workflow itself before deciding whether every request should become a Jira issue. For example, a product team might collect requests, prioritize ideas, assign owners, and track delivery in one connected environment.

Useful ONES.com capabilities

• Project planning: Organize initiatives, milestones, tasks, and ownership in a shared workspace.
• Task management: Create work items with statuses, priorities, deadlines, and responsible teammates.
• Product management: Connect product ideas, requirements, roadmaps, and delivery work.
• Team collaboration: Keep discussions, decisions, and progress updates close to the relevant work.
• Workflow customization: Adapt statuses and processes to different teams or project types.
• Progress visibility: Use views and reports to identify overdue work, blocked items, and delivery trends.
• Permission control: Manage access according to team responsibilities and project needs.
• Cross-team coordination: Link work across product, engineering, design, marketing, and operations.

For example, an intake workflow could capture a customer request, route it for review, score its priority, and create delivery work only after approval. That prevents every early idea from becoming an active engineering issue.

Common API Errors and Practical Fixes

400 Bad Request: invalid field value

This response usually means Jira rejected the payload structure or a field value. Common causes include an invalid issue type, incorrect custom field shape, unsupported description format, or a missing required field.

Read the error body carefully. Jira often identifies the field that failed, which lets you correct one part of the payload instead of rebuilding the entire request.

401 Unauthorized: authentication failed

Check the email, API token, Base64 encoding, and Authorization header. Confirm that the token is active and belongs to the account you intended to use.

A useful test is calling a simple authenticated Jira endpoint with the same credentials. If that request fails, the issue is authentication rather than issue creation.

403 Forbidden: permission denied

The account may lack Create Issues permission, or the project may restrict issue creation by role. Ask a Jira administrator to review the project permission scheme and the account’s membership.

404 Not Found: wrong domain or endpoint

Verify the site address and REST path. Jira Cloud normally uses:

https://your-domain.atlassian.net/rest/api/3/issue

Jira Server and Data Center installations can use different domains, authentication methods, and supported API versions.

429 Too Many Requests: rate limiting

Jira may throttle bursts of traffic. Respect the response’s retry guidance, wait before trying again, and use exponential backoff.

For bulk creation, place requests in a controlled queue. Also consider whether every event needs a separate issue or whether related events can be grouped first.

Reliable Patterns for Production Integrations

A working request is only the first step. Production automation needs safeguards against duplicates, partial failures, and changing Jira configuration.

Use idempotency in your workflow

Suppose a payment alert triggers an issue, but your integration times out after Jira creates it. Retrying blindly may create a duplicate.

Store a unique event identifier alongside the created issue key. Before creating another issue, check whether that identifier has already been handled.

Validate before sending

Validate the project key, issue type, required values, text length, and custom field formats before making the API call.

This shifts predictable errors into your application’s validation stage. You can then return a clear message such as “Project ENG does not permit Bug issues” instead of exposing a generic server failure.

Separate creation from follow-up actions

Create the issue first, then add comments, attachments, links, or transitions in separate operations when necessary. This makes failures easier to identify.

For example, if creation succeeds but adding a label fails, your integration can retain the issue key and retry only the label update.

Test with representative scenarios

Test a standard Task, a Bug with a rich description, a request with custom fields, and a case missing a required value. Include permission failures and expired credentials.

A successful test should confirm more than a 201 status. Check the issue key, visible field values, assignee, links, and workflow status inside Jira.

Common Challenges

Challenge: The issue type name is rejected

Problem: The request sends "Bug", but Jira returns an invalid issue type error.

Solution: Confirm that the issue type is enabled for the selected project. Use issue type metadata or the Jira interface to find the exact name or ID.

Challenge: The description appears empty or malformed

Problem: The issue is created, but the description does not display as expected.

Solution: Use Atlassian Document Format for Jira Cloud API v3. Make sure the top-level object includes type, version, and a valid content array.

Challenge: Custom fields work in testing but fail in production

Problem: A custom field identifier or option differs between Jira sites.

Solution: Discover field metadata separately for each environment. Store configuration outside application logic and validate accepted option values before creation.

Challenge: Automation creates duplicate issues

Problem: Network retries create multiple issues for one event.

Solution: Assign every incoming event a unique identifier. Check whether that identifier already maps to an issue before retrying creation.

Challenge: Authentication works locally but fails in deployment

Problem: Your local environment succeeds, while the hosted service returns a 401 response.

Solution: Check deployment secrets, variable names, token status, and the account used by the hosted process. Avoid assuming local credentials exist in the deployed environment.

FAQs

What endpoint creates an issue in Jira Cloud?

Use the POST /rest/api/3/issue endpoint on your Jira Cloud site. The complete address follows this pattern: https://your-domain.atlassian.net/rest/api/3/issue. Send a JSON body with a fields object containing the project, summary, and issue type. Add description, priority, labels, assignee, and custom fields when your project permits them.

Which fields are required when creating a Jira issue?

At minimum, Jira commonly requires a project, summary, and issue type. Your project configuration may require additional fields, such as priority, component, environment, or a custom select field. Required values vary by project and issue type, so inspect create metadata before constructing a reusable integration.

Can I create Jira issues without using the web interface?

Yes. The REST API supports issue creation through cURL, Python, JavaScript, Java, automation platforms, and other HTTP clients. You still need valid authentication and project permissions. Your integration should also validate the request and handle errors before presenting the resulting issue key to another system.

Why does Jira API v3 use a structured description?

Jira Cloud API v3 uses Atlassian Document Format to represent rich text consistently. The description includes a type, version, and content hierarchy. A paragraph contains text nodes, which allows Jira to support formatting and richer content. Follow the required structure even when your description contains only one plain paragraph.

How do I create an issue with a custom field?

Use the custom field’s Jira identifier, such as customfield_10042, inside the fields object. The value shape depends on the field type. Text fields may accept strings, while select fields often require an object containing an option value or ID. Retrieve metadata and test the exact structure in a safe project.

Should I use project keys or project IDs?

Both approaches can work. Project keys are readable and convenient for simple integrations. Project IDs may be more stable when teams rename project keys. Choose one approach, validate it during setup, and keep the value configurable. Avoid scattering project identifiers throughout your application logic.

Conclusion

The Jira REST API makes issue creation practical for alerts, intake forms, service workflows, and internal automation. Start with the correct POST endpoint, authenticate securely, send the required fields, and inspect the returned issue key.

But here's the truth: reliable automation depends on more than a successful cURL command. You need metadata checks, permission testing, custom field handling, duplicate protection, retry logic, and clear logging.

If manual creation is slowing your team down, begin with one focused workflow. Create a test issue, verify every field, then expand carefully. Whether you continue with Jira or evaluate a platform such as ONES.com, a clear workflow will produce better results than a rushed integration.