As a primer for sending Backlog API requests, please see Basic intro to sending Backlog API requests.
Adding an issue via Backlog API
According to the Backlog API documentation, the minimum required information to add an issue via API are:
- project id (number)
- summary (the title of the issue; string)
- issueTypeId (number)
- priorityId (number)
These are documented under Form Parameters in the Add Issues documentation.
To get the required info, we can use CURL to send requests to Backlog API.
Get project id:
Get project id path: /api/v2/projects/[project key]
Example:
curl https://xx.backlog.com/api/v2/projects/COMDEMO?apiKey=abcdefghijklmn
The JSON response will be like:
{
"id":33368,
"projectKey":"COMDEMO",
"name":"ComDemo",
"chartEnabled":true,
"subtaskingEnabled":true,
"projectLeaderCanEditProjectLeader":true,
"useWikiTreeView":true,
"textFormattingRule":"markdown",
"archived":false,
"displayOrder":2147483646,
"useDevAttributes":true
}
So the project id is 33368. We will need it later to send the request to add issues to this project.
Get list of issue types from the project:
Get issue types path: /api/v2/projects/[project id or key]/issueTypes
Example:
curl https://xx.backlog.com/api/v2/projects/COMDEMO/issueTypes?apiKey=abcdefghijklmn
This will return a JSON response containing a list (i.e. array) of issue types of the project:
[
{"id":140151,"projectId":33368,"name":"Task","color":"#7ea800","displayOrder":0,"templateSummary":null,"templateDescription":null},
{"id":140150,"projectId":33368,"name":"Bug","color":"#990000","displayOrder":1,"templateSummary":null,"templateDescription":null},
{"id":140152,"projectId":33368,"name":"Request","color":"#ff9200","displayOrder":2,"templateSummary":null,"templateDescription":null},
{"id":140153,"projectId":33368,"name":"Other","color":"#2779ca","displayOrder":3,"templateSummary":null,"templateDescription":null}
]
If we want to add a Task issue, we will use the id number 140151.
Get priority list:
Get priority list path: /api/v2/priorities
Example:
curl https://xx.backlog.com/api/v2/priorities?apiKey=abcdefghijklmn
This will return a list of id numbers that correspond to priorities: High, Normal, Low.
For example:
[
{
"id": 2,
"name": "High"
},
{
"id": 3,
"name": "Normal"
},
{
"id": 4,
"name": "Low"
}
]
Sending the CURL POST request to Backlog API to add an issue
With the required information we’ve obtained earlier, we can build a JSON form body/file to add the issue.
For example, the JSON code will contain the minimum required parameters:
{
"projectId":33368,
"summary":"This is the title/subject of the issue",
"issueTypeId":140151,
"priorityId":3
}
The Add issues path is /api/v2/issues
So, the curl POST command will be:
curl -X POST https://spaceid.backlog.com/api/v2/issues?apiKey=abcdefghijklmn -H 'Content-Type: application/json'
-d '{
"projectId":33368,
"summary":"This is the title/subject of the issue",
"issueTypeId":140151,
"priorityId":3
}'
When successful, this will return an HTTP 201 response code indicating that we have added the task to the specified project. The response body will also contain more information about the issue.
Example using reqbin to send a CURL POST JSON request:
If we want to add other info, e.g. the issue description or assignee, etc., we can add additional parameters in the JSON code when we send the request to Backlog API.
Important edit: Adding issues with custom fields
I realized that I’d made an error about adding issues above, my apologies. The form parameters as documented in the Backlog API is
Content-Type:application/x-www-form-urlencoded
This means the data to be sent should not be in JSON format. But in the format:
curl -X POST https://[spaceid].backlog.com/api/v2/issues?apiKey=[yourAPIkey]
-H “Content-Type: application/x-www-form-urlencoded”
-d “param1=value1¶m2=value2”
This is important if you are adding issues with custom fields to be filled.
