Rest API - Metadata for Jira 4.5

Owned by Andreas Spall (evolu.software)
Jul 03, 2019
7 min read

You can create/read/update/delete metadata value via UI or the following Rest API
Version 1.0

APIs

Base path for the Rest API: Jira_Base_Url/rest/metadata/1.0

e.g. get the first 20 metadata for project JM (as project-admin): https://jira.atlassian.internal/rest/metadata/1.0/project/JM?includeHidden=true&startAt=0&maxResults=20

/component/{projectkey}/{identifier}

GET

get metadata values for a given object (e.g. version/component) as object array (not unlimited since 4.2)

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

projectkey

path

yes

the project key


>string

identifier

path

yes

the version/component identifier


>string

includeHidden

query

no

will include the hidden metadata values, if the user has the permission to edit (create/update) metadata values


>boolean

startAt

query

no

the index of the first metadata value to return (0-based)


>integer (int32)

maxResults

query

no

the maximum number of metadata values to return (defaults to 100 (if startAt >= 1)). The maximum allowable value is dictated to 500. If you specify a value that is higher than this number, your search results will be truncated.


>integer (int32)

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

Array[ JiraMetadata ]

PUT

create / update metadata as object array

 Details

Request

**Content-Type: ** application/json

Parameters

Name

Located in

Required

Description

Default

Schema

projectkey

path

yes

the project key


>string

identifier

path

yes

the version/component identifier


>string

JiraMetadata

body

yes

the to change metadata object array


Array[ JiraMetadata ]

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

Array[ JiraMetadata ]

400

the specified version/component can't be loaded


403

User has no permission to create / update metadata


503

Invalid license


/component/{projectkey}/{identifier}/{key}

GET

get the specified metadata

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

projectkey

path

yes

the project key


>string

identifier

path

yes

the version/component identifier


>string

key

path

yes

the user-defined key of the metadata


>string

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

JiraMetadata

PUT

create / update one metadata

 Details

Request

**Content-Type: ** application/json

Parameters

Name

Located in

Required

Description

Default

Schema

projectkey

path

yes

the project key


>string

identifier

path

yes

the version/component identifier


>string

key

path

yes

the user-defined key of the metadata


>string

JiraMetadata

body

yes

the to change metadata


JiraMetadata

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

JiraMetadata

400

the given key doesn't match to the key of the JiraMetadata object, the specified version/component can't be loaded or something went wrong while loading the saved metadata


403

User has no permission to create / update metadata


500

something went wrong while saving the metadata


503

Invalid license


DELETE

delete the specified metadata

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

projectkey

path

yes

the project key


>string

identifier

path

yes

the version/component identifier


>string

key

path

yes

the user-defined key of the metadata


>string

Response

**Content-Type: ** text/plain

Status Code

Reason

Response Model

-------------

-------------

----------------

400

the specified version/component can't be loaded


403

User has no permission to create / update metadata


404

there is no metadata object with the given key


503

Invalid license


/component/{projectkey}/{identifier}/{key}/value

GET

get the specified metadata value

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

projectkey

path

yes

the project key


>string

identifier

path

yes

the version/component identifier


>string

key

path

yes

the user-defined key of the metadata


>string

Response

**Content-Type: ** text/plain

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation


/configuration/project/{projectKey}

GET

experimental: returns the project configuration for the specified project

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

projectKey

path

yes



>string

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

ProjectConfiguration

/configuration/project/{projectKey}/screen/{screenKey}

GET

experimental: applies the project screen to the specified project

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

projectKey

path

yes

the project key


>string

screenKey

path

yes

the screen key


>string

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

Message

403

User has no Project Admin permission


/configuration/screen/customer/default

GET

experimental: get the default customer screen

 Details

Request

Parameters

Response

Status Code

Reason

Response Model

-------------

-------------

----------------

403

User has no application use permission


PUT

experimental: the specified user screen becomes the default customer screen

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

MetadataScreen

body

yes

the to change metadata screen



Response

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

Message

400

the given json is invalid


403

User has no Jira Admin permission


/configuration/screen/project

PUT

experimental: the given (valid) project screen will be updated

 Details

Request

**Content-Type: ** application/json

Parameters

Name

Located in

