Jira Cloud REST API: 5 Steps for Making Your First Call
Ready to make your first Jira Cloud API call? Follow 5 steps to use the jira rest api cloud, test requests, and troubleshoot errors. Read now.
Connecting an app to Jira Cloud can feel complicated when you’re facing unfamiliar endpoints, authentication rules, and JSON responses. One misplaced URL or expired token can turn a simple test into a frustrating debugging session.
But here's the truth: your first Jira Cloud REST API call can be a small, read-only request that confirms your connection. Then you can build toward useful actions, such as checking a project or creating an issue. Here’s a practical five-step walkthrough, with examples you can adapt safely. You’ll also learn how to handle common errors and protect your credentials before expanding an integration.
How to Make Your First Jira Cloud REST API Call in 5 Steps
Start with a request that reads your Jira account profile. You’ll need your site address, Atlassian account email, and an API token. This GET request verifies authentication without changing project information.
-

1. Find Your Jira Cloud Site Address
Your site address usually follows this format: https://your-domain.atlassian.net. Replace your-domain with the actual Atlassian site name used by your team.
For example, if your site is acme.atlassian.net, the profile endpoint is https://acme.atlassian.net/rest/api/3/myself. Keep the base address separate from the endpoint so you can reuse it for other calls.
-
2. Create an Atlassian API Token
Sign in to your Atlassian account and create an API token in its security settings. Give the token a clear label, such as “Local API test,” so you can recognize its purpose later.
For basic authentication with Jira Cloud, use your Atlassian account email as the username and the API token as the password. Don’t use your regular account password in a script.
Store the token in a secure environment variable or secret manager. Avoid placing it in a URL, sharing it in chat, or committing it to a code repository.
-
3. Send a Small Authentication Test
Use curl to make a GET request to the profile endpoint. The command below reads credentials from environment variables rather than exposing them directly in the command.
curl --request GET \
--url "$JIRA_BASE_URL/rest/api/3/myself" \
--user "$JIRA_EMAIL:$JIRA_API_TOKEN" \
--header "Accept: application/json"
Set JIRA_BASE_URL, JIRA_EMAIL, and JIRA_API_TOKEN in your environment before running the command. A successful response returns profile information in JSON.
Here's why: this request isolates the connection and authentication from project-specific permissions. If it succeeds, you know the address and credentials work for a basic account request.
-
4. Try a Project Search Request
Once the profile request works, check whether your account can access a project. Jira Cloud provides a project search endpoint at /rest/api/3/project/search.
curl --request GET \
--url "$JIRA_BASE_URL/rest/api/3/project/search?maxResults=10" \
--user "$JIRA_EMAIL:$JIRA_API_TOKEN" \
--header "Accept: application/json"
The response includes project details you can inspect, such as project keys and names. A project key like OPS is often needed when you create an issue.
If you receive an empty result, your account may lack access to visible projects. Ask a Jira administrator to confirm your project permissions before changing the request.
-
5. Create a Test Issue When You’re Ready
A POST request creates an issue, so use a test project and confirm your permissions first. Jira requires fields such as a project key, summary, and issue type. Your project configuration may require additional fields.
curl --request POST \
--url "$JIRA_BASE_URL/rest/api/3/issue" \
--user "$JIRA_EMAIL:$JIRA_API_TOKEN" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
"fields": {
"project": { "key": "OPS" },
"summary": "API connection test",
"issuetype": { "name": "Task" },
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{ "type": "text", "text": "Created through a Jira Cloud REST API test." }
]
}
]
}
}
}'
For Jira Cloud API version 3, issue descriptions use Atlassian Document Format. Replace OPS with a project key you can access, and use an issue type available in that project.
A successful issue creation typically returns HTTP status 201 and an issue key. Save that key so you can check the new issue or clean it up after testing.
Understand the Parts of a Jira API Request
A REST request combines a base URL, an endpoint, an HTTP method, authentication, and sometimes a JSON body. For example, GET /rest/api/3/myself reads profile details, while POST /rest/api/3/issue creates an issue.
Think of the endpoint as the destination and the method as the action. A GET request is a safe starting point because it reads information. A POST request can create or change information, so test it carefully.
The version number matters. Jira Cloud’s platform API version 3 uses endpoints beginning with /rest/api/3. Some older examples use version 2, so check the endpoint before adapting a snippet.
JSON responses can include more fields than you need. Start by inspecting the status code and a few relevant values, such as a project key or issue identifier. You can refine your code after confirming the response shape.
Choose Endpoints and Permissions Carefully
Jira has endpoints for issues, projects, users, comments, and many other operations. Choose the narrowest endpoint that completes your task. A project lookup is a better first test than an issue-creation script that changes several fields.
Permissions affect what an authenticated request can see or change. A valid token does not automatically grant access to every project. For example, a teammate may be able to read the OPS project but lack permission to create issues there.
Use the account that will run the integration, and ask an administrator to confirm its project access. This helps you avoid confusing a permission problem with an authentication failure.
You might be wondering: should you use an API token or OAuth? An API token can suit a personal script or a controlled internal test. OAuth is often a better fit for an app that needs user consent and a managed authorization flow.
Read Responses and Diagnose Common Errors
Check the HTTP status code before relying on the response body. A successful GET request usually returns a 2xx status, while a successful issue creation commonly returns 201.
| Response | What to check |
401 Unauthorized | Confirm the account email, token, and site address. Create a replacement token if the current one has expired or been revoked. |
403 Forbidden | Check whether the account has the permission required for that project or action. |
404 Not Found | Verify the site address, endpoint path, and project key. Some inaccessible resources may also appear unavailable. |
400 Bad Request | Inspect the JSON body, required fields, issue type, and project configuration. |
429 Too Many Requests | Reduce request frequency and respect any retry guidance returned with the response. |
For example, a 400 response during issue creation may point to a missing required field. A 401 response usually calls for checking credentials before rewriting the request body.
Keep a short record of the endpoint, method, status code, and non-sensitive error details during testing. Never include an API token in a shared error report.
Protect Credentials and Make Integrations Reliable
Treat an API token like a password. Keep it out of browser code, public repositories, screenshots, and logs. If it appears in an unsafe place, revoke it and create a replacement.
For a production integration, add timeouts and handle failed requests deliberately. If Jira returns a rate-limit response, pause before retrying instead of sending repeated requests immediately.
Also consider what the integration should do when a request partially succeeds. For example, if your system creates an issue but fails to record its key, retrying blindly could create duplicates. Store the returned issue key and design a safe recovery path.
The best part? You don’t need a large integration to learn the fundamentals. A profile lookup, a project search, and one controlled issue creation can teach you how authentication, permissions, and responses fit together.
Project Management Beyond API Calls: ONES.com
API calls can connect systems and automate specific tasks. If your larger challenge is coordinating project work and team knowledge, ONES.com offers a separate platform to consider. It doesn’t form part of the Jira API request, and this guide makes no claim that ONES endpoints are interchangeable with Jira endpoints.

