REST API

The app provides a set of REST Endpoints to perform operations such as add new customfield option value or set default value for the supported field types.

Rest API Explorer

The REST API Explorer will help you to send REST requests to the API directly in the browser. Since version 1.8.0 it uses Swagger UI v3.1.

To access the REST API Explorer click on Issues in the Jira top navigation bar. In the drop-down click on Field Editor.

In the left navigation bar click on REST API Explorer.

You now see a list of all available endpoints and you can click on any endpoint to expand its details. If you want to perform some requests you first need to enter your basic auth credentials.

A dialog opens and you can enter your Jira username and password. Finally click on Authorize.

Via the Try it out button you can now perform a REST Request against your Jira instance.

If the Endpoint has parameters such as URL parameters or a request body you can specify them before you click on Execute. The request will now be executed and when scrolling down a little bit you will see the HTTP response.

If using Jira Data Center each request sent by the REST API Explorer will randomly use another cluster node which you can see in the response headers x-anodeid. If you are receiving a HTTP 404 as response this is most likely caused by an defunct cluster setup. For example you are on node-1 and the HTTP API response comes from node-2 where for some reason the app is not installed.

The following demo screeencast will show you the full process described above.

Rest API Endpoint Documentation

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

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

  • 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 for Jira. See User Guide for supported FieldTypes. 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.2.0 - introduced
consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
array of object
PropertyTypeDescription
fieldIdintegerThe customField Id.
fieldNamestringThe customField name.
fieldTypestringThe customField Type.
fieldDescriptionstringThe customField Description.
[
    {
        "fieldId": 0,
        "fieldName": "foo",
        "fieldType": "foo",
        "fieldDescription": "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. 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.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
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
object
PropertyTypeDescription
userlistarrayUsernames who have permission (GET). Or are destined to have permission (PUT).
array of string
grouplistarrayGroupnames who have permission (GET). Or are destined to have permission (PUT).
array of string
{
    "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 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

  • 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

CustomFieldPermissionModel is used to save and get permissions on customfield.Userlist and grouplist contain usernames and groupnames.
object
PropertyTypeDescription
userlistarrayUsernames who have permission (GET). Or are destined to have permission (PUT).
array of string
grouplistarrayGroupnames who have permission (GET). Or are destined to have permission (PUT).
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 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
issueTypeIdstringThe issue types's literal Id.
issueTypeNamestringThe issue types's name.
issueTypeDescriptionstringThe issue types's description.
issueTypeIsSubTaskbooleanIs the issue types a subtask (true).
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": [
            {
                "issueTypeId": "foo",
                "issueTypeName": "foo",
                "issueTypeDescription": "foo",
                "issueTypeIsSubTask": false
            }
        ],
        "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. 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.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
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
array of object
PropertyTypeDescription
contextIdintegerThe customField's context Id.
userlistarrayUsernames who have permission (GET). Or are destined to have permission (PUT).
array of string
grouplistarrayGroupnames who have permission (GET). Or are destined to have permission (PUT).
array of string
[
    {
        "contextId": 0,
        "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 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

  • 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

CustomFieldContextPermissionModel is used to save and get permissions on customfield contexts.Userlist and grouplist contain usernames and groupnames.
array of object
PropertyTypeDescription
contextIdintegerThe customField's context Id.
userlistarrayUsernames who have permission (GET). Or are destined to have permission (PUT).
array of string
grouplistarrayGroupnames who have permission (GET). Or are destined to have permission (PUT).
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.

Version History

  • 1.2.0 - introduced

consumes application/json produces application/json
Request Parameters
ParameterDescriptionData Type
Response Messages
StatusDescriptionSchema / JSON Example
200successful operation
array of object
PropertyTypeDescription
fieldIdintegerThe customField Id.
fieldNamestringThe customField name.
fieldTypestringThe customField Type.
fieldDescriptionstringThe customField Description.
[
    {
        "fieldId": 0,
        "fieldName": "foo",
        "fieldType": "foo",
        "fieldDescription": "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"
}

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
issueTypeIdstringThe issue types's literal Id.
issueTypeNamestringThe issue types's name.
issueTypeDescriptionstringThe issue types's description.
issueTypeIsSubTaskbooleanIs the issue types a subtask (true).
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": [
            {
                "issueTypeId": "foo",
                "issueTypeName": "foo",
                "issueTypeDescription": "foo",
                "issueTypeIsSubTask": false
            }
        ],
        "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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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"
}

Rest API Upgrade Notes

The REST API changes from time to time. We try to keep these changes as minimal as possible, but at some point technical debt needs to be dealt with. See in the version sections below which changes made to the API on the respective app version:

v1.9.0 to v2.0.0

No breaking changes.

  • breaking:

    • -

  • non-breaking:

    • [CEP-71] REST API new incremental Permission update Endpoint (HTTP PATCH)

    • [CEP-69] REST API new combined get customfield, context and defaultOption Endpoint (HTTP GET)

    • [CEP-72] REST API old full Permission update Endpoint (HTTP PUT) now enforces users must exist (returns validation errors if not).

    • [CEP-68] REST API user and admin customfield lists: Introducing paginable, filterable and orderable results. (backwards compatible but with deprecations)

  • deprecations:

    • GET /user/customfields and /admin/customfields for old un-paginated results are deprecated and will be removed in future releases. See [CEP-68].

Summary: No structural changes to any endpoints. Release v2.0.0 brings all the performance optimizations needed for Data Center compatibility. Only deprecations for non-paginated customfield list endpoints (see above).

v1.8.0 to v1.9.0

No breaking changes.

v1.7.1 to v1.8.0

Breaking changes!

  • breaking:

    • [CEP-56] REST API: Simplify Errors - Remove HTTP 406 - Migrate to HTTP 400.

    • [CEP-57] REST API: Improve Error Handling for ChildOption Endpoints of Cascading Select fields.

  • non-breaking:

    • [CEP-58] REST API: Change of existing option should work even if only case is changed

Summary: No structural changes to any endpoints. All Endpoints still have the same URLs and same JSON Schemas for Request and Response. All Endpoints now use HTTP 400 for most of the errors. HTTP 406 removed. HTTP 412 only used for version compatibility errors. HTTP 500 only used for unexpected errors.

v1.5.0 to v1.7.1

No breaking changes.

v1.4.0 to v1.5.0

Breaking changes!

  • breaking:

    • [CEP-36] Rest-API: All Endpoints will return HTTP 403 instead of HTTP 500 on non existing custom field id.

  • non-breaking:

    • [CEP-31] Rest-API: Provide associated projects and issue types info for /*/customfields/{id}/contexts Endpoint.

v1.3.0 to v1.4.0

No breaking changes.

v1.2.3 to v1.3.0

No breaking changes.

  • breaking:

    • -

  • non-breaking:

    • [CEP-INT-8] base url is now /1 not /1.2 anymore. But will be backwards compatible.

    • [CEP-INT-8] removed the "v1.1 Compatibility Mode" completely.

    • [CEP-12] added /extended Endpoints for admin context permissions that display users fullname in userlists.

v1.2.2 to v1.2.3

No breaking changes.

v1.2.1 to v1.2.2

No breaking changes.

v1.2.0 to v1.2.1

You don't really need to do anything. Everything should work as before since it is just a bugfixing release which also brings the new context security feature. See the administrator guide for more details.

v1.0.0/1.1.0 to v1.2.0

You are advised to migrate to the new v1.2 URLs but you can use the v1.1 compatibility mode until you fully migrated. Here are the changes to the API from v1.1 to v1.2:

  • new baseUrl (with version /1.2/)

  • the URL pattern changed for all endpoints. See the the above REST-API-Endpoint-Documentation.

  • CustomFieldId is now Long (1234) not String (customfield_1234) anymore.

  • childOptions are removed from GET Options Resource response. Use separate Request on GET childOptions Resource now.

  • XML Support is removed completely. Use JSON as body-payload instead.

  • Error Responses are a little different and there are more distinct Response codes. See the the above REST-API-Endpoint-Documentation for all details.

  • Added Support for Field Contexts (with contextIDs or defaultContext).

  • Added alphabetical Sorting Endpoint for Options and childOptions.

  • Added Setting of default Value Endpoint.

  • Added a REST API Explorer on URL http://server:port/jira/plugins/servlet/customfieldeditorplugin/restapi/. You can trigger API Calls to the API directly in the Browser

  • Added admin Endpoints to set permissions and list customfields (for jira-administrator only)

CORS (Cross-Origin Resource Sharing)

CORS is not provided by the app itself. You need to configure CORS to your needs in the Webserver (Nginx or Apache Webserver) that sits in front of Jira.

Note: codeclou does not recommend you to configure CORS in a specific way. You should consult a specalist to configure CORS to your needs. The config below is provided without any warranty

Use this demo config for Apache Webserver v2.4+ to handle HTTP Options Preflight Requests and set correct CORS headers. Note that you still should abide Proxying Atlassian server applications with Apache HTTP Server (mod_proxy_http).

virtual-host.conf
<VirtualHost *:80>
  ServerName api-proxy.codeclou.io

  ## SSL => You should use SSL in production
  #SSLEngine on
  #SSLCertificateKeyFile /etc/ssl.key/example.com.key
  #SSLCertificateFile /etc/ssl.crt/example.com.crt

  ## CORS Header
  Header always set Access-Control-Allow-Origin  "*"
  Header always set Access-Control-Allow-Methods "POST, GET, OPTIONS, DELETE, PUT"
  Header always set Access-Control-Allow-Headers "x-requested-with, Content-Type, origin, authorization, accept, client-security-token"

  ## Handle HTTP Options Preflight Request always with 200
  RewriteEngine On
  RewriteCond %{REQUEST_METHOD} OPTIONS
  RewriteRule ^(.*)$ $1 [R=200,L]

  ## Proxy CEP REST Uris to Jira Server
  <LocationMatch "/rest/jiracustomfieldeditorplugin/1">
    ProxyPass http://jira-server:8080/rest/jiracustomfieldeditorplugin/1 disablereuse=On
    ProxyPassReverse http:///jira-server:8080/rest/jiracustomfieldeditorplugin/1
  </LocationMatch>
</VirtualHost>

Use this demo config for NGINX v1+ to handle HTTP Options Preflight Requests and set correct CORS headers. Note that you still should abide Integrating Jira with Nginx.

nginx.conf
server {
  listen api-proxy.codeclou.io:80;
  server_name api-proxy.codeclou.io;

  ## SSL => You should use SSL in production
  #ssl_certificate     www.example.com.crt;
  #ssl_certificate_key www.example.com.key;
  #ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
  #ssl_ciphers         HIGH:!aNULL:!MD5;

  location /rest/jiracustomfieldeditorplugin/1 {

    ## CORS Header
    add_header 'Access-Control-Allow-Origin' '*' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
    add_header 'Access-Control-Allow-Headers' 'x-requested-with, Content-Type, origin, authorization, accept, client-security-token' always;

    ## Handle HTTP Options Preflight Request always with 200
    if ($request_method = 'OPTIONS') {
      return 200;
    }

    ## Proxy CEP REST Uris to Jira Server
    proxy_pass http://jira-server:8080/rest/jiracustomfieldeditorplugin/1;
  }
}

Now you can test your CORS config. The HTTP Options Preflight Request should have the following CORS Headers:

$
curl -I -X OPTIONS -H "Accept: application/json" -u admin:admin http://jira-server:8080/rest/jiracustomfieldeditorplugin/1/admin/customfields
HTTP/1.1 200 OK
Server: nginx/1.10.3 (Ubuntu)
Date: Tue, 24 Jul 2018 11:29:58 GMT
Content-Type: application/octet-stream
Content-Length: 0
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: x-requested-with, Content-Type, origin, authorization, accept, client-security-token

Any normal e.g. HTTP Get Request should have the following CORS Headers.

$
curl -I -X GET -H "Accept: application/json" -u admin:admin http://jira-server:8080/rest/jiracustomfieldeditorplugin/1/admin/customfields
HTTP/1.1 200
Server: nginx/1.10.3 (Ubuntu)
Date: Tue, 24 Jul 2018 11:30:32 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
X-AREQUESTID: 690x707x1
X-ANODEID: jira-cluster-7100-node1
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
Content-Security-Policy: frame-ancestors 'self'
X-ASEN: SEN-L12059515
X-Seraph-LoginReason: OK
X-ASESSIONID: cdyu96
X-AUSERNAME: admin
Cache-Control: no-cache, no-store, no-transform
...
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: x-requested-with, Content-Type, origin, authorization, accept, client-security-token