How to manage attachment categories via REST API

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

These API requests are supported in Smart Attachments 1.16.0 and its newer versions.

Global parameters passed in each request

These parameters are used globally for all cURL requests.

Parameter	Description
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"

CODE

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

Parameter

Description

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"

CODE

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/category" --data "projectKey=KEY&name=CategoryName&groups=groupName&users=username&roles=roleId&issueTypes=IssutTypeId"

CODE

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

Parameter	Description
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	ID of project roles that will have access to the category with attachments. For the details on how to fetch ID of 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/category" --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"

CODE

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 PUT "JIRA.baseURL/rest/attach-cat/1.0/project/category" --data "projectKey=KEY&catId=categoryId&name=CategoryName&groups=groupName&users=username&roles=roleId&issueTypes=IssutTypeId"

CODE

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

Parameter	Description
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 update.
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	ID of project roles that will have access to the category with attachments. For the details on how to fetch ID of 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 PUT "https://yourjira.com/rest/attach-cat/1.0/project/category" --data "projectKey=SMART&catId=2&name=Documents for Review&issueTypes=10000&issueTypes=10001&issueTypes=10003&groups=jira-administrators&groups=jira-users&users=admin&users=astone&roles=10002&roles=10003"

CODE

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/category?projectKey=PROJECT_KEY"

CODE

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

Parameter	Description
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/category?projectKey=SMART"

CODE

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

{
   "categories":[
      {
         "id":0,
         "name":"Uncategorized",
         "position":0,
         "groups":[],
         "roles":[],
         "issueTypes":[],
         "users":[],
         "userPosition":{}
      },
      {
         "id":1,
         "name":"Docs",
         "position":1,
         "groups":["jira-administrators"],
         "roles":[10002],
         "issueTypes":[10000],
         "users":["admin"],
         "userPosition":{}
      }
   ],
   "disabled":false,
   "imageSize":100,
   "formDropZones":true
}

CODE

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 DELETE "JIRA.baseURL/rest/attach-cat/1.0/project/category" --data "projectKey=KEY&catId=categoryId"

CODE

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

Parameter	Description
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 DELETE "https://yourjira.com/rest/attach-cat/1.0/project/category" --data "projectKey=SMART&catId=2"

CODE

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 PUT "JIRA.baseURL/rest/attach-cat/1.0/project/category" --data "projectKey=KEY&catId=categoryId&name=categoryName&issueTypes=issueTypeId&issueTypes=IssutTypeId"

CODE

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

Parameter	Description
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 PUT "https://yourjira.com/rest/attach-cat/1.0/project/category" --data "projectKey=SMART&catId=2&name=Screenshots&issueTypes=10000&issueTypes=10001&issueTypes=10003"

CODE

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 PUT "JIRA.baseURL/rest/attach-cat/1.0/project/category" --data "projectKey=KEY&catId=categoryId&name=categoryName&groups=groupName&users=username&roles=roleId"

CODE

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

Parameter	Description
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	ID of Project roles that will have access to the category with attachments. For the details on how to fetch ID of project roles, please refer to Atlassian documentation.

Here you can see an example of the request:

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

CODE

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

Download PDF

How to manage attachment categories via REST API

Global parameters passed in each request

Enabling/Disabling the Add-on for JIRA Project

Adding a New Attachment Category in the Project

Updating the Attachment Category in the Project

Fetching attachment categories for the specific project

Deleting the Attachment Category in the Project

Setting Issue Types for the Category

Setting Access Restrictions for the Category

Cookie Notice

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

Global parameters passed in each request

Enabling/Disabling the Add-on for JIRA Project

Adding a New Attachment Category in the Project

Updating the Attachment Category in the Project

Fetching attachment categories for the specific project

Deleting the Attachment Category in the Project

Setting Issue Types for the Category

Setting Access Restrictions for the Category

Cookie Notice