{"openapi":"3.0.1","info":{"title":"External Assets Platform API","description":"Assets are identified by `appKey/originId` which is defined in the `origin` field as part of creation. They need to be URL-safe and unique within a Jira instance. We recommend `appKey` to be the same as the Connect descriptor key if possible, otherwise it can be an arbitrary value.","version":"0.1"},"servers":[{"url":"/rest/assetapi","variables":{}}],"tags":[{"name":"Assets","description":"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."},{"name":"Asset types","description":"This resource represents asset types in Jira. Asset types are used to categorize assets. Use this resource to get, create, update, and delete assets in Jira."}],"x-atlassian-narrative":{"documents":[{"title":"Rate Limits","anchor":"rate-limits","body":"All the endpoints are instrumented with rate limiting controls in place to restrict the amount of traffic from clients. This is to protect the External Assets Platform APIs from misbehaving client or denial of service attacks like a single client overloading the system by sending too many requests and disrupting other legitimate clients trying to access the External Assets Platform.\n\n#### Rate limit policy\nRate limits are applied per vendor app key. Currently the rate limit thresholds are configured on a rate limit window of 60 seconds. However the rate limit window is subject to vary in the future.\n\n#### Rate limit response headers\nThe following HTTP response headers are returned indicating the rate and threshold allowed for a client for each endpoint.\n\n- **X-RateLimit-Limit:** The number of allowed requests in the current period.\n- **X-RateLimit-Remaining:** The number of remaining requests in the current period.\n- **X-RateLimit-Reset:** Next period reset time (ISO 8601 - Date and time in UTC)\n\n#### Client Breaching rate limit thresholds\nWhen a client breach the rate limit thresholds, they get [HTTP 429 Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) responses.\nThe client has to wait for the rate limit counter to reset on the server before being able to make successful requests.\n"}]},"paths":{"/asset/bulk":{"put":{"tags":["Assets"],"summary":"Bulk create or update assets","description":"Creates new assets or updates existing assets. Note that updating assets will overwrite their properties with the properties defined in the request object.\n\n","operationId":"createOrUpdate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkAssetsDTO"}}},"required":true},"responses":{"202":{"description":"Returned if the resource is accepted to be asynchronously processed."},"400":{"description":"Returned if the request object is invalid."},"403":{"description":"Returned if the user is not logged in, is inactive, does not have a Jira licence or the asset/asset type limit has been reached for the tenant or vendor."},"429":{"description":"Returned if too many requests sent. Check headers.","headers":{"X-RateLimit-Remaining":{"description":"The number of remaining requests in the current period.","style":"simple","schema":{"type":"integer"}},"Retry-After":{"description":"The number of seconds the client should wait before making a follow-up request.","style":"simple","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Next period reset time (ISO 8601 - Date and time in UTC)","style":"simple","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"The number of allowed requests in the current period.","style":"simple","schema":{"type":"integer"}}}}}}},"/asset":{"get":{"tags":["Assets"],"summary":"Get all assets","description":"Returns a list of all assets","operationId":"getAll","parameters":[{"name":"type","in":"query","description":"The asset type to filter by. Set this to the concatenation of the asset type’s `appKey` and `originId`, in the format `appKey/originId`.","schema":{"uniqueItems":true,"type":"array","items":{"type":"string"}}},{"name":"start","in":"query","description":"The index of the first item to return in a page of results (page offset).","schema":{"type":"integer","format":"int32","default":0}},{"name":"limit","in":"query","description":"The maximum number of items to return per page. Note that this may be constrained by the External Assets Platform service.","schema":{"maximum":100,"minimum":0,"type":"integer","format":"int32","default":20}}],"responses":{"200":{"description":"Returned if the request is successful. The response may be empty, if no results are found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PagedAssetsDTO"}}}},"403":{"description":"Returned if the user is not logged in or is inactive."},"429":{"description":"Returned if too many requests sent. Check headers.","headers":{"X-RateLimit-Remaining":{"description":"The number of remaining requests in the current period.","style":"simple","schema":{"type":"integer"}},"Retry-After":{"description":"The number of seconds the client should wait before making a follow-up request.","style":"simple","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Next period reset time (ISO 8601 - Date and time in UTC)","style":"simple","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"The number of allowed requests in the current period.","style":"simple","schema":{"type":"integer"}}}}}},"put":{"tags":["Assets"],"summary":"Create or update asset","description":"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.","operationId":"createOrUpdate_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetDTO"}}},"required":true},"responses":{"200":{"description":"Returned if the resource is updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetDTO"}}}},"201":{"description":"Returned if the resource is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetDTO"}}}},"400":{"description":"Returned if the request object is invalid."},"403":{"description":"Returned if the user is not logged in, is inactive, does not have a Jira licence or the asset/asset type limit has been reached for the tenant or vendor."},"429":{"description":"Returned if too many requests sent. Check headers.","headers":{"X-RateLimit-Remaining":{"description":"The number of remaining requests in the current period.","style":"simple","schema":{"type":"integer"}},"Retry-After":{"description":"The number of seconds the client should wait before making a follow-up request.","style":"simple","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Next period reset time (ISO 8601 - Date and time in UTC)","style":"simple","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"The number of allowed requests in the current period.","style":"simple","schema":{"type":"integer"}}}}}}},"/asset/{appKey}/{originId}":{"get":{"tags":["Assets"],"summary":"Get an asset by its origin","operationId":"get","parameters":[{"name":"appKey","in":"path","description":"The app key, which should be the Connect app key. This parameter is used to scope the `originId`.","required":true,"schema":{"type":"string"}},{"name":"originId","in":"path","description":"The identifier of an asset/asset type. This is the same identifier for the asset/asset type in its origin (external) system.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returned if the request is successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetDTO"}}}},"403":{"description":"Returned if the user is not logged in or is inactive."},"404":{"description":"Returned if not found."},"429":{"description":"Returned if too many requests sent. Check headers.","headers":{"X-RateLimit-Remaining":{"description":"The number of remaining requests in the current period.","style":"simple","schema":{"type":"integer"}},"Retry-After":{"description":"The number of seconds the client should wait before making a follow-up request.","style":"simple","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Next period reset time (ISO 8601 - Date and time in UTC)","style":"simple","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"The number of allowed requests in the current period.","style":"simple","schema":{"type":"integer"}}}}}},"delete":{"tags":["Assets"],"summary":"Delete an asset","operationId":"delete","parameters":[{"name":"appKey","in":"path","description":"The app key, which should be the Connect app key. This parameter is used to scope the `originId`.","required":true,"schema":{"type":"string"}},{"name":"originId","in":"path","description":"The identifier of an asset/asset type. This is the same identifier for the asset/asset type in its origin (external) system.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returned if the request is successful."},"403":{"description":"Returned if the user is not logged in, is inactive or does not have a Jira licence."},"404":{"description":"Returned if the request object is invalid."},"429":{"description":"Returned if too many requests sent. Check headers.","headers":{"X-RateLimit-Remaining":{"description":"The number of remaining requests in the current period.","style":"simple","schema":{"type":"integer"}},"Retry-After":{"description":"The number of seconds the client should wait before making a follow-up request.","style":"simple","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Next period reset time (ISO 8601 - Date and time in UTC)","style":"simple","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"The number of allowed requests in the current period.","style":"simple","schema":{"type":"integer"}}}}}}},"/asset/search":{"get":{"tags":["Assets"],"summary":"Search assets","description":"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.","operationId":"search","parameters":[{"name":"query","in":"query","description":"The search term that will be matched with either *label*, *origin* or *fields* values.","schema":{"type":"string"}},{"name":"type","in":"query","description":"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`.","schema":{"uniqueItems":true,"type":"array","items":{"type":"string"}}},{"name":"assignee","in":"query","description":"The assignees to filter the search by. Set one of these values to `unassigned` if you want to include `unassigned` assets.","schema":{"uniqueItems":true,"type":"array","items":{"type":"string"}}},{"name":"prioritizedAssignee","in":"query","description":"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.","schema":{"type":"array","items":{"type":"string"}}},{"name":"limit","in":"query","description":"The maximum number of items to return per page. Note that this may be constrained by the External Assets Platform service.","schema":{"maximum":100,"minimum":0,"type":"integer","format":"int32","default":10}}],"responses":{"200":{"description":"Returns a list of assets ordered by relevance to the `query` parameter. The response may be empty, if no matching assets were found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetDTO"}}}},"400":{"description":"Returned if the request object is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetDTO"}}}},"403":{"description":"Returned if the user is not logged in or is inactive."},"429":{"description":"Returned if too many requests sent. Check headers.","headers":{"X-RateLimit-Remaining":{"description":"The number of remaining requests in the current period.","style":"simple","schema":{"type":"integer"}},"Retry-After":{"description":"The number of seconds the client should wait before making a follow-up request.","style":"simple","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Next period reset time (ISO 8601 - Date and time in UTC)","style":"simple","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"The number of allowed requests in the current period.","style":"simple","schema":{"type":"integer"}}}}}}},"/asset/type":{"get":{"tags":["Asset types"],"summary":"Get all asset types","description":"Fetches all available asset types. Only asset types with an appKey matching an installed asset management app will be returned. If no asset management apps are installed, falls back to returning all asset types.","operationId":"getAll_1","parameters":[{"name":"start","in":"query","description":"The index of the first item to return in a page of results (page offset).","schema":{"type":"integer","format":"int32","default":0}},{"name":"limit","in":"query","description":"The maximum number of items to return per page. Note that this may be constrained by the External Assets platform service.","schema":{"type":"integer","format":"int32","default":50}}],"responses":{"200":{"description":"Returned if the request is successful. The response may be empty, if no results are found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PagedAssetTypesDTO"}}}},"403":{"description":"Returned if the user is not logged in or is inactive."},"429":{"description":"Returned if too many requests sent. Check headers.","headers":{"X-RateLimit-Remaining":{"description":"The number of remaining requests in the current period.","style":"simple","schema":{"type":"integer"}},"Retry-After":{"description":"The number of seconds the client should wait before making a follow-up request.","style":"simple","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Next period reset time (ISO 8601 - Date and time in UTC)","style":"simple","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"The number of allowed requests in the current period.","style":"simple","schema":{"type":"integer"}}}}}},"put":{"tags":["Asset types"],"summary":"Create or update an asset type","description":"Creates a new asset type or updates an existing asset type. Note that updating an asset type will overwrite its properties with the properties defined in the request object.","operationId":"createOrUpdate_2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetTypeDTO"}}},"required":true},"responses":{"200":{"description":"Returned if the resource is updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetTypeDTO"}}}},"201":{"description":"Returned if the resource is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetTypeDTO"}}}},"400":{"description":"Returned if the request object is invalid."},"403":{"description":"Returned if the user is not logged in, is inactive, does not have a Jira licence or the asset/asset type limit has been reached for the tenant or vendor."},"429":{"description":"Returned if too many requests sent. Check headers.","headers":{"X-RateLimit-Remaining":{"description":"The number of remaining requests in the current period.","style":"simple","schema":{"type":"integer"}},"Retry-After":{"description":"The number of seconds the client should wait before making a follow-up request.","style":"simple","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Next period reset time (ISO 8601 - Date and time in UTC)","style":"simple","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"The number of allowed requests in the current period.","style":"simple","schema":{"type":"integer"}}}}}}},"/asset/type/{appKey}/{originId}":{"delete":{"tags":["Asset types"],"summary":"Delete an asset type","operationId":"delete_1","parameters":[{"name":"appKey","in":"path","description":"The app key, which should be the Connect app key. This parameter is used to scope the `originId`.","required":true,"schema":{"type":"string"}},{"name":"originId","in":"path","description":"The identifier of an asset/asset type. This is the same identifier for the asset/asset type in its origin (external) system.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Returned if the request is successful."},"403":{"description":"Returned if the user is not logged in, is inactive or does not have a Jira licence."},"404":{"description":"Returned if not found."},"429":{"description":"Returned if too many requests sent. Check headers.","headers":{"X-RateLimit-Remaining":{"description":"The number of remaining requests in the current period.","style":"simple","schema":{"type":"integer"}},"Retry-After":{"description":"The number of seconds the client should wait before making a follow-up request.","style":"simple","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Next period reset time (ISO 8601 - Date and time in UTC)","style":"simple","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"The number of allowed requests in the current period.","style":"simple","schema":{"type":"integer"}}}}}}}},"components":{"schemas":{"AssetDTO":{"title":"asset","required":["label","origin"],"type":"object","properties":{"origin":{"$ref":"#/components/schemas/OriginDTO"},"label":{"$ref":"#/components/schemas/LabelDTO"},"type":{"$ref":"#/components/schemas/OriginDTO"},"assignee":{"$ref":"#/components/schemas/AssigneeDTO"},"fields":{"type":"array","description":"The list of asset's fields, this is an arbitrary list of vendor specific fields which will be available for searching.","items":{"$ref":"#/components/schemas/FieldValueDTO"}}},"description":"Asset"},"AssigneeDTO":{"title":"assignee","type":"object","properties":{"accountId":{"type":"string","description":"The Atlassian account id of the assignee.","example":"27505:c73cd17f-ae93-4f10-911c-d754d02420be"},"email":{"type":"string","description":"Only provide an email if the accountId field is omitted. A mapping from the provided email to an accountId is attempted. If no matching accountId is found, no assignee will be persisted","example":"test@example.com"}},"description":"The asset's assignee."},"BulkAssetsDTO":{"title":"bulkAssets","type":"object","properties":{"putRequest":{"type":"array","description":"A list of up to 25 assets to be created or updated.","items":{"$ref":"#/components/schemas/AssetDTO"}}}},"FieldValueDTO":{"title":"fieldValue","required":["fieldId","value"],"type":"object","properties":{"fieldId":{"type":"string","description":"The field's unique identifier.","example":"RAM"},"value":{"type":"string","description":"The field's value.","example":"8GB DDR4 2400MHz"}},"description":"The list of asset's fields, this is an arbitrary list of vendor specific fields which will be available for searching."},"LabelDTO":{"title":"label","required":["value"],"type":"object","properties":{"value":{"type":"string","description":"The text value of the label.","example":"MacBook Pro 15\" 2016"}},"description":"The asset type's label."},"OriginDTO":{"title":"origin","required":["appKey","originId"],"type":"object","properties":{"appKey":{"type":"string","description":"The app key, which should be the Connect app key. This parameter is used to scope the `originId`.","example":"com.myasset.app"},"originId":{"type":"string","description":"The identifier of an asset/asset type. This is the same identifier for the asset/asset type in its origin (external) system.","example":"5-113-51143-2032"}},"description":"The asset type's origin."},"PagedAssetsDTO":{"title":"pagedAssets","type":"object","properties":{"values":{"type":"array","description":"The list of assets","items":{"$ref":"#/components/schemas/AssetDTO"}},"start":{"type":"integer","description":"The index of the first item to return in a page of results (page offset).","format":"int64"},"limit":{"type":"integer","description":"The maximum number of items to return per page. Note that this may be constrained by the External Assets Platform service.","format":"int32"},"size":{"type":"integer","description":"The number of items in this page.","format":"int32"},"isLastPage":{"type":"boolean","description":"Specifies whether or not this is the last page in the results."}}},"AssetsDTO":{"title":"assets","type":"object","properties":{"values":{"type":"array","description":"The list of assets.","items":{"$ref":"#/components/schemas/AssetDTO"}},"limit":{"type":"integer","description":"The maximum number of items to return per page. Note that this may be constrained by the External Assets Platform service.","format":"int32"},"size":{"type":"integer","description":"The number of items in this page.","format":"int32"}}},"AssetTypeDTO":{"title":"assetType","type":"object","properties":{"origin":{"$ref":"#/components/schemas/OriginDTO"},"label":{"$ref":"#/components/schemas/LabelDTO"}},"description":"Asset Type"},"PagedAssetTypesDTO":{"title":"assetTypes","type":"object","properties":{"values":{"type":"array","description":"The list of asset types.","items":{"$ref":"#/components/schemas/AssetTypeDTO"}},"start":{"type":"integer","description":"The index of the first item to return in a page of results (page offset).","format":"int64"},"limit":{"type":"integer","description":"The maximum number of items to return per page. Note that this may be constrained by the External Assets Platform service.","format":"int32"},"size":{"type":"integer","description":"The number of items in this page.","format":"int32"},"isLastPage":{"type":"boolean","description":"Specifies whether or not this is the last page in the results."}}}}}}