The Assets Platform REST API

Assets

This resource represents assets in Jira. These assets may have been populated in Jira from another application. Use this resource to get, search for, create, update, and delete assets in Jira.

Bulk create or update assets

PUT /rest/assetapi/asset/bulk

Creates new assets or updates existing assets. Note that updating assets will overwrite their properties with the properties defined in the request object.

Request

Body parameters

putRequest

Array<asset>

A list of up to 25 assets to be created or updated.

Example

cURL

Node.js

Java

Python

PHP

curl --request PUT \
  --url '/rest/assetapi/asset/bulk' \
  --header 'Content-Type: application/json' \
  --data '{
  "putRequest": [
    {
      "origin": {
        "appKey": "com.myasset.app",
        "originId": "5-113-51143-2032"
      },
      "label": {
        "value": "MacBook Pro 15\" 2016"
      },
      "type": {
        "appKey": "com.myasset.app",
        "originId": "5-113-51143-2032"
      },
      "assignee": {
        "accountId": "27505:c73cd17f-ae93-4f10-911c-d754d02420be",
        "email": "test@example.com"
      },
      "fields": [
        {
          "fieldId": "RAM",
          "value": "8GB DDR4 2400MHz"
        }
      ]
    }
  ]
}'

Responses

202

400

403

429

Returned if the resource is accepted to be asynchronously processed.

A schema has not been defined for this response code.

Get all assets

GET /rest/assetapi/asset

Returns a list of all assets

Request

Query parameters

type

Array<string>

The asset type to filter by. Set this to the concatenation of the asset type’s appKey and originId, in the format appKey/originId.

Unique items: true

start

integer

The index of the first item to return in a page of results (page offset).

Default: 0, Format: int32

limit

integer

The maximum number of items to return per page. Note that this may be constrained by the Assets platform service.

Default: 20, Minimum: 0, Maximum: 100, Format: int32

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url '/rest/assetapi/asset' \
  --header 'Accept: application/json'

Responses

200

403

429

Returned if the request is successful. The response may be empty, if no results are found.

Content type	Value
application/json	pagedAssets

Create or update asset

PUT /rest/assetapi/asset

Creates a new asset or updates an existing asset. Note that updating an asset will overwrite its properties with the properties defined in the request object.

Request

Body parameters

Asset

origin Required

origin

The asset type's origin.

label Required

label

The asset type's label.

type

origin

The asset type's origin.

assignee

assignee

The asset's assignee.

fields

Array<fieldValue>

The list of asset's fields, this is an arbitrary list of vendor specific fields which will be available for searching.

Example

cURL

Node.js

Java

Python

PHP

curl --request PUT \
  --url '/rest/assetapi/asset' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "origin": {
    "appKey": "com.myasset.app",
    "originId": "5-113-51143-2032"
  },
  "label": {
    "value": "MacBook Pro 15\" 2016"
  },
  "type": {
    "appKey": "com.myasset.app",
    "originId": "5-113-51143-2032"
  },
  "assignee": {
    "accountId": "27505:c73cd17f-ae93-4f10-911c-d754d02420be",
    "email": "test@example.com"
  },
  "fields": [
    {
      "fieldId": "RAM",
      "value": "8GB DDR4 2400MHz"
    }
  ]
}'

Responses

200

201

400

403

429

Returned if the resource is updated.

Content type	Value
application/json	asset

Get an asset by its origin

GET /rest/assetapi/asset/{appKey}/{originId}

Request

Path parameters

appKey Required

string

The app key, which should be the Connect app key. This parameter is used to scope the originId.

originId Required

string

The identifier of an asset/asset type. This is the same identifier for the asset/asset type in its origin (external) system.

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url '/rest/assetapi/asset/{appKey}/{originId}' \
  --header 'Accept: application/json'

Responses

200

403

404

429

Returned if the request is successful.

Content type	Value
application/json	asset

Delete an asset

DELETE /rest/assetapi/asset/{appKey}/{originId}

Request

Path parameters

appKey Required

string

The app key, which should be the Connect app key. This parameter is used to scope the originId.

originId Required

string

The identifier of an asset/asset type. This is the same identifier for the asset/asset type in its origin (external) system.

Example

cURL

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url '/rest/assetapi/asset/{appKey}/{originId}'

Responses

200

403

404

429

Returned if the request is successful.

A schema has not been defined for this response code.

Search assets

GET /rest/assetapi/asset/search

Searches assets matching the query parameter. Only assets with an appKey matching an installed asset management app will be returned. If no asset management apps are installed, falls back to returning all assets.

Request

Query parameters

query

string

The search term that will be matched with either label, origin or fields values.

type

Array<string>

The asset type to filter the search by. Set this to the concatenation of the asset type’s appKey and originId, in the format appKey/originId.

Unique items: true

assignee

Array<string>

The assignees to filter the search by. Set one of these values to unassigned if you want to include unassigned assets.

Unique items: true

prioritizedAssignee

Array<string>

The assignee the search is prioritized by. This means that results with an assignee matching this one will be promoted to the top of the list. If multiple prioritizedAssignee parameters are specified, only the first one will be used.

limit

integer

The maximum number of items to return per page. Note that this may be constrained by the Assets platform service.

Default: 10, Minimum: 0, Maximum: 100, Format: int32

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url '/rest/assetapi/asset/search' \
  --header 'Accept: application/json'

Responses

200

400

403

429

Returns a list of assets ordered by relevance to the query parameter. The response may be empty, if no matching assets were found.

Content type	Value
application/json	asset