Endpoint Documentation

This is the static documentation for the REST-API of Customfield Editor for Jira.

Endpoints

The baseUrl of the REST API might be one of the following URLs on your Jira instance:

  • http[s]://server:port/jira/rest/jiracustomfieldeditorplugin/1/*

  • http[s]://server:port/rest/jiracustomfieldeditorplugin/1/*

You need to use Basic Authentication for every request to the API.

admin-operations

List all available customfields. Not all of them will be editable with the Customfield Editor Plugin. See User Guide for supported FieldTypes.   DEPRECATED: When no parameters are specified the result looks like this (backwards-compatibility) and will return ALL customfields without pagination or limit:

[
  {
    "fieldId": 10002,
    "fieldName": "my super field",
    "fieldType": "cascadingselect",
    "fieldDescription": "awesome"
  }
]

 

NEW: You should instead use the new approach with pagination and filtering, which will return fields wrapped inside a values: [] array. The following example was performed with these parameters ?startAt=0&maxResults=10&orderBy=fieldName:

{
  "maxResults": 10,
  "startAt": 0,
  "total": 1,
  "processingTimeInMs": 48,
  "values": [
    {
      "fieldId": 10002,
      "fieldName": "my super field",
      "fieldType": "cascadingselect",
      "fieldDescription": "awesome",
      "globalPermission": {
        "userlist": [
          "bob",
          "steve"
        ],
        "grouplist": [
          "jira-administrators",
          "jira-system-administrators"
        ]
      },
      "contextPermissions": [
        {
          "context": {
            "contextId": 10127,
            "contextName": "Defaultconfigscheme für singleselectWithContextsGuiTest",
            "contextDescription": "Von JIRA generiertes Standardkonfigurationsschema",
            "projects": [],
            "issueTypes": []
          },
          "userlist": [
            "linda"
          ],
          "grouplist": []
        },
        {
          "context": {
            "contextId": 10128,
            "contextName": "contextForProjectTest",
            "contextDescription": "contextForProjectTest",
            "projects": [
              {
                "projectId": 10000,
                "projectKey": "TEST",
                "projectName": "test",
                "projectDescription": "test"
              }
            ],
            "issueTypes": []
          },
          "userlist": [
            "chris"
          ],
          "grouplist": []
        }
      ]
    }
  ]
}

 

Pagination is handled the same way as the official JIRA REST API handles it. The startAt parameter indicates which item should be used as the first item in the page of results. The maxResults parameter indicates how many results to return per page. The default is 20. values always contains the items and processingTimeInMs is the time it took to process the request in milliseconds.

{
  "maxResults": 20,
  "startAt": 100,
  "total": 200,
  "processingTimeInMs": 327,
  "values": [ ]
}

 

Ordering is also handled in a standardized way. With ?orderBy=name the order will be ascending. With ?orderBy=+name the order will be ascending. With ?orderBy=-name the order will be descending.   Filtering is also handled in a standardized way. With ?filter=foo the result will be filtered on the server for the value.   You need to be administrator or system administrator to use this endpoint.

Version History

  • 2.0.0 - changed: added pagination,filtering,ordering to endpoint (while still keeping backwards compatibility, but deprecating old approach)
  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced
consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
startAttype: query required: false

indicates which item should be used as the first item in the page of results.
integer default:
maxResultstype: query required: false

indicates how many results to return per page.
integer default:
orderBytype: query required: false

defines by what field should be sorted.
string default: fieldName
filtertype: query required: false