Required

Description

Default

Schema

MetadataScreen

body

yes

the to change metadata screen



Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

Message

400

the given json is invalid


403

User has no Jira Admin permission


/configuration/screen/project/all

GET

experimental: get all project screens

 Details

Request

Parameters

Response

Status Code

Reason

Response Model

-------------

-------------

----------------

403

User has no application use permission


/configuration/screen/project/default

GET

experimental: get the default project screen

 Details

Request

Parameters

Response

Status Code

Reason

Response Model

-------------

-------------

----------------

403

User has no application use permission


PUT

experimental: the specified project screen becomes the default project screen

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

MetadataScreen

body

yes

the to change metadata screen



Response

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

Message

400

the given json is invalid


403

User has no Jira Admin permission


/configuration/screen/project/{identifier}

DELETE

experimental: the specified project screen will be deleted

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the screen identifier


>string

Response

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

Message

403

User has no Jira Admin permission


500

Error when deleting


/configuration/screen/user/default

GET

experimental: get the default user screen

 Details

Request

Parameters

Response

Status Code

Reason

Response Model

-------------

-------------

----------------

403

User has no application use permission


PUT

experimental: the specified user screen becomes the default user screen

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

MetadataScreen

body

yes

the to change metadata screen



Response

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

Message

400

the given json is invalid


403

User has no Jira Admin permission


/group/{identifier}

GET

get metadata values for a given object (e.g. project/group/user) as object array (not unlimited since 4.2)

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

includeHidden

query

no

will include the hidden metadata values, if the user has the permission to edit (create/update) metadata values


>boolean

startAt

query

no

the index of the first metadata value to return (0-based)


>integer (int32)

maxResults

query

no

the maximum number of metadata values to return (defaults to 100 (if startAt >= 1)). The maximum allowable value is dictated to 500. If you specify a value that is higher than this number, your search results will be truncated.


>integer (int32)

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

Array[ JiraMetadata ]

PUT

create / update metadata as object array

 Details

Request

**Content-Type: ** application/json

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

JiraMetadata

body

yes

the to change metadata object array


Array[ JiraMetadata ]

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

Array[ JiraMetadata ]

403

User has no permission to create / update metadata


503

Invalid license


/group/{identifier}/{key}

GET

get the specified metadata

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

key

path

yes

the user-defined key of the metadata


>string

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

JiraMetadata

PUT

create / update one metadata

 Details

Request

**Content-Type: ** application/json

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

key

path

yes

the user-defined key of the metadata


>string

JiraMetadata

body

yes

the to change metadata


JiraMetadata

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

JiraMetadata

400

the given key doesn't match to the key of the JiraMetadata object or something went wrong while loading the saved metadata


403

User has no permission to create / update metadata


500

something went wrong while saving the metadata


503

Invalid license


DELETE

delete the specified metadata

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

key

path

yes

the user-defined key of the metadata


>string

Response

**Content-Type: ** text/plain

Status Code

Reason

Response Model

-------------

-------------

----------------

403

User has no permission to create / update metadata


404

there is no metadata object with the given key


503

Invalid license


/group/{identifier}/{key}/value

GET

get the specified metadata value

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

key

path

yes

the user-defined key of the metadata


>string

Response

**Content-Type: ** text/plain

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation


/project/{identifier}

GET

get metadata values for a given object (e.g. project/group/user) as object array (not unlimited since 4.2)

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

includeHidden

query

no

will include the hidden metadata values, if the user has the permission to edit (create/update) metadata values


>boolean

startAt

query

no

the index of the first metadata value to return (0-based)


>integer (int32)

maxResults

query

no

the maximum number of metadata values to return (defaults to 100 (if startAt >= 1)). The maximum allowable value is dictated to 500. If you specify a value that is higher than this number, your search results will be truncated.


>integer (int32)

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

Array[ JiraMetadata ]

PUT

create / update metadata as object array

 Details

Request

**Content-Type: ** application/json

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

JiraMetadata

body

yes

the to change metadata object array


Array[ JiraMetadata ]

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

Array[ JiraMetadata ]

403

User has no permission to create / update metadata


503

Invalid license


/project/{identifier}/{key}

GET

get the specified metadata

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

key

path

yes

