Tell us how you use Jira Service Desk and get a Starbucks gift card for this! Share your experience to help us design a new solution for efficient communication with customers!
Skip to end of metadata
Go to start of metadata

REST API methods are not available in Smart Attachments 2.X+ versions. Please use Java API instead.


Please see this page for new API requests. These requests are applicable if you are using Smart Attachment 1.15.3 or its older versions.



Subscribe to receive notifications about changes in REST API of Smart Attachments

* indicates required

Global parameters passed in each request

These parameters are used globally for all cURL requests.

ParameterDescription
username
Username for accessing JIRA instance.
password
Password for accessing JIRA instance.
JIRA.baseURL
Base URL of JIRA instance.

Enabling/Disabling the Add-on for JIRA Project

You can enable or disable Smart Attachments add-on for a specific JIRA project.

The pattern of request looks like this:

curl -D- -u username:password --request POST "JIRA.baseURL/rest/attach-cat/1.0/project/disable" --data "projectKey=KEY&disable=false"

In this request you need to specify the correct values for the following parameters:

ParameterDescription
projectKey
Key of the JIRA project which you want to enable or disable the add-on for.
disable

Determines the status of the add-on for the current project. It may take accept two values:

  • true - disables the add-on for the project.
  • false - enables the add-on for the project.

Here you can see an example of the request:

curl -D- -u admin:admin --request POST "https://yourjira.com/rest/attach-cat/1.0/project/disable" --data "projectKey=SMART&disable=false"

Adding a New Attachment Category in the Project

You can create new attachment categories in the JIRA project. Before doing this, you need to enable the add-on for the current JIRA project.

You can add only one category per request.

The pattern of request looks like this:

curl -D- -u username:password --request POST "JIRA.baseURL/rest/attach-cat/1.0/project/add" --data "projectKey=KEY&name=CategoryName&groups=groupName&users=username&roles=roleId&issueTypes=IssutTypeId"

In this request you need to specify the correct values for the following parameters:

ParameterDescription
projectKey
Key of the JIRA project which you want to enable or disable the add-on for.
name
Name of a new category you want to add.
groups
Groups that will have access to the category with attachments. For the details on how to fetch user groups, please refer to Atlassian documentation.
users
Usernames of people who will have access to the category with attachments. For the details on how to fetch users, please refer to Atlassian documentation .
roles
Project roles that will have access to the category with attachments. For the details on how to fetch project roles, please refer to Atlassian documentation .
issueTypes
ID of the issue type where a specific category is displayed. For the details on how to fetch ID's of issue types, please refer to Atlassian documentation.

Here you can see an example of the request:

curl -D- -u admin:admin --request POST "https://yourjira.com/rest/attach-cat/1.0/project/add" --data "projectKey=SMART&name=Documents for Review&issueTypes=10000&issueTypes=10001&issueTypes=10003&groups=jira-administrators&groups=jira-users&users=admin&users=astone&roles=10002&roles=10003"

As a response, you will receive the id of a newly created category.

Updating the Attachment Category in the Project

Please note that the current API request will overwrite the existing configuration with a new one. So if you need to add new values, you need to include old values too.

You can update the existing attachment categories in the JIRA project. Before doing this, you need to enable the add-on for the current JIRA project.

You can update only one category per request.

The pattern of request looks like this:

curl -D- -u username:password --request POST "JIRA.baseURL/rest/attach-cat/1.0/project/update" --data "projectKey=KEY&name=CategoryName&groups=groupName&users=username&roles=roleId&issueTypes=IssutTypeId"

In this request you need to specify the correct values for the following parameters:

ParameterDescription
projectKey
Key of the JIRA project which you want to enable or disable the add-on for.
name
Name of a new category you want to add.
groups
Groups that will have access to the category with attachments. For the details on how to fetch user groups, please refer to Atlassian documentation.
users
Usernames of people who will have access to the category with attachments. For the details on how to fetch users, please refer to Atlassian documentation .
roles
Project roles that will have access to the category with attachments. For the details on how to fetch project roles, please refer to Atlassian documentation .
issueTypes
ID of the issue type where a specific category is displayed. For the details on how to fetch ID's of issue types, please refer to Atlassian documentation.

Here you can see an example of the request:

curl -D- -u admin:admin --request POST "https://yourjira.com/rest/attach-cat/1.0/project/update" --data "projectKey=SMART&name=Documents for Review&issueTypes=10000&issueTypes=10001&issueTypes=10003&groups=jira-administrators&groups=jira-users&users=admin&users=astone&roles=10002&roles=10003"

As a response, you will receive the id of the edited category.

Fetching attachment categories for the specific project

You can get the list of attachment categories configured for the specific JIRA project.

The pattern of request looks like this:

curl -D- -u username:password --request GET "JIRA.baseUrl/rest/attach-cat/1.0/project/get?projectKey=PROJECT_KEY"

In this request you need to specify the correct value for the following parameter:

ParameterDescription
projectKey
Key of the JIRA project which you want to get the list of categories.

Here you can see an example of the request:

curl -D- -u admin:admin --request GET "https://yourjira.com/rest/attach-cat/1.0/project/get?projectKey=SMART"

As a response, you will receive the following JSON string:

{"categories":[
    {
        "id":1,
        "name":"Documents",
        "groups":[],
        "roles":[],
        "users":[],
        ...
    },
    {
        "id":2,
        "name":"Logs",
        "groups":["jira-developers"],
        "roles":[],
        "users":["user1", "user2"],
        ...
    },
    ...
}

Deleting the Attachment Category in the Project 

You can delete the attachment categories in the JIRA project. Before doing this, you need to enable the add-on for the current JIRA project and have at least one category for deletion.

You can delete only one category per request.

The pattern of request looks like this:

curl -D- -u username:password --request POST "JIRA.baseURL/rest/attach-cat/1.0/project/remove" --data "projectKey=KEY&catId=categoryId"

In this request you need to specify the correct values for the following parameters:

ParameterDescription
projectKey
Key of the JIRA project which you want to enable or disable the add-on for.
catId
ID of the category in JIRA project you want to delete.

Here you can see an example of the request:

curl -D- -u admin:admin --request POST "https://yourjira.com/rest/attach-cat/1.0/project/remove" --data "projectKey=SMART&catId=2"

No response is returned.

Setting Issue Types for the Category

Please note that the current API request will overwrite the existing configuration with a new one. So if you need to add additional issue types, you need to include ID's of the already used categories.

You can specify the issue types which attachment categories are displayed in.

curl -D- -u username:password --request POST "JIRA.baseURL/rest/attach-cat/1.0/project/update" --data "projectKey=KEY&catId=categoryId&name=categoryName&issueTypes=issueTypeId&issueTypes=IssutTypeId"

In this request you need to specify the correct values for the following parameters:

ParameterDescription
projectKey
Key of the JIRA project which you want to update issue types for showing a specific category in.
catId
ID of the category which you want to update issue types in.
name
Name of the category which you want to update issue types in.
issueTypes
ID of the issue type where a specific category is displayed. For the details on how to fetch ID's of issue types, please refer to Atlassian documentation.

Here you can see an example of the request:

curl -D- -u admin:admin --request POST "https://yourjira.com/rest/attach-cat/1.0/project/update" --data "projectKey=SMART&catId=2&name=Screenshots&issueTypes=10000&issueTypes=10001&issueTypes=10003"

No response is returned. All the issue types not registered in the project settings are skipped.

Setting Access Restrictions for the Category

Please note that the current API request will overwrite the existing configuration with a new one. You need to include the old values along with the new users, user groups and project roles.

You can specify the issue types which attachment categories are displayed in.

curl -D- -u username:password --request POST "JIRA.baseURL/rest/attach-cat/1.0/project/update" --data "projectKey=KEY&catId=categoryId&name=categoryName&groups=groupName&users=username&roles=roleId"

In this request you need to specify the correct values for the following parameters:

ParameterDescription
projectKey
Key of the JIRA project which you want update issue types for showing a specific category.
catId
ID of the category which you want to update access restrictions for.
name
Name of the category which you want to access restrictions for.
groups
Groups that will have access to the category with attachments. For the details on how to fetch user groups, please refer to Atlassian documentation.
users
Usernames of people who will have access to the category with attachments. For the details on how to fetch users, please refer to Atlassian documentation .
roles
Project roles that will have access to the category with attachments. For the details on how to fetch project roles, please refer to Atlassian documentation .

Here you can see an example of the request:

curl -D- -u admin:admin --request POST "https://yourjira.com/rest/attach-cat/1.0/project/update" --data "projectKey=PCE&catId=2&name=Screenshots&groups=jira-administrators&groups=jira-users&users=admin&users=astone&roles=10002&roles=10003"

No response is returned. All the unavailable or non-existing users, user groups and project roles are skipped.

  • No labels