filter results by a string e.g. name of an entity.
string default:
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
maxResultsinteger
startAtinteger
totalinteger
processingTimeInMsinteger
valuesarray
array of object
PropertyTypeDescription
fieldIdinteger
fieldNamestring
fieldDescriptionstring
fieldTypestring
contextPermissionsarray
array of object
PropertyTypeDescription
contextobjectCustomFieldContextsModel describes one context of a customField.
object
PropertyTypeDescription
contextIdintegerThe customField's context Id.
contextNamestringThe customField's context name.
contextDescriptionstringThe customField's context description.
projectsarrayJIRA projects associated to this specific context of the customField. Only visible when ?expand=projects is set as URL Parameter.
array of object
PropertyTypeDescription
projectIdintegerThe project's numeric Id.
projectKeystringThe projects's literal key.
projectNamestringThe projects's name.
projectDescriptionstringThe projects's description.
issueTypesarrayJIRA Issue Types associated to this specific context of the customField. Only visible when ?expand=issueTypes is set as URL Parameter.
array of object
PropertyTypeDescription
issueTypeIdstringThe issue types's literal Id.
issueTypeNamestringThe issue types's name.
issueTypeDescriptionstringThe issue types's description.
issueTypeIsSubTaskbooleanIs the issue types a subtask (true).
userlistarray
array of string
grouplistarray
array of string
globalPermissionobject
object
PropertyTypeDescription
userlistarray
array of string
grouplistarray
array of string
{
    "maxResults": 0,
    "startAt": 0,
    "total": 0,
    "processingTimeInMs": 0,
    "values": [
        {
            "fieldId": 0,
            "fieldName": "foo",
            "fieldDescription": "foo",
            "fieldType": "foo",
            "contextPermissions": [
                {
                    "context": {
                        "contextId": 0,
                        "contextName": "foo",
                        "contextDescription": "foo",
                        "projects": [
                            {
                                "projectId": 0,
                                "projectKey": "foo",
                                "projectName": "foo",
                                "projectDescription": "foo"
                            }
                        ],
                        "issueTypes": [
                            {
                                "issueTypeId": "foo",
                                "issueTypeName": "foo",
                                "issueTypeDescription": "foo",
                                "issueTypeIsSubTask": false
                            }
                        ]
                    },
                    "userlist": [
                        "foo",
                        "bar"
                    ],
                    "grouplist": [
                        "foo",
                        "bar"
                    ]
                }
            ],
            "globalPermission": {
                "userlist": [
                    "foo",
                    "bar"
                ],
                "grouplist": [
                    "foo",
                    "bar"
                ]
            }
        }
    ]
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (you must be JIRA administrator).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

You can get permissions of the specified customfield. Will return usernames and groupnames that have global permissions.

 

To get information on the customfield together with permissions set the query-parameter ?expand=field

{
  "userlist": [ "bob" ],
  "grouplist": ["jira-administrators"],
  "field": {
    "fieldId": "10000",
    "fieldName": "Browsers",
    "fieldType": "singleselect",
    "fieldDescription": "A list of all Browsers"
  }
}

 

To get information on associated fullnames for userlist set the query-parameter to ?expand=userlistWithFullnames

{
  "userlist": [ "bob" ],
  "grouplist": ["jira-administrators"],
  "userlistWithFullnames": [
    {
      "username": "bob",
      "fullname": "Bob Bobbington"
      "exists": true
    }
  ]
}

 

To get information on both associated field and fullnames for userlist set the query-parameter to ?expand=field,userlistWithFullnames

{
  "userlist": [ "bob" ],
  "grouplist": ["jira-administrators"],
  "userlistWithFullnames": [
    {
      "username": "bob",
      "fullname": "Bob Bobbington"
      "exists": true
    }
  ],
  "field": {
    "fieldId": "10000",
    "fieldName": "Browsers",
    "fieldType": "singleselect",
    "fieldDescription": "A list of all Browsers"
  }
}

 

Note that the containers will only show up when the corresponding expand parameter is set.
Also note that if you have a big JIRA Installation with many users, the usage of expand parameter can produce higher loads on the JIRA instance.   When the expand parameter is not set the response will look like this:

{
  "userlist": [ "bob" ],
  "grouplist": ["jira-administrators"]
}

 

You need to be administrator or system administrator to use this endpoint.

Version History

  • 2.0.0 - changed: added expand field to expand customfield and full names for userlist
  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.3.0 - changed: Internal change so that normal admins can use endpoint too. Before only system administrators could use it.
  • 1.2.0 - introduced
consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
expandtype: query required: false

You can specify one or more keys as comma separated list
string default:
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
userlistarrayUsernames who have permission.
array of string
grouplistarrayGroupnames who have permission.
array of string
fieldobjectCustomFieldModel describes the properties of a customField.
object
PropertyTypeDescription
fieldIdintegerThe customField Id.
fieldNamestringThe customField name.
fieldTypestringThe customField Type.
fieldDescriptionstringThe customField Description.
userlistWithFullnamesarrayExpand customfield
array of object
PropertyTypeDescription
usernamestring
fullnamestring
existsboolean
avatarstring
{
    "userlist": [
        "foo",
        "bar"
    ],
    "grouplist": [
        "foo",
        "bar"
    ],
    "field": {
        "fieldId": 0,
        "fieldName": "foo",
        "fieldType": "foo",
        "fieldDescription": "foo"
    },
    "userlistWithFullnames": [
        {
            "username": "foo",
            "fullname": "foo",
            "exists": false,
            "avatar": "foo"
        }
    ]
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (you must be JIRA administrator).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

You can submit usernames or groupnames to give global permissions on the specified customfield. Notice: Always provide the full list of usernames and groupnames! You cannot just add a username, what you submit will overwrite the previous values of usernames and groupnames fields. You need to be administrator or system administrator to use this endpoint.

Version History

  • 2.0.0 - changed: Granting permissions for non-existing Groups or Usernames will result in ValidationErrors.
  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.3.0 - changed: Internal change so that normal admins can use endpoint too. Before only system administrators could use it.
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
bodytype: body required: false

Used to save permissions on a customfield. Userlist and grouplist contain usernames and groupnames.
object
PropertyTypeDescription
userlistarrayFull list of Usernames to grant permissions to.
array of string
grouplistarrayFull list of Groupnames to grant permissions to.
array of string
{
    "userlist": [
        "foo",
        "bar"
    ],
    "grouplist": [
        "foo",
        "bar"
    ]
}
customFieldIdtype: path required: true

integer default: 12345
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
{}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (you must be JIRA administrator).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

You can grant or revoke permission for a single username or a single groupname. You can perform this on global permission and context permission level. Existing permissions will not be changed. That means you can simply add a new permission to existing permissions. If the permission you are trying to grant already exists, no duplicates are created and no error is returned. If the permission you are trying to revoke is already revoked, no error is returned.   Example 1: Grant username bob global permission on customfield

{
  "user": "bob",
  "action": "GRANT",
  "type": "GLOBAL"
}

Example 2: Grant username bob context permission on customfield and context 123

{
  "user": "bob",
  "contextId": 123,
  "action": "GRANT",
  "type": "CONTEXT"
}

Example 3: Revoke username bob global permission on customfield

{
  "user": "bob",
  "action": "REVOKE",
  "type": "GLOBAL"
}

Example 4: Revoke username bob context permission on customfield and context 123

{
  "user": "bob",
  "contextId": 123,
  "action": "REVOKE",
  "type": "CONTEXT"
}

Example 5: Grant groupname team-awesome global permission on customfield

{
  "group": "team-awesome",
  "action": "GRANT",
  "type": "GLOBAL"
}

You need to be administrator or system administrator to use this endpoint.

Version History

  • 2.0.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
bodytype: body required: false

PatchCustomFieldPermissionModel is used to grant or revoke single customfield permissions.
object
PropertyTypeDescription
userstringUsername to grant permission to or NULL.
groupstringGroupname to grant permission to or NULL.
actionstringAction is either 'GRANT' or 'REVOKE'.
typestringType is either 'GLOBAL' or 'CONTEXT'.
contextIdintegerContextid is null when type=GLOBAL and set if type=CONTEXT
{
    "user": "foo",
    "group": "foo",
    "action": "foo",
    "type": "foo",
    "contextId": 0
}
customFieldIdtype: path required: true

integer default: 12345
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
{}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (you must be JIRA administrator).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

You can get all contexts of a customfield.

 

To get information on associated projects set the query-parameter ?expand=projects

[
  {
    "contextId": 123,
    "contextName": "foo",
    "contextDescription": "bar",
    "issueTypes": [
      {
        "issueTypeId": "10000",
        "issueTypeName": "Bug",
        "issueTypeDescription": "Bug issue type",
        "issueTypeIsSubTask": false
      }
    ]
  }
]

 

To get information on associated issue types set the query-parameter to ?expand=issueTypes

[
  {
    "contextId": 123,
    "contextName": "foo",
    "contextDescription": "bar",
    "projects": [
      {
        "projectId": 10000,
        "projectKey": "TEST",
        "projectName": "test",
        "projectDescription": "test"
      }
    ]
  }
]

 

To get information on both associated projects and issue types set the query-parameter to ?expand=projects,issueTypes

[
  {
    "contextId": 123,
    "contextName": "foo",
    "contextDescription": "bar",
    "issueTypes": [
      {
        "issueTypeId": "10000",
        "issueTypeName": "Bug",
        "issueTypeDescription": "Bug issue type",
        "issueTypeIsSubTask": false
      }
    ],
    "projects": [
      {
        "projectId": 10000,
        "projectKey": "TEST",
        "projectName": "test",
        "projectDescription": "test"
      }
    ]
  }
]

 

Note that the containers will only show up when the corresponding expand parameter is set.
Also note that if you have a big JIRA Installation with many customFields, projects and issueTypes the usage of expand parameter can produce high loads on the JIRA instance.   When the expand parameter is not set the response will look like this:

[
  {
    "contextId": 123,
    "contextName": "foo",
    "contextDescription": "bar"
  }
]

 

You need to be administrator or system administrator to use this endpoint.

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.5.0 - changed: Added the expand Query-Parameter for projects and issueTypes [CEP-31].
  • 1.3.0 - changed: Internal change so that normal admins can use endpoint too. Before only system administrators could use it.
  • 1.2.1 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
expandtype: query required: false

You can specify one or more keys as comma separated list
string default:
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
array of object
PropertyTypeDescription
contextIdintegerThe customField's context Id.
contextNamestringThe customField's context name.
contextDescriptionstringThe customField's context description.
projectsarrayJIRA projects associated to this specific context of the customField. Only visible when ?expand=projects is set as URL Parameter.
array of object
PropertyTypeDescription
projectIdintegerThe project's numeric Id.
projectKeystringThe projects's literal key.
projectNamestringThe projects's name.
projectDescriptionstringThe projects's description.
issueTypesarrayJIRA Issue Types associated to this specific context of the customField. Only visible when ?expand=issueTypes is set as URL Parameter.
array of object
PropertyTypeDescription
issueTypeIdstringThe issue types's literal Id.
issueTypeNamestringThe issue types's name.
issueTypeDescriptionstringThe issue types's description.
issueTypeIsSubTaskbooleanIs the issue types a subtask (true).
[
    {
        "contextId": 0,
        "contextName": "foo",
        "contextDescription": "foo",
        "projects": [
            {
                "projectId": 0,
                "projectKey": "foo",
                "projectName": "foo",
                "projectDescription": "foo"
            }
        ],
        "issueTypes": [
            {
                "issueTypeId": "foo",
                "issueTypeName": "foo",
                "issueTypeDescription": "foo",
                "issueTypeIsSubTask": false
            }
        ]
    }
]
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (you must be JIRA administrator).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

You can get context permissions of the specified customfield. It will return usernames and groupnames for every context. Notice: If a user has global permissions on a field all context permissions will be overruled.

 

To get information on associated fullnames for userlist set the query-parameter to ?expand=userlistWithFullnames

[
  {
    "contextId": 10007
    "userlist": [ "bob" ],
    "grouplist": ["jira-administrators"]
    "userlistWithFullnames": [
      {
        "username": "bob",
        "fullname": "Bob Bobbington"
        "exists": true
      }
    ]
  }
]

If the user does not exist anymore then exists=false will be set. This should usually not happen since we listen on UserDeleted events and cleanup permissions automatically.   Note that the containers will only show up when the corresponding expand parameter is set.
Also note that if you have a big JIRA Installation with many users, the usage of expand parameter can produce higher loads on the JIRA instance.   When the expand parameter is not set the response will look like this:

[
  {
    "contextId": 10007
    "userlist": [ "bob" ],
    "grouplist": ["jira-administrators"]
  }
]

 

You need to be administrator or system administrator to use this endpoint.

Version History

  • 2.0.0 - changed: added expand field to expand customfield and full names for userlist
  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.3.0 - changed: Internal change so that normal admins can use endpoint too. Before only system administrators could use it.
  • 1.2.1 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
expandtype: query required: false

You can specify one or more keys as comma separated list
string default:
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
array of object
PropertyTypeDescription
contextIdintegerThe customField's context Id.
userlistarrayUsernames who have permission.
array of string
grouplistarrayGroupnames who have permission.
array of string
userlistWithFullnamesarrayExpand customfield
array of object
PropertyTypeDescription
usernamestring
fullnamestring
existsboolean
avatarstring
[
    {
        "contextId": 0,
        "userlist": [
            "foo",
            "bar"
        ],
        "grouplist": [
            "foo",
            "bar"
        ],
        "userlistWithFullnames": [
            {
                "username": "foo",
                "fullname": "foo",
                "exists": false,
                "avatar": "foo"
            }
        ]
    }
]
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (you must be JIRA administrator).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

You can submit usernames or groupnames to give permissions on the specified customfield contexts. Notice: If a user has global permissions on a field all context specific permissions will be overruled. Notice: Always provide the full list with permissions for all contexts otherwise permissions might get overwritten! You need to be administrator or system administrator to use this endpoint.

Version History

  • 2.0.0 - changed: Granting permissions for non-existing Groups or Usernames will result in ValidationErrors.
  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.3.0 - changed: Internal change so that normal admins can use endpoint too. Before only system administrators could use it.
  • 1.2.1 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
bodytype: body required: false

Used to save permissions on customfield contexts.Userlist and grouplist contain usernames and groupnames.
array of object
PropertyTypeDescription
contextIdintegerThe customField's context Id.
userlistarrayFull list of Usernames to grant permissions to.
array of string
grouplistarrayFull list of Groupnames to grant permissions to.
array of string
[
    {
        "contextId": 0,
        "userlist": [
            "foo",
            "bar"
        ],
        "grouplist": [
            "foo",
            "bar"
        ]
    }
]
customFieldIdtype: path required: true

integer default: 12345
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
{}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (you must be JIRA administrator).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

user-operations

List all customfields accessible by the authenticated user. Administrator needs to grant the user permissions on customfields via admin-endpoints first. If the user has no permissions on any customfield the list will be empty. Even jira-administrators need explicit customfield permissions for the user-endpoints.   DEPRECATED: When no parameters are specified the result looks like this (backwards-compatibility) and will return ALL customfields without pagination or limit:

[
  {
    "fieldId": 10002,
    "fieldName": "my super field",
    "fieldType": "cascadingselect",
    "fieldDescription": "awesome"
  }
]

 

NEW: You should instead use the new approach with pagination and filtering, which will return fields wrapped inside a values: [] array. The following example was performed with these parameters ?startAt=0&maxResults=10&orderBy=fieldName:

{
  "maxResults": 10,
  "startAt": 0,
  "total": 1,
  "processingTimeInMs": 48,
  "values": [
    {
      "fieldId": 10002,
      "fieldName": "my super field",
      "fieldType": "cascadingselect",
      "fieldDescription": "awesome",
      "fieldGlobalPermission": true,
      "contexts": [
        {
          "contextId": 10127,
          "contextName": "Defaultconfigscheme für singleselectWithContextsGuiTest",
          "contextDescription": "Von JIRA generiertes Standardkonfigurationsschema",
          "projects": [],
          "issueTypes": []
        },
        {
          "contextId": 10128,
          "contextName": "contextForProjectTest",
          "contextDescription": "contextForProjectTest",
          "projects": [
            {
              "projectId": 10000,
              "projectKey": "TEST",
              "projectName": "test",
              "projectDescription": "test"
            }
          ],
          "issueTypes": []
        }
      ]
    }
  ]
}

 

Pagination is handled the same way as the official JIRA REST API handles it. The startAt parameter indicates which item should be used as the first item in the page of results. The maxResults parameter indicates how many results to return per page. The default is 20. values always contains the items and processingTimeInMs is the time it took to process the request in milliseconds.

{
  "maxResults": 20,
  "startAt": 100,
  "total": 200,
  "processingTimeInMs": 327,
  "values": [ ]
}

 

Ordering is also handled in a standardized way. With ?orderBy=name the order will be ascending. With ?orderBy=+name the order will be ascending. With ?orderBy=-name the order will be descending.   Filtering is also handled in a standardized way. With ?filter=foo the result will be filtered on the server for the value.  

Version History

  • 2.0.0 - changed: added pagination,filtering,ordering to endpoint (while still keeping backwards compatibility, but deprecating old approach)
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
startAttype: query required: false

indicates which item should be used as the first item in the page of results.
integer default:
maxResultstype: query required: false

indicates how many results to return per page.
integer default:
orderBytype: query required: false

defines by what field should be sorted.
string default: fieldName
filtertype: query required: false

filter results by a string e.g. name of an entity.
string default:
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
maxResultsinteger
startAtinteger
totalinteger
processingTimeInMsinteger
valuesarray
array of object
PropertyTypeDescription
fieldIdinteger
fieldNamestring
fieldDescriptionstring
fieldTypestring
fieldGlobalPermissionboolean
contextsarray
array of object
PropertyTypeDescription
contextIdintegerThe customField's context Id.
contextNamestringThe customField's context name.
contextDescriptionstringThe customField's context description.
projectsarrayJIRA projects associated to this specific context of the customField. Only visible when ?expand=projects is set as URL Parameter.
array of object
PropertyTypeDescription
projectIdintegerThe project's numeric Id.
projectKeystringThe projects's literal key.
projectNamestringThe projects's name.
projectDescriptionstringThe projects's description.
issueTypesarrayJIRA Issue Types associated to this specific context of the customField. Only visible when ?expand=issueTypes is set as URL Parameter.
array of object
PropertyTypeDescription
issueTypeIdstringThe issue types's literal Id.
issueTypeNamestringThe issue types's name.
issueTypeDescriptionstringThe issue types's description.
issueTypeIsSubTaskbooleanIs the issue types a subtask (true).
{
    "maxResults": 0,
    "startAt": 0,
    "total": 0,
    "processingTimeInMs": 0,
    "values": [
        {
            "fieldId": 0,
            "fieldName": "foo",
            "fieldDescription": "foo",
            "fieldType": "foo",
            "fieldGlobalPermission": false,
            "contexts": [
                {
                    "contextId": 0,
                    "contextName": "foo",
                    "contextDescription": "foo",
                    "projects": [
                        {
                            "projectId": 0,
                            "projectKey": "foo",
                            "projectName": "foo",
                            "projectDescription": "foo"
                        }
                    ],
                    "issueTypes": [
                        {
                            "issueTypeId": "foo",
                            "issueTypeName": "foo",
                            "issueTypeDescription": "foo",
                            "issueTypeIsSubTask": false
                        }
                    ]
                }
            ]
        }
    ]
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Get one context of customfield accessible by the authenticated user. Administrator needs to grant the user permissions on customfields via admin-endpoints first. If the user has no permissions an error will be returned. Even jira-administrators need explicit customfield permissions for the user-endpoints.

 

You will get info on the field, context and default option. The defaultOption varies depending on the fieldType, have a look at the GET defaultoption endpoint for more details.

Version History

  • 2.4.0 - changed: added authenticatedUserMeta.userAllowedToDeleteOptions Boolean
  • 2.0.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
contextIdtype: path required: true

integer default: 10001
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
fieldIdinteger
fieldNamestring
fieldDescriptionstring
fieldTypestring
contextobjectCustomFieldContextsModel describes one context of a customField.
object
PropertyTypeDescription
contextIdintegerThe customField's context Id.
contextNamestringThe customField's context name.
contextDescriptionstringThe customField's context description.
projectsarrayJIRA projects associated to this specific context of the customField. Only visible when ?expand=projects is set as URL Parameter.
array of object
PropertyTypeDescription
projectIdintegerThe project's numeric Id.
projectKeystringThe projects's literal key.
projectNamestringThe projects's name.
projectDescriptionstringThe projects's description.
issueTypesarrayJIRA Issue Types associated to this specific context of the customField. Only visible when ?expand=issueTypes is set as URL Parameter.
array of object
PropertyTypeDescription
issueTypeIdstringThe issue types's literal Id.
issueTypeNamestringThe issue types's name.
issueTypeDescriptionstringThe issue types's description.
issueTypeIsSubTaskbooleanIs the issue types a subtask (true).
defaultOptionobjectclass used to get the default value of a customfield
object
PropertyTypeDescription
defaultOptionobjectCustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
defaultChildOptionobjectCustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
defaultOptionsarrayThe IDs and names of the options as default values. (null for fieldtypes other than multiselect or multicheckboxes)
array of object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
authenticatedUserMetaobject
object
PropertyTypeDescription
userAllowedToDeleteOptionsboolean
{
    "fieldId": 0,
    "fieldName": "foo",
    "fieldDescription": "foo",
    "fieldType": "foo",
    "context": {
        "contextId": 0,
        "contextName": "foo",
        "contextDescription": "foo",
        "projects": [
            {
                "projectId": 0,
                "projectKey": "foo",
                "projectName": "foo",
                "projectDescription": "foo"
            }
        ],
        "issueTypes": [
            {
                "issueTypeId": "foo",
                "issueTypeName": "foo",
                "issueTypeDescription": "foo",
                "issueTypeIsSubTask": false
            }
        ]
    },
    "defaultOption": {
        "defaultOption": {
            "optionvalue": "foo",
            "id": 0,
            "sequence": 0,
            "disabled": false
        },
        "defaultChildOption": {
            "optionvalue": "foo",
            "id": 0,
            "sequence": 0,
            "disabled": false
        },
        "defaultOptions": [
            {
                "optionvalue": "foo",
                "id": 0,
                "sequence": 0,
                "disabled": false
            }
        ]
    },
    "authenticatedUserMeta": {
        "userAllowedToDeleteOptions": false
    }
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

List all contexts and other information for a specific customfield. The user will only get the contexts he has permissions for.

 

To get information on associated projects set the query-parameter ?expand=projects

[
  {
    "contextId": 123,
    "contextName": "foo",
    "contextDescription": "bar",
    "issueTypes": [
      {
        "issueTypeId": "10000",
        "issueTypeName": "Bug",
        "issueTypeDescription": "Bug issue type",
        "issueTypeIsSubTask": false
      }
    ]
  }
]

 

To get information on associated issue types set the query-parameter to ?expand=issueTypes

[
  {
    "contextId": 123,
    "contextName": "foo",
    "contextDescription": "bar",
    "projects": [
      {
        "projectId": 10000,
        "projectKey": "TEST",
        "projectName": "test",
        "projectDescription": "test"
      }
    ]
  }
]

 

To get information on both associated projects and issue types set the query-parameter to ?expand=projects,issueTypes

[
  {
    "contextId": 123,
    "contextName": "foo",
    "contextDescription": "bar",
    "issueTypes": [
      {
        "issueTypeId": "10000",
        "issueTypeName": "Bug",
        "issueTypeDescription": "Bug issue type",
        "issueTypeIsSubTask": false
      }
    ],
    "projects": [
      {
        "projectId": 10000,
        "projectKey": "TEST",
        "projectName": "test",
        "projectDescription": "test"
      }
    ]
  }
]

 

Note that the containers will only show up when the corresponding expand parameter is set.
Also note that if you have a big JIRA Installation with many customFields, projects and issueTypes the usage of expand parameter can produce high loads on the JIRA instance.   When the expand parameter is not set the response will look like this:

[
  {
    "contextId": 123,
    "contextName": "foo",
    "contextDescription": "bar"
  }
]

 

Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.5.0 - changed: Added the expand Query-Parameter for projects and issueTypes [CEP-31].
  • 1.2.1 - changed: The contexts returned are filtered by context permissions now. If there are no context permissions set, you will still see all contexts.
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
expandtype: query required: false

You can specify one or more keys as comma separated list
string default:
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
array of object
PropertyTypeDescription
contextIdintegerThe customField's context Id.
contextNamestringThe customField's context name.
contextDescriptionstringThe customField's context description.
projectsarrayJIRA projects associated to this specific context of the customField. Only visible when ?expand=projects is set as URL Parameter.
array of object
PropertyTypeDescription
projectIdintegerThe project's numeric Id.
projectKeystringThe projects's literal key.
projectNamestringThe projects's name.
projectDescriptionstringThe projects's description.
issueTypesarrayJIRA Issue Types associated to this specific context of the customField. Only visible when ?expand=issueTypes is set as URL Parameter.
array of object
PropertyTypeDescription
issueTypeIdstringThe issue types's literal Id.
issueTypeNamestringThe issue types's name.
issueTypeDescriptionstringThe issue types's description.
issueTypeIsSubTaskbooleanIs the issue types a subtask (true).
[
    {
        "contextId": 0,
        "contextName": "foo",
        "contextDescription": "foo",
        "projects": [
            {
                "projectId": 0,
                "projectKey": "foo",
                "projectName": "foo",
                "projectDescription": "foo"
            }
        ],
        "issueTypes": [
            {
                "issueTypeId": "foo",
                "issueTypeName": "foo",
                "issueTypeDescription": "foo",
                "issueTypeIsSubTask": false
            }
        ]
    }
]
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

user-default-context-options-operations

List all options of a customfield for the default context. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - changed: URL changed from /customfieldoptions/{customFieldId}; childOptions is no longer returned; Use special childOptions Endpoint instead.
  • 1.1.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

customFieldId of the customField
integer default: 12345
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
array of object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
[
    {
        "optionvalue": "foo",
        "id": 0,
        "sequence": 0,
        "disabled": false
    }
]
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Creates a new option for the customfield in the default context. When creating a new option use the following JSON and do not set sequence and id since they are auto-generated on create.

{
  "optionvalue": "my option value"
}

Option values must be unique. If you create an option with a value that already exists you will recieve a HTTP 400 Validation Error.

{
  "statusCode": 400,
  "subCode": 400000,
  "message": "validation errors",
  "errors": [
    {
      "name": "optionvalue",
      "message": "This option value does already exist. Option values need to be unique."
    }
  ]
}

Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - changed: URL changed from /customfieldoption/{customFieldId}; Request and Response Parameters/Schema mostly unchanged; childOptions removed; sequence is ignored - new options are always placed at the end of the list.
  • 1.1.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
bodytype: body required: false

CustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Updates the properties of an existing option for the customfield in default context. When updating the value of an existing option try to use the following JSON:

{
  "optionvalue": "my option value"
}

When you want to disable an existing option use this JSON:

{
  "disabled": true
}

You should not tamper with sequence, because that can mess up the internal order of all options. If you made some mistakes with sequence then simply use the /sort endpoint. This will repair the internal sequence. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - changed: URL changed from /customfieldoption/{customFieldId}/{optionId}; Request and Response Parameters/Schema mostly unchanged; childOptions removed.
  • 1.1.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
optionIdtype: path required: true

integer default: 123
bodytype: body required: false

CustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Deletes an option of the customfield by its id in default context. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 2.4.0 - changed: added HTTP 403 when global setting 'only administrators can delete options' is active
  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - changed: URL changed from /customfieldoption/{customFieldId}/{optionId}; Request and Response Parameters/Schema unchanged.
  • 1.1.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
optionIdtype: path required: true

integer default: 123
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
idintegerThe ID of the just deleted object.
{
    "id": 0
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Change order for existing option of customfield in default context. Example: You have four options with IDs 10, 20, 30 and 40 which exist in exactly this order

  • If you now want to place option with ID 20 between 30 and 40, then you need to send:

    • Request-URL: POST /user/customfields/123/contexts/default/options/20/move
    • Request-Body: { "after": "30" }
  • There is only one special case for moving an option to the start of the list.
    If you want to move option with ID 40 at the start you need to send:

    • Request-URL: POST /user/customfields/123/contexts/default/options/40/move
    • Request-Body: { "position": "First" }

Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - changed: URL changed from /customfieldoption/{customFieldId}/{optionId}/move; Request and Response Parameters/Schema unchanged.
  • 1.1.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
optionIdtype: path required: true

integer default: 123
bodytype: body required: true

RestfulTableMoveModel is used for drag-and-drop sorting options using the AUI Restfultable. It is advised to not use it. Use the SORT Endpoint instead or you might break the internal order sequence.
object
PropertyTypeDescription
afterstringAfter must contain the optionId to move the option after. In form of "/foo/bar/{optionid}" which is provided that way by AUI Restfultable.You can provide just the optionId too.
positionstringSpecial Case to move an option to the beginning of the option List. Specify position="First". (Notice: if after and position are defined together, after is ignored)
{
    "after": "foo",
    "position": "foo"
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Get the default value for the customfield in default context. The default option is different depending on the field type. For type singleSelect and radioButtons the default value consists of a single option. JSON:

{
  "defaultOption": {
    "optionvalue": "foo",
    "id": 10301,
    "sequence": 0,
    "disabled": false
  }
}

For type cascadingSelect the default value consists of a parentOption and a childOption. JSON:

{
  "defaultOption": {
    "optionvalue": "foo",
    "id": 10200,
    "sequence": 0,
    "disabled": false
  },
  "defaultChildOption": {
    "optionvalue": "bar",
    "id": 10201,
    "sequence": 1,
    "disabled": false
  }
}

For type multiSelect and multiCheckboxes the default value consists of a parentOption and a childOption. JSON:

{
  "defaultOptions": [
    {
      "optionvalue": "foobar",
      "id": 10400,
      "sequence": 1,
      "disabled": false
    },
    {
      "optionvalue": "barfoo",
      "id": 10401,
      "sequence": 2,
      "disabled": false
    }
  ]
}

If no default value is set the response body is JSON:

{ }

Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
defaultOptionobjectCustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
defaultChildOptionobjectCustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
defaultOptionsarrayThe IDs and names of the options as default values. (null for fieldtypes other than multiselect or multicheckboxes)
array of object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "defaultOption": {
        "optionvalue": "foo",
        "id": 0,
        "sequence": 0,
        "disabled": false
    },
    "defaultChildOption": {
        "optionvalue": "foo",
        "id": 0,
        "sequence": 0,
        "disabled": false
    },
    "defaultOptions": [
        {
            "optionvalue": "foo",
            "id": 0,
            "sequence": 0,
            "disabled": false
        }
    ]
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Set the default value for the customfield in default context. The default option is different depending on the field type. For type singleSelect and radioButtons the default value consists of a single option. To set the default value use JSON:

{
  "optionId": 123
}

For type cascadingSelect the default value consists of a parentOption and a childOption. To set the default value use JSON:

{
  "optionId": 123,
  "childOptionId": 567
}

For type multiSelect and multiCheckboxes the default value consists of a parentOption and a childOption. To set the default value use JSON:

{
  "optionIds": [ 12, 34 ]
}

Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
bodytype: body required: true

Model used to set the default value of a customfield. The default value differs by fieldType.
  • A singleSelect/radioButtons fields defaultOption consists of an optionId (optionIds=null,childOptionId=null)
  • A cascadingSelect fields defaultOption consists of an optionId and a childOptionId (optionIds=null)
  • A multiSelect/multiCheckboxes fields defaultOptions consists of multiple optionIds (optionId=null,childOptionId=null)
object
PropertyTypeDescription
optionIdintegerThe ID of the option to be set as default value. (null for fieldtype multicheckboxes and multiselect)
childOptionIdintegerThe ID of the childOption to be set as default value. (null for fieldtypes other than cascadingSelect)
optionIdsarrayThe IDs of the options to be set as default values. (null for fieldtypes other than multiselect or multicheckboxes)
array of integer
{
    "optionId": 0,
    "childOptionId": 0,
    "optionIds": [
        1,
        2,
        3
    ]
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
defaultOptionobjectCustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
defaultChildOptionobjectCustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
defaultOptionsarrayThe IDs and names of the options as default values. (null for fieldtypes other than multiselect or multicheckboxes)
array of object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "defaultOption": {
        "optionvalue": "foo",
        "id": 0,
        "sequence": 0,
        "disabled": false
    },
    "defaultChildOption": {
        "optionvalue": "foo",
        "id": 0,
        "sequence": 0,
        "disabled": false
    },
    "defaultOptions": [
        {
            "optionvalue": "foo",
            "id": 0,
            "sequence": 0,
            "disabled": false
        }
    ]
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Delete the default value for the customfield in default context. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 2.4.0 - changed: added HTTP 403 when global setting 'only administrators can delete options' is active
  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
Response Messages
StatusDescriptionSchema / JSON Example
204Success. Operation was successful. Response has no body.
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Sorts the options alphabetically for the customfield in default context depending on the specified locale. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
bodytype: body required: true

SortModel specifies in which way to sort the options of a customfield.You can sort ascending or descending. The sorting will be locale dependant, so you need to specify a locale like en-US. You can specify an optional collator strength.
object
PropertyTypeDescription
localestringIETF BCP 47 language tag string in form of [a-zA-Z]+-[a-zA-Z]+
strengthstringCollator Strength in form of [A-Z]+
orderstringThe sort order in form of [A-Z]+
{
    "locale": "foo",
    "strength": "foo",
    "order": "foo"
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
{}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

user-specific-context-options-operations

List all options of a customfield for specific context. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

customFieldId of the customField
integer default: 12345
contextIdtype: path required: true

integer default: 678
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
array of object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
[
    {
        "optionvalue": "foo",
        "id": 0,
        "sequence": 0,
        "disabled": false
    }
]
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Creates a new option for the customfield in a specific context. When creating a new option use the following JSON and do not set sequence and id since they are auto-generated on create.

{
  "optionvalue": "my option value"
}

Option values must be unique. If you create an option with a value that already exists you will recieve a HTTP 400 Validation Error.

{
  "statusCode": 400,
  "subCode": 400000,
  "message": "validation errors",
  "errors": [
    {
      "name": "optionvalue",
      "message": "This option value does already exist. Option values need to be unique."
    }
  ]
}

Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
contextIdtype: path required: true

integer default: 678
bodytype: body required: false

CustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Updates the properties of an existing option for the customfield in a specific context. When updating the value of an existing option try to use the following JSON:

{
  "optionvalue": "my option value"
}

When you want to disable an existing option use this JSON:

{
  "disabled": true
}

You should not tamper with sequence, because that can mess up the internal order of all options. If you made some mistakes with sequence then simply use the /sort endpoint. This will repair the internal sequence. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
contextIdtype: path required: true

integer default: 678
optionIdtype: path required: true

integer default: 123
bodytype: body required: false

CustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Deletes an option of the customfield by its id in specific context. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 2.4.0 - changed: added HTTP 403 when global setting 'only administrators can delete options' is active
  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
contextIdtype: path required: true

integer default: 678
optionIdtype: path required: true

integer default: 123
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
idintegerThe ID of the just deleted object.
{
    "id": 0
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Change order for existing option of customfield in specific context. Example: You have four options with IDs 10, 20, 30 and 40 which exist in exactly this order

  • If you now want to place option with ID 20 between 30 and 40, then you need to send:

    • Request-URL: POST /user/customfields/123/contexts/{contextId}/options/20/move
    • Request-Body: { "after": "30" }
  • There is only one special case for moving an option to the start of the list.
    If you want to move option with ID 40 at the start you need to send:

    • Request-URL: POST /user/customfields/123/contexts/{contextId}/options/40/move
    • Request-Body: { "position": "First" }

Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
contextIdtype: path required: true

integer default: 678
optionIdtype: path required: true

integer default: 123
bodytype: body required: true

RestfulTableMoveModel is used for drag-and-drop sorting options using the AUI Restfultable. It is advised to not use it. Use the SORT Endpoint instead or you might break the internal order sequence.
object
PropertyTypeDescription
afterstringAfter must contain the optionId to move the option after. In form of "/foo/bar/{optionid}" which is provided that way by AUI Restfultable.You can provide just the optionId too.
positionstringSpecial Case to move an option to the beginning of the option List. Specify position="First". (Notice: if after and position are defined together, after is ignored)
{
    "after": "foo",
    "position": "foo"
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Get the default value for the customfield in specific context. The default option is different depending on the field type. For type singleSelect and radioButtons the default value consists of a single option. JSON:

{
  "defaultOption": {
    "optionvalue": "foo",
    "id": 10301,
    "sequence": 0,
    "disabled": false
  }
}

For type cascadingSelect the default value consists of a parentOption and a childOption. JSON:

{
  "defaultOption": {
    "optionvalue": "foo",
    "id": 10200,
    "sequence": 0,
    "disabled": false
  },
  "defaultChildOption": {
    "optionvalue": "bar",
    "id": 10201,
    "sequence": 1,
    "disabled": false
  }
}

For type multiSelect and multiCheckboxes the default value consists of a parentOption and a childOption. JSON:

{
  "defaultOptions": [
    {
      "optionvalue": "foobar",
      "id": 10400,
      "sequence": 1,
      "disabled": false
    },
    {
      "optionvalue": "barfoo",
      "id": 10401,
      "sequence": 2,
      "disabled": false
    }
  ]
}

If no default value is set the response body is JSON:

{ }

Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
contextIdtype: path required: true

integer default: 678
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
defaultOptionobjectCustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
defaultChildOptionobjectCustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
defaultOptionsarrayThe IDs and names of the options as default values. (null for fieldtypes other than multiselect or multicheckboxes)
array of object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "defaultOption": {
        "optionvalue": "foo",
        "id": 0,
        "sequence": 0,
        "disabled": false
    },
    "defaultChildOption": {
        "optionvalue": "foo",
        "id": 0,
        "sequence": 0,
        "disabled": false
    },
    "defaultOptions": [
        {
            "optionvalue": "foo",
            "id": 0,
            "sequence": 0,
            "disabled": false
        }
    ]
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Set the default value for the customfield in specific context. The default option is different depending on the field type. For type singleSelect and radioButtons the default value consists of a single option. To set the default value use JSON:

{
  "optionId": 123
}

For type cascadingSelect the default value consists of a parentOption and a childOption. To set the default value use JSON:

{
  "optionId": 123,
  "childOptionId": 567
}

For type multiSelect and multiCheckboxes the default value consists of a parentOption and a childOption. To set the default value use JSON:

{
  "optionIds": [ 12, 34 ]
}

Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
contextIdtype: path required: true

integer default: 678
bodytype: body required: true

Model used to set the default value of a customfield. The default value differs by fieldType.
  • A singleSelect/radioButtons fields defaultOption consists of an optionId (optionIds=null,childOptionId=null)
  • A cascadingSelect fields defaultOption consists of an optionId and a childOptionId (optionIds=null)
  • A multiSelect/multiCheckboxes fields defaultOptions consists of multiple optionIds (optionId=null,childOptionId=null)
object
PropertyTypeDescription
optionIdintegerThe ID of the option to be set as default value. (null for fieldtype multicheckboxes and multiselect)
childOptionIdintegerThe ID of the childOption to be set as default value. (null for fieldtypes other than cascadingSelect)
optionIdsarrayThe IDs of the options to be set as default values. (null for fieldtypes other than multiselect or multicheckboxes)
array of integer
{
    "optionId": 0,
    "childOptionId": 0,
    "optionIds": [
        1,
        2,
        3
    ]
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
defaultOptionobjectCustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
defaultChildOptionobjectCustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
defaultOptionsarrayThe IDs and names of the options as default values. (null for fieldtypes other than multiselect or multicheckboxes)
array of object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "defaultOption": {
        "optionvalue": "foo",
        "id": 0,
        "sequence": 0,
        "disabled": false
    },
    "defaultChildOption": {
        "optionvalue": "foo",
        "id": 0,
        "sequence": 0,
        "disabled": false
    },
    "defaultOptions": [
        {
            "optionvalue": "foo",
            "id": 0,
            "sequence": 0,
            "disabled": false
        }
    ]
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Delete the default value for the customfield in specific context. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 2.4.0 - changed: added HTTP 403 when global setting 'only administrators can delete options' is active
  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
contextIdtype: path required: true

integer default: 678
Response Messages
StatusDescriptionSchema / JSON Example
204Success. Operation was successful. Response has no body.
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Sorts the options alphabetically for the customfield in specific context depending on the specified locale. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
contextIdtype: path required: true

integer default: 678
bodytype: body required: true

SortModel specifies in which way to sort the options of a customfield.You can sort ascending or descending. The sorting will be locale dependant, so you need to specify a locale like en-US. You can specify an optional collator strength.
object
PropertyTypeDescription
localestringIETF BCP 47 language tag string in form of [a-zA-Z]+-[a-zA-Z]+
strengthstringCollator Strength in form of [A-Z]+
orderstringThe sort order in form of [A-Z]+
{
    "locale": "foo",
    "strength": "foo",
    "order": "foo"
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
{}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

user-default-context-child-options-operations

This feature is only available for the customfields with type Cascading Select.
Lists child-options of parent-option for default context. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - changed: URL changed from /customfieldchildoptions/{customfieldid}/{parentoptionid}; Request and Response Parameters/Schema unchanged.
  • 1.1.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
optionIdtype: path required: true

integer default: 123
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
array of object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
[
    {
        "optionvalue": "foo",
        "id": 0,
        "sequence": 0,
        "disabled": false
    }
]
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

This feature is only available for the customfields with type Cascading Select.
Creates a new child-option of a parent-option for the customfield in default context. When creating a new option use the following JSON and do not set sequence and id since they are auto-generated on create.

{
  "optionvalue": "my option value"
}

Option values must be unique. If you create an option with a value that already exists you will recieve a HTTP 400 Validation Error.

{
  "statusCode": 400,
  "subCode": 400000,
  "message": "validation errors",
  "errors": [
    {
      "name": "optionvalue",
      "message": "This option value does already exist. Option values need to be unique."
    }
  ]
}

Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - changed: URL changed from /customfieldchildoption/{customfieldid}/{parentoptionid}; Request and Response Parameters/Schema unchanged.
  • 1.1.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
optionIdtype: path required: true

integer default: 123
bodytype: body required: false

CustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

This feature is only available for the customfields with type Cascading Select.
Updates the value of an existing child-option of a parent-option for the customfield in default context. When updating the value of an existing option try to use the following JSON:

{
  "optionvalue": "my option value"
}

When you want to disable an existing option use this JSON:

{
  "disabled": true
}

You should not tamper with sequence, because that can mess up the internal order of all options. If you made some mistakes with sequence then simply use the /sort endpoint. This will repair the internal sequence. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - changed: URL changed from /customfieldchildoption/{customfieldid}/{parentoptionid}; Request and Response Parameters/Schema unchanged.
  • 1.1.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
optionIdtype: path required: true

integer default: 123
childOptionIdtype: path required: true

integer default: 334
bodytype: body required: false

CustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

This feature is only available for the customfields with type Cascading Select.
Deletes a child-option of a parent-option of the customfield by its id in default context. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 2.4.0 - changed: added HTTP 403 when global setting 'only administrators can delete options' is active
  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - changed: URL changed from /customfieldchildoption/{customfieldid}/{parentoptionid}; Request and Response Parameters/Schema unchanged.
  • 1.1.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
optionIdtype: path required: true

integer default: 123
childOptionIdtype: path required: true

integer default: 334
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
idintegerThe ID of the just deleted object.
{
    "id": 0
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

This feature is only available for the customfields with type Cascading Select.
Change order for existing child-option of parent-option of customfield in default context. Example: You have four options with IDs 10, 20, 30 and 40 which exist in exactly this order

  • If you now want to place option with ID 20 between 30 and 40, then you need to send:

    • Request-URL: POST /user/customfields/123/contexts/default/options/{parentOptionId}/childoptions/20/move
    • Request-Body: { "after": "30" }
  • There is only one special case for moving an option to the start of the list.
    If you want to move option with ID 40 at the start you need to send:

    • Request-URL: POST /user/customfields/123/contexts/default/options/{parentOptionId}/childoptions/40/move
    • Request-Body: { "position": "First" }

Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - changed: URL changed from /customfieldchildoption/{customfieldid}/{parentoptionid}/move; Request and Response Parameters/Schema unchanged.
  • 1.1.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
optionIdtype: path required: true

integer default: 123
childOptionIdtype: path required: true

integer default: 334
bodytype: body required: true

RestfulTableMoveModel is used for drag-and-drop sorting options using the AUI Restfultable. It is advised to not use it. Use the SORT Endpoint instead or you might break the internal order sequence.
object
PropertyTypeDescription
afterstringAfter must contain the optionId to move the option after. In form of "/foo/bar/{optionid}" which is provided that way by AUI Restfultable.You can provide just the optionId too.
positionstringSpecial Case to move an option to the beginning of the option List. Specify position="First". (Notice: if after and position are defined together, after is ignored)
{
    "after": "foo",
    "position": "foo"
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

This feature is only available for the customfields with type Cascading Select.
Sorts the child-options of a parent-option for the customfield in default context. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
optionIdtype: path required: true

integer default: 123
bodytype: body required: true

SortModel specifies in which way to sort the options of a customfield.You can sort ascending or descending. The sorting will be locale dependant, so you need to specify a locale like en-US. You can specify an optional collator strength.
object
PropertyTypeDescription
localestringIETF BCP 47 language tag string in form of [a-zA-Z]+-[a-zA-Z]+
strengthstringCollator Strength in form of [A-Z]+
orderstringThe sort order in form of [A-Z]+
{
    "locale": "foo",
    "strength": "foo",
    "order": "foo"
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
{}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

user-specific-context-child-options-operations

This feature is only available for the customfields with type Cascading Select.
Lists child-options of parent-option for specific context. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
contextIdtype: path required: true

integer default: 678
optionIdtype: path required: true

integer default: 123
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
array of object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
[
    {
        "optionvalue": "foo",
        "id": 0,
        "sequence": 0,
        "disabled": false
    }
]
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

This feature is only available for the customfields with type Cascading Select.
Creates a new child-option of a parent-option for the customfield in specific context. When creating a new option use the following JSON and do not set sequence and id since they are auto-generated on create.

{
  "optionvalue": "my option value"
}

Option values must be unique. If you create an option with a value that already exists you will recieve a HTTP 400 Validation Error.

{
  "statusCode": 400,
  "subCode": 400000,
  "message": "validation errors",
  "errors": [
    {
      "name": "optionvalue",
      "message": "This option value does already exist. Option values need to be unique."
    }
  ]
}

Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
contextIdtype: path required: true

integer default: 334
optionIdtype: path required: true

integer default: 123
bodytype: body required: false

CustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

This feature is only available for the customfields with type Cascading Select.
Updates the value of an existing child-option of a parent-option for the customfield. When updating the value of an existing option try to use the following JSON:

{
  "optionvalue": "my option value"
}

When you want to disable an existing option use this JSON:

{
  "disabled": true
}

You should not tamper with sequence, because that can mess up the internal order of all options. If you made some mistakes with sequence then simply use the /sort endpoint. This will repair the internal sequence. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
optionIdtype: path required: true

integer default: 123
childOptionIdtype: path required: true

integer default: 334
contextIdtype: path required: true

integer default: 334
bodytype: body required: false

CustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

This feature is only available for the customfields with type Cascading Select.
Deletes a child-option of a parent-option of the customfield by its id in specific context. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 2.4.0 - changed: added HTTP 403 when global setting 'only administrators can delete options' is active
  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
contextIdtype: path required: true

integer default: 334
optionIdtype: path required: true

integer default: 123
childOptionIdtype: path required: true

integer default: 334
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
idintegerThe ID of the just deleted object.
{
    "id": 0
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

This feature is only available for the customfields with type Cascading Select.
Change order for existing child-option of parent-option of customfield in specific context. Example: You have four options with IDs 10, 20, 30 and 40 which exist in exactly this order

  • If you now want to place option with ID 20 between 30 and 40, then you need to send:

    • Request-URL: POST /user/customfields/123/contexts/{contextId}/options/{parentOptionId}/childoptions/20/move
    • Request-Body: { "after": "30" }
  • There is only one special case for moving an option to the start of the list.
    If you want to move option with ID 40 at the start you need to send:

    • Request-URL: POST /user/customfields/123/contexts/{contextId}/options/{parentOptionId}/childoptions/40/move
    • Request-Body: { "position": "First" }

Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
contextIdtype: path required: true

integer default: 334
optionIdtype: path required: true

integer default: 123
childOptionIdtype: path required: true

integer default: 334
bodytype: body required: true

RestfulTableMoveModel is used for drag-and-drop sorting options using the AUI Restfultable. It is advised to not use it. Use the SORT Endpoint instead or you might break the internal order sequence.
object
PropertyTypeDescription
afterstringAfter must contain the optionId to move the option after. In form of "/foo/bar/{optionid}" which is provided that way by AUI Restfultable.You can provide just the optionId too.
positionstringSpecial Case to move an option to the beginning of the option List. Specify position="First". (Notice: if after and position are defined together, after is ignored)
{
    "after": "foo",
    "position": "foo"
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
optionvaluestringThe actual optionValue which is displayed to the user who uses the customField.
idintegerThe unique optionId.
sequenceintegerThe OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabledbooleanThe OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an JIRA issue.
{
    "optionvalue": "foo",
    "id": 0,
    "sequence": 0,
    "disabled": false
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

This feature is only available for the customfields with type Cascading Select.
Sorts the child-options of a parent-option for the customfield in specific context. Note that the user needs permissions granted by an administrator via admin-endpoints first in order to not get a 'permission denied' error via HTTP 403:

{
  "statusCode": 403,
  "subCode": 403001,
  "message": "FieldPermission Denied - you do not have sufficient rights for this operation."
}

Version History

  • 1.8.0 - changed: Better error handling with HTTP 400 Validation Errors [CEP-56].
  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
customFieldIdtype: path required: true

integer default: 12345
contextIdtype: path required: true

integer default: 678
optionIdtype: path required: true

integer default: 123
bodytype: body required: true

SortModel specifies in which way to sort the options of a customfield.You can sort ascending or descending. The sorting will be locale dependant, so you need to specify a locale like en-US. You can specify an optional collator strength.
object
PropertyTypeDescription
localestringIETF BCP 47 language tag string in form of [a-zA-Z]+-[a-zA-Z]+
strengthstringCollator Strength in form of [A-Z]+
orderstringThe sort order in form of [A-Z]+
{
    "locale": "foo",
    "strength": "foo",
    "order": "foo"
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
{}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (insufficient rights on field).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

maintenance

List all event log entries. An example of an event log entry looks like this:

{
  "name": "CustomFieldCreatedEvent",
  "details": "ID customfield_10107",
  "dateTime": "2019-01-03T20:44:29+0000",
  "hash": "b323674a11b0f287fe81b1633be9dbb9d6dda6056065209521431eea8a441a7a"
}
  • dateTime is in format YYYY-MM-dd T HH:mm:ss+Z; It is a UTC date with offset +0000.

 

Pagination is handled the same way as the official JIRA REST API handles it. The startAt parameter indicates which item should be used as the first item in the page of results. The maxResults parameter indicates how many results to return per page. The default is 20. values always contains the items and processingTimeInMs is the time it took to process the request in milliseconds.

{
  "maxResults": 20,
  "startAt": 100,
  "total": 200,
  "processingTimeInMs": 327,
  "values": [ ]
}

 

Ordering is also handled in a standardized way. With ?orderBy=name the order will be ascending. With ?orderBy=+name the order will be ascending. With ?orderBy=-name the order will be descending.   You need to be administrator or system administrator to use this endpoint.

Version History

  • 2.0.0 - introduced
consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
startAttype: query required: false

indicates which item should be used as the first item in the page of results.
integer default:
maxResultstype: query required: false

indicates how many results to return per page.
integer default:
orderBytype: query required: false

defines by what field should be sorted.
string default: -dateTime
filtertype: query required: false

filter results by a string e.g. name of an entity.
string default:
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
maxResultsinteger
startAtinteger
totalinteger
processingTimeInMsinteger
valuesarray
array of object
PropertyTypeDescription
namestring
detailsstring
dateTimestring
hashstring
{
    "maxResults": 0,
    "startAt": 0,
    "total": 0,
    "processingTimeInMs": 0,
    "values": [
        {
            "name": "foo",
            "details": "foo",
            "dateTime": "foo",
            "hash": "foo"
        }
    ]
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (you must be JIRA administrator).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

List all jobs. An example of an job entry looks like this:

{
  "name": "JobIndexCustomFieldSearchTable",
  "status": "FINISHED",
  "scheduledTime": "2019-01-03T20:44:29+0000",
  "finishedTime": "2019-01-03T20:54:29+0000"
}
  • scheduledTime and finishedTime is in format YYYY-MM-dd T HH:mm:ss+Z or null; It is a UTC date with offset +0000.
  • status is either SCHEDULED, RUNNING, SUCCESS, FAILED.

 

Pagination is handled the same way as the official JIRA REST API handles it. The startAt parameter indicates which item should be used as the first item in the page of results. The maxResults parameter indicates how many results to return per page. The default is 20. values always contains the items and processingTimeInMs is the time it took to process the request in milliseconds.

{
  "maxResults": 20,
  "startAt": 100,
  "total": 200,
  "processingTimeInMs": 327,
  "values": [ ]
}

 

Ordering is also handled in a standardized way. With ?orderBy=name the order will be ascending. With ?orderBy=+name the order will be ascending. With ?orderBy=-name the order will be descending.   You need to be administrator or system administrator to use this endpoint.

Version History

  • 2.0.0 - introduced
consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
startAttype: query required: false

indicates which item should be used as the first item in the page of results.
integer default:
maxResultstype: query required: false

indicates how many results to return per page.
integer default:
orderBytype: query required: false

defines by what field should be sorted.
string default: +name
filtertype: query required: false

filter results by a string e.g. name of an entity.
string default:
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
maxResultsinteger
startAtinteger
totalinteger
processingTimeInMsinteger
valuesarray
array of object
PropertyTypeDescription
namestring
statusstring
scheduledTimestring
finishedTimestring
{
    "maxResults": 0,
    "startAt": 0,
    "total": 0,
    "processingTimeInMs": 0,
    "values": [
        {
            "name": "foo",
            "status": "foo",
            "scheduledTime": "foo",
            "finishedTime": "foo"
        }
    ]
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (you must be JIRA administrator).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

List data storage status. You will see all Database Tables of the app with their count of rows. You need to be administrator or system administrator to use this endpoint.

Version History

  • 2.0.0 - introduced
consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
maxResultsinteger
startAtinteger
totalinteger
processingTimeInMsinteger
valuesarray
array of object
PropertyTypeDescription
tableNamestring
countinteger
{
    "maxResults": 0,
    "startAt": 0,
    "total": 0,
    "processingTimeInMs": 0,
    "values": [
        {
            "tableName": "foo",
            "count": 0
        }
    ]
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (you must be JIRA administrator).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Get the event-log auto-truncate schedule for when the event-log should be truncated automatically.


You need to be administrator or system administrator to use this endpoint.

Version History

  • 2.5.4 - introduced
consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
activebooleanIf true then the auto-truncate job is active.
cronExpressionstringSet this to a unix cronjob expression such as '0 0 * ? * *' for every hour.
nextRunstringutc date of next run in format YYYY-MM-ddTHH:mm:ss.
{
    "active": false,
    "cronExpression": "foo",
    "nextRun": "foo"
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (you must be JIRA administrator).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Set the event-log auto-truncate schedule for when the event-log should be truncated automatically. Send a cronjob-expression like so to activate the job to run every hour:

{
  "active": true,
  "cronExpression": "0 0 * ? * *"
}

Or send this to deactivate the job:

{
  "active": false
}


You need to be administrator or system administrator to use this endpoint.

Version History

  • 2.5.4 - introduced
consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
bodytype: body required: false

used to event-log auto-truncate schedule and activate/deactivate the job
object
PropertyTypeDescription
activebooleanIf true then the auto-truncate job is active.
cronExpressionstringSet this to a unix cronjob expression such as '0 0 * ? * *' for every hour.
{
    "active": false,
    "cronExpression": "foo"
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
activebooleanIf true then the auto-truncate job is active.
cronExpressionstringSet this to a unix cronjob expression such as '0 0 * ? * *' for every hour.
nextRunstringutc date of next run in format YYYY-MM-ddTHH:mm:ss.
{
    "active": false,
    "cronExpression": "foo",
    "nextRun": "foo"
}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (you must be JIRA administrator).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

These Tasks run automatically after a plugin install/update. Should the tasks for some reason not have been executed automatically you will see them here with status other than SUCCESS and can trigger them manually via maintenance operations. Since v2.0.0 of the plugin you can re-trigger MigrationTask runs on the Settings Page via a Button. You need to be administrator or system administrator to use this endpoint.

Version History

  • 2.0.0 - changed URL from /admin/migrationtasks to /maintenance/migration_tasks.
  • 1.3.0 - changed so that admins and sysadmins can use it.
  • 1.2.1 - introduced
consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
array of object
PropertyTypeDescription
idintegerThe Migration Task ID.
descriptionstringThe Description of the migration task.
forVersionstringThe Version in which the migration Task was introduced
executionTimestringThe datetime when the task was executed in utc +0000 offset.
statusstringOne of STATUS_NOT_EXECUTED_OR_FAILED or SUCCESS
[
    {
        "id": 0,
        "description": "foo",
        "forVersion": "foo",
        "executionTime": "foo",
        "status": "foo"
    }
]
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (you must be JIRA administrator).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

Execute a maintenance operation. To execute an maintenance operation send the operatioName like so:

{
  "name": "JobIndexCustomFieldSearchTable"
}


Scheduling a Job You can schedule a job by sending the jobName as operationName. Job scheduling will silently be ignored if the job is currently running. Jobs will always run on one JIRA Instance at a time (Data Center Compatible). No concurrent Job runs of the same job possible. Schedulable jobs are: JobIndexCustomFieldSearchTable

  • recreate the database table for searching custom fields.

    JobRunDataMigrationTasks

  • run all data migration tasks.


Execute Maintenance Action The actions should only be performed if something is not working and if it is really necessary. Possible Maintenance Actions are: MaintenanceActionForceFailRunningAndScheduledJobs

  • If Jobs remain on SCHEDULED or RUNNING forever you can set the status of these jobs to FAILED in the database. That does not stop running Jobs that are in some kind of deadlock, you should at some point restart JIRA to do so. Once these jobs are set to FAILED you can manually reschedule them for execution. Do this only if you really have waited more than one day. Ask the vendor if in your case you really should perform this action.

MaintenanceActionDeleteEventLogsOlderThanOneMonth

  • Delete Event Log entries older than one month. Deleted entries cannot be restored.

MaintenanceActionDeleteAllEventLogs

  • Delete ALL Event Log entries. Deleted entries cannot be restored.

MaintenanceActionDeleteAllMigrationTaskInformation

  • If the Data Migration Tasks display as FAILED forever then you can clear all Migration Task information and then the job 'JobRunDataMigrationTasks' can be manually scheduled for execution. Usually Migration Tasks are idempotent and can be executed multiple times even though that should be avoided. They are designed to not overwrite existing data. Ask the vendor if in your case you really should perform this action.
  • (prior to version 2.0.0 the URL to perform the action was HTTP GET /admin/migrationtasks/clearhistory)

MaintenanceActionIncreaseVerbosityForTesting and MaintenanceActionDecreaseVerbosityForTesting

  • Increase and decrease the verbosity on the EventLog needed during Integration tests.


You need to be administrator or system administrator to use this endpoint.

Version History

  • 2.0.0 - introduced
consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
bodytype: body required: false

Specify the operation to be executed
object
PropertyTypeDescription
namestring
{
    "name": "foo"
}
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
{}
400Validation Error for Request parameters (or body).
object
PropertyTypeDescription
messagestringA human readable error message.
statusCodeintegerAn integer HTTP status code.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
errorsarrayIf there are errors that are specific to a certain property of a submitted model it will be listed here.
array of object
PropertyTypeDescription
namestringThe name of the field or property which has a validation error.
messagestringHuman readable error message.
exceptionNamestringThe Exception name (optional).
{
    "message": "foo",
    "statusCode": 0,
    "subCode": 0,
    "errors": [
        {
            "name": "foo",
            "message": "foo",
            "exceptionName": "foo"
        }
    ]
}
401Unauthorized (no user is authenticated).
403Permission Denied (you must be JIRA administrator).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
412not available under the requested URL (min version).
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}
500Unexpected Error.
object
PropertyTypeDescription
statusCodeintegerAn integer HTTP status code. For example HTTP 500.
subCodeintegerAn unique number to send in with bug reports to better identify the error.
messagestringA human readable error message.
{
    "statusCode": 0,
    "subCode": 0,
    "message": "foo"
}

bulk