the user-defined key of the metadata


>string

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

JiraMetadata

PUT

create / update one metadata

 Details

Request

**Content-Type: ** application/json

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

key

path

yes

the user-defined key of the metadata


>string

JiraMetadata

body

yes

the to change metadata


JiraMetadata

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

JiraMetadata

400

the given key doesn't match to the key of the JiraMetadata object or something went wrong while loading the saved metadata


403

User has no permission to create / update metadata


500

something went wrong while saving the metadata


503

Invalid license


DELETE

delete the specified metadata

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

key

path

yes

the user-defined key of the metadata


>string

Response

**Content-Type: ** text/plain

Status Code

Reason

Response Model

-------------

-------------

----------------

403

User has no permission to create / update metadata


404

there is no metadata object with the given key


503

Invalid license


/project/{identifier}/{key}/value

GET

get the specified metadata value

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

key

path

yes

the user-defined key of the metadata


>string

Response

**Content-Type: ** text/plain

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation


/servicedesk/customer/profile/{identifier}

GET

experimental: returns the customer screen (with it's metadata values for the specfied user

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the user identifier


>string

Response

Status Code

Reason

Response Model

-------------

-------------

----------------

500

the user defined by identifier is not the current user


/servicedesk/customer/profile/{identifier}/{key}

PUT

experimental: create / update the specified metadata as non hidden metadata

 Details

Request

**Content-Type: ** application/json

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the user identifier


>string

key

path

yes

the user-defined key of the metadata


>string

JiraMetadata

body

yes

the to change metadata


JiraMetadata

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

JiraMetadata

400

the given key doesn't match to the key of the JiraMetadata object or something went wrong while loading the saved metadata


403

User (found by the user identifier) is not the calling user or the metadata is not part of the customer screen


500

something went wrong while saving the metadata


503

Invalid license


/servicedesk/{projectKey}/agent/customer/profile/{identifier}

GET

experimental: returns the customer screen (with it's metadata values for the specfied user

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

projectKey

path

yes

the service desk project key


>string

identifier

path

yes

the user identifier


>string

Response

Status Code

Reason

Response Model

-------------

-------------

----------------

500

current user is not an agent for the specified project or the project can't be found


/servicedesk/{projectKey}/agent/customer/profile/{identifier}/{key}

PUT

experimental: create / update the specified metadata as non hidden metadata

 Details

Request

**Content-Type: ** application/json

Parameters

Name

Located in

Required

Description

Default

Schema

projectKey

path

yes

the service desk project key


>string

identifier

path

yes

the user identifier


>string

key

path

yes

the user-defined key of the metadata


>string

JiraMetadata

body

yes

the to change metadata


JiraMetadata

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

JiraMetadata

400

the given key doesn't match to the key of the JiraMetadata object or something went wrong while loading the saved metadata


403

The calling user is not in the Agent role or the metadata is not part of the customer screen


500

something went wrong while saving the metadata


503

Invalid license


/user/{identifier}

GET

get metadata values for a given object (e.g. project/group/user) as object array (not unlimited since 4.2)

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

includeHidden

query

no

will include the hidden metadata values, if the user has the permission to edit (create/update) metadata values


>boolean

startAt

query

no

the index of the first metadata value to return (0-based)


>integer (int32)

maxResults

query

no

the maximum number of metadata values to return (defaults to 100 (if startAt >= 1)). The maximum allowable value is dictated to 500. If you specify a value that is higher than this number, your search results will be truncated.


>integer (int32)

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

Array[ JiraMetadata ]

PUT

create / update metadata as object array

 Details

Request

**Content-Type: ** application/json

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

JiraMetadata

body

yes

the to change metadata object array


Array[ JiraMetadata ]

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

Array[ JiraMetadata ]

403

User has no permission to create / update metadata


503

Invalid license


/user/{identifier}/{key}

GET

get the specified metadata

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

key

path

yes

the user-defined key of the metadata


>string

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

JiraMetadata

PUT

create / update one metadata

 Details

Request

**Content-Type: ** application/json

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

key

path

yes

the user-defined key of the metadata


>string

JiraMetadata

body

yes

the to change metadata


JiraMetadata

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

JiraMetadata

400

the given key doesn't match to the key of the JiraMetadata object or something went wrong while loading the saved metadata


403

User has no permission to create / update metadata


500

something went wrong while saving the metadata


503

Invalid license


DELETE

delete the specified metadata

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

key

path

yes

the user-defined key of the metadata


>string

Response

**Content-Type: ** text/plain

Status Code

Reason

Response Model

-------------

-------------

----------------

403

User has no permission to create / update metadata


404

there is no metadata object with the given key


503

Invalid license


/user/{identifier}/{key}/value

GET

get the specified metadata value

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

identifier

path

yes

the project/group/user identifier


>string

key

path

yes

the user-defined key of the metadata


>string

Response

**Content-Type: ** text/plain

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation


/version/{projectkey}/{identifier}

GET

get metadata values for a given object (e.g. version/component) as object array (not unlimited since 4.2)

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

projectkey

path

yes

the project key


>string

identifier

path

yes

the version/component identifier


>string

includeHidden

query

no

will include the hidden metadata values, if the user has the permission to edit (create/update) metadata values


>boolean

startAt

query

no

the index of the first metadata value to return (0-based)


>integer (int32)

maxResults

query

no

the maximum number of metadata values to return (defaults to 100 (if startAt >= 1)). The maximum allowable value is dictated to 500. If you specify a value that is higher than this number, your search results will be truncated.


>integer (int32)

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

Array[ JiraMetadata ]

PUT

create / update metadata as object array

 Details

Request

**Content-Type: ** application/json

Parameters

Name

Located in

Required

Description

Default

Schema

projectkey

path

yes

the project key


>string

identifier

path

yes

the version/component identifier


>string

JiraMetadata

body

yes

the to change metadata object array


Array[ JiraMetadata ]

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

Array[ JiraMetadata ]

400

the specified version/component can't be loaded


403

User has no permission to create / update metadata


503

Invalid license


/version/{projectkey}/{identifier}/{key}

GET

get the specified metadata

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

projectkey

path

yes

the project key


>string

identifier

path

yes

the version/component identifier


>string

key

path

yes

the user-defined key of the metadata


>string

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

JiraMetadata

PUT

create / update one metadata

 Details

Request

**Content-Type: ** application/json

Parameters

Name

Located in

Required

Description

Default

Schema

projectkey

path

yes

the project key


>string

identifier

path

yes

the version/component identifier


>string

key

path

yes

the user-defined key of the metadata


>string

JiraMetadata

body

yes

the to change metadata


JiraMetadata

Response

**Content-Type: ** application/json

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation

JiraMetadata

400

the given key doesn't match to the key of the JiraMetadata object, the specified version/component can't be loaded or something went wrong while loading the saved metadata


403

User has no permission to create / update metadata


500

something went wrong while saving the metadata


503

Invalid license


DELETE

delete the specified metadata

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

projectkey

path

yes

the project key


>string

identifier

path

yes

the version/component identifier


>string

key

path

yes

the user-defined key of the metadata


>string

Response

**Content-Type: ** text/plain

Status Code

Reason

Response Model

-------------

-------------

----------------

400

the specified version/component can't be loaded


403

User has no permission to create / update metadata


404

there is no metadata object with the given key


503

Invalid license


/version/{projectkey}/{identifier}/{key}/value

GET

get the specified metadata value

 Details

Request

Parameters

Name

Located in

Required

Description

Default

Schema

projectkey

path

yes

the project key


>string

identifier

path

yes

the version/component identifier


>string

key

path

yes

the user-defined key of the metadata


>string

Response

**Content-Type: ** text/plain

Status Code

Reason

Response Model

-------------

-------------

----------------

200

successful operation


Json-Objects

JiraMetadata

name

type

required

description

example

key

string

required

the userdefined key of the metadata


group

string

optional



value

string

optional



hidden

boolean

optional



Message

name

type

required

description

example

message

string

optional



ProjectConfiguration

name

type

required

description

example

editPermission

boolean

optional



selectionItems

array[ #/definitions/SelectionItem ]

optional



screen

string

optional



SelectionItem

name

type

required

description

example

label

string

optional



value

string

optional



projectKey

string

optional



items

array[ #/definitions/SelectionItem ]

optional