Search for apps using JSON

The /rest/2/addons API lets you query app listings. You may wish to use this, for instance, to write a script that outputs information about every app that meets some criteria.

For an example of such a script (using the Bash shell and curl), see list-addons.sh in the Marketplace API Tutorials repository.

Prerequisites

You will need:

Any tool for making HTTP requests

Step 1: Get the resource URL

The base URL for the app collection resource is currently https://marketplace.atlassian.com/rest/2/addons (with optional query parameters as described below).

Rather than hard-coding the URL path for the resource, you can also obtain it by starting from the entry point of the API. This takes additional steps, but is a better practice in case resource paths ever change in the future.

Do a GET request to https://marketplace.atlassian.com/rest/2--you will receive a JSON response that looks something like this:

1
2
{
  "_links": {
    "self": {
      "href": "/rest/2"
    },
    [some more links...]
    "addons": {
      "href": "/rest/2/addons"
    }
  }
}

The href property under addons provides the URL path for the app collection resource.

Step 2: Optional query parameters

The following optional parameters can be used to filter and/or sort your search query:

Parameter Name	Description
`application`	Only returns apps compatible with the specified application
`applicationBuild`	Only returns apps compatible with the specified application build number; `application` parameter must also be specified
`category`	Only returns apps with the specified categories; `application` parameter must also be specified
`cost`	Only returns apps with the specified paid/free status
`filter`	Return apps filtered or sorted using the specified parameter
`forThisUser`	Only returns apps from vendors associated with the current user; you have to be authenticated to use this
`hosting`	Only returns apps with the specified hosting model
`includeHidden`	Includes apps that are normally hidden in the site; default value is `false`
`includePrivate`	Includes private apps if you are authorized to see them (you have to be authenticated to use this); default value is `false`
`text`	Only returns apps that match the search text
1 2 `withVersion`	Includes the latest compatible app version in the response (it will be in `/_embedded/versions` within each app item)

The offset and limit parameters are used for pagination to limit the number of apps returned by the search query.

Rather than referring to this table, you can get the list of supported parameters directly from the API:

Do a GET request to the app collection resource, adding ?limit=0 to indicate that you don't want any app data but only the links: https://marketplace.atlassian.com/rest/2/addons?limit=0

In the JSON response, look for the query link:

1
2
{
  "_links": {
    [...other links that you can ignore...]
    "query": {
      "href": "/rest/2/addons{?application,applicationBuild,category*,cost,filter,forThisUser,hosting,includeHidden,includePrivate,text,withVersion,offset,limit}",
      "templated": true
    }
  }
}

The templated property for this link indicates that it is a link template; in its href value, the symbols within curly braces indicate all the optional query parameters that you can use, using URI Template syntax.

Step 3: Perform the query

Request

HTTP method: GET
URL: the app collection resource, as described above, along with any optional query parameters
Authentication: if you want to see private or user-specific data (using forThisUserOnly or includePrivate), you must provide Basic Authentication with the username and password of your Atlassian Account

Example of a curl request to get free apps that are compatible with Jira:

1
2
$ curl "https://marketplace.atlassian.com/rest/2/addons?application=jira&cost=free"

Response

1
2
{
  "_links": {
    "self": {
      "href": "/rest/2/addons?application=jira&cost=free"
    },
    "alternate": {
      "href": "/plugins/app/jira?cost=free"
    }
    "next": [
      {
        "href": "/rest/2/addons?application=jira&cost=free&offset=10",
        "type": "application/json"
      },
      {
        "href": "/plugins/app/jira?cost=free&offset=10",
        "type": "text/html"
      }
    ]
  },
  "_embedded": {
    "addons": [
      {
        "_links": {
          "self": {
            "href": "/rest/2/addons/some-addon-key"
          }
        },
        "key": "some-app-key",
        "name": "Some App",
        [... more app properties ...]
      },
      [... more app items ...]
    ]
  },
  "count": 125
}

Response properties

/_links/alternate: A web link for viewing the corresponding list of results on the Marketplace site.
/_links/next: This will only be present if there are additional pages of results available after this one (the default size of a page is 10, unless you specify otherwise using limit). This is not a single link, but an array of two links: the first is a resource link for getting the next page via REST (content type "application/json"), and the second is a web link for displaying the next page of results on the Marketplace site (like the alternate link).
/embedded/addons: An array containing the app items. Note that these do not contain all properties of each app, but only a subset of the properties; to view all the properties, you can query the individual app resource using the self link for that item.
/count: the total number of results matched by the query, even if it is more than will fit in a single result page.