Value Proposition
ONES.com brings project management and knowledge management together in one AI-powered platform. ONES Project is a Jira alternative for project management, while ONES Wiki supports team knowledge management as a Confluence alternative; they’re sold separately.
Core Capabilities
- Pain: Your team relies on several disconnected work systems. ONES capability: ONES.com combines project and knowledge management in one platform. Result: Teams can coordinate project activity and shared working knowledge in a unified environment.
- Pain: Your project workflow is difficult to adapt. ONES capability: ONES Project supports custom workflows and fields. Result: Teams can shape work stages and issue details around their process.
- Pain: Jira migration concerns make alternatives harder to evaluate. ONES capability: ONES Project supports Jira-compatible workflows. Result: Teams can assess a Jira alternative while retaining familiar workflow patterns.
- Pain: Teams depend on many add-ons for everyday project work. ONES capability: Built-in reporting, automation, and sprint management cover common project needs. Result: Teams may be able to reduce plugin dependence for those tasks.
- Pain: Hosting requirements limit platform choices. ONES capability: Deployment options include Cloud, On-Premise, Private Cloud, and Air-gapped environments. Result: You can evaluate a setup that fits your operating requirements.
- Pain: Self-hosting can raise concerns about feature differences. ONES capability: Cloud and self-hosted versions have full feature parity. Result: Teams can compare deployment models without choosing between feature sets.
- Pain: A team wants to assess the platform before wider adoption. ONES capability: The free plan supports up to 30 seats. Result: A small group can evaluate how the platform fits its work.
- Pain: Project delivery and team knowledge are handled separately. ONES capability: ONES Wiki provides a knowledge-management option alongside ONES Project. Result: Teams can choose project management, knowledge management, or both as separate products.
Application Scenarios
A software team with custom issue states could evaluate ONES Project’s Jira-compatible workflows, custom fields, sprint management, and built-in reporting. It can compare those capabilities with its existing process before deciding whether to change platforms.
A company with strict hosting requirements could assess On-Premise, Private Cloud, or Air-gapped deployment. A distributed team that wants project planning alongside team knowledge management could evaluate ONES Project and ONES Wiki separately.
Common Challenges When Making Your First Call
- Authentication fails: Confirm that you’re using the Atlassian account email and API token together. Check that your environment variables contain the current values, then test the profile endpoint again.
- The project search returns no results: Confirm that the authenticated account can view a project. Ask a Jira administrator to check access if the project should be visible.
- Issue creation returns a validation error: Check required fields and permitted issue types for the selected project. Jira project configurations can require fields beyond the example.
- A token appears in a log or shared message: Revoke the exposed token, create a new one, and update the integration’s secure credential storage.
FAQs About the Jira Cloud REST API
What is the Jira Cloud REST API?
The Jira Cloud REST API is a web interface that lets applications interact with Jira Cloud through HTTP requests. You can use endpoints to read information or perform permitted actions, such as creating an issue. Requests typically include an endpoint, an HTTP method, authentication, and sometimes a JSON body. For Jira Cloud platform API version 3, endpoints commonly begin with /rest/api/3.
How do I authenticate a basic Jira Cloud API request?
For a simple script, Jira Cloud supports basic authentication using your Atlassian account email and an API token. Pass those credentials through a secure mechanism, such as environment variables, rather than embedding them in a URL or public code. For apps that need a managed user authorization flow, investigate OAuth and choose the approach that fits your app.
Why am I getting a 401 or 403 response?
A 401 response usually indicates that Jira could not authenticate the request. Check the site address, email, and API token. A 403 response generally means the account lacks permission for the requested action. For example, your account may be able to search projects but not create issues. Check the relevant project permissions with an administrator.
Can I use the Jira Cloud REST API to create an issue?
Yes. Send a POST request to /rest/api/3/issue with a JSON body containing the required issue fields. Common fields include a project key, summary, and issue type. Your Jira project may require additional fields, and version 3 uses Atlassian Document Format for issue descriptions. Test in a project where you have permission to create issues.
Conclusion
Your first Jira Cloud API call is easiest to troubleshoot when you start small. Confirm your site address, create a token, test the profile endpoint, and move on to project searches or issue creation when authentication works.
If a call fails, check the status code, credentials, endpoint, and project permissions before changing several things at once. That steady approach turns an unfamiliar API into a practical tool for your team’s workflow.