JIRA REST API
People click buttons to work in JIRA. Programs need another doorway. The JIRA REST API gives scripts, apps, and tools a standard way to read and change JIRA data without a browser. A script can create hundreds of issues in seconds or pull data for a custom report.
Layman's View: A Restaurant Waiter
A diner never walks into the kitchen. A waiter carries the order to the kitchen and brings the food back. The API plays the waiter. A program places a request, JIRA prepares the answer, and the API returns it.
Your Script --- HTTP request ---> JIRA API ---> JIRA data Your Script <--- JSON response --- JIRA API <--- JIRA data
Key Terms
REST API Vocabulary
| Term | Plain Meaning |
|---|---|
| Endpoint | A web address that handles one kind of request |
| HTTP Method | The action: read, create, update, or delete |
| JSON | A simple text format that stores data in labelled pairs |
| Authentication | Proof of who sends the request |
| Status Code | A number that reports success or failure |
HTTP Methods
Methods and Their Jobs
| Method | Action | JIRA Example |
|---|---|---|
| GET | Read data | Fetch one issue |
| POST | Create data | Create a new issue |
| PUT | Update data | Change an issue summary |
| DELETE | Remove data | Delete a comment |
Authentication
Every request must prove identity. JIRA Cloud accepts an email address paired with an API token. JIRA Data Center accepts personal access tokens. Tokens act like passwords. Keep them out of public code, shared screenshots, and chat messages.
Common Endpoints
The paths below follow the JIRA Cloud version 3 pattern. Check the current Atlassian documentation for the latest paths, especially for search.
Frequently Used Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /rest/api/3/issue/PROJ-1 | Read issue PROJ-1 |
| POST | /rest/api/3/issue | Create an issue |
| PUT | /rest/api/3/issue/PROJ-1 | Edit issue PROJ-1 |
| POST | /rest/api/3/issue/PROJ-1/comment | Add a comment |
| GET | /rest/api/3/project | List projects |
Sample Request
A single command reads an issue. Replace the email, token, and site name with real values.
curl -u you@example.com:API_TOKEN \ -H "Accept: application/json" \ https://your-site.atlassian.net/rest/api/3/issue/PROJ-1
JIRA replies with JSON that holds the key, summary, status, and many other fields.
{
"key": "PROJ-1",
"fields": {
"summary": "Login button not working",
"status": { "name": "In Progress" }
}
}
Creating an Issue
A POST request to the issue endpoint carries a JSON body with the project, summary, and issue type.
{
"fields": {
"project": { "key": "PROJ" },
"summary": "Login button not working",
"issuetype": { "name": "Bug" }
}
}
Status Codes
Response Codes to Know
| Code | Meaning |
|---|---|
| 200 | Request succeeded |
| 201 | New item created |
| 400 | Request has a mistake, such as a missing field |
| 401 | Login details failed |
| 403 | Account lacks permission |
| 404 | Item does not exist |
| 429 | Too many requests in a short time |
Popular Uses
- Importing hundreds of issues from a spreadsheet.
- Syncing JIRA with another tracking system.
- Building custom dashboards outside JIRA.
- Creating issues from monitoring alerts or chat messages.
Safe Practices
- Create a dedicated account with only the permissions the script needs.
- Test new scripts in a sandbox project before touching live data.
- Slow down loops when the API returns code 429.
- Rotate tokens on a regular schedule and remove tokens nobody uses.
Summary
The REST API lets programs talk to JIRA through web requests. Methods define the action, endpoints define the target, and JSON carries the data. Tokens prove identity and demand careful handling. Small scripts built on these pieces automate imports, reports, and syncs.