The Marketplace API is a RESTful API that allows you to manage add-ons and your vendor account.
Version 2 is the latest release of the Marketplace API. View the latest API documentation in the Marketplace API reference.
The Marketplace API uses HTTP basic authentication and your Atlassian account. Once authenticated, you can view and modify most properties of your add-ons and your account. If you are not logged in, you are considered an unauthenticated user and will not be able to edit add-ons or vendor information.
All URIs start with theprefix:
When a resource provides a link to another resource, the link URI will not include the hostname (for instance, the link will be
/rest/2/addons rather than
URIs referring to content that is not provided by Atlassian Marketplace are always absolute (that is, they use http:// or https://) and are encoded as ordinary string properties.
All request and response representations are in JSON and use the content type
application/json with the UTF-8 character set, except for
The Marketplace API uses standard HTTP methods. Successful
PATCH requests return a
Location header in addition to the HTTP status codes documented below. Successful
DELETE requests return only the status code. See Errors for information about responses that return an error.
||Creates a new entity||201|
||Modifies all editable properties of existing entity. It cannot be applied to a collection resource||204|
Modifies only selected properties of an existing entity. It cannot be applied to a collection resource
Request bodies use the JSON Patch document structure with the content type
||Removes an entity. It cannot be applied to a collection resource and accepts no request body||204|
The Marketplace API uses pagination to limit response size for resources that may return large numbers of results. HTTP clients may specify a smaller page size of N by adding the query parameter
limit=N. A client may also specify a starting offset for a paginated resource by adding the query parameter
offset=N, meaning that the first N items are skipped. Non-paginated resources ignore the
offsetOptional. Specifies the number of items to skip. The default value is 0.
limitOptional. Specifies the maximum page size, between 0 and 50, with a default value of 10. Setting
limit=0returns only the overall properties of a collection resource, such as the total number of available items, without getting the properties of any individual item.
limit argument fails to validate, the API may respond with an error like the example below:
All resources containing links to Atlassian Marketplace resources and web pages use the HAL specification with JSON (with some extensions as described below under
PUT, for cases that HAL does not cover). Such links will always be within a top-level
_embedded object. External links provided by third parties are considered simple data properties and can appear anywhere in a representation.
All resource links should:
- be relative to the host root, for example,
- have a
selflink referring to themselves
Links to the Marketplace website may be absolute or relative URIs. External links must always be absolute URIs.
When available, paginated responses provide the
prev links to retrieve the next or previous page of items:
nextRetrieves the next page of items.
prevRetrieves the previous page of items.
The following response status codes may be accompanied by an error representation.
|400||Request body is malformed or has an illegal property value|
|401||Authentication is required|
|403||User was authenticated but is not authorized for this operation|
|404||Resource does not exist or is not visible to this user|
|409||Resource cannot be created or modified due to some state constraint|
|500||Unexpected internal error in the Atlassian Marketplace|
|502||Unexpected error in an external service|
Error responses may contain a JSON representation with a single top-level property,
errors, that contains an array of objects (each with a message) and optional
code properties. The
path uses JSON Pointer format to refer to an invalid field in the request representation. If
path is not present, the message describes a general condition that isn't tied to a specific field. If present, the
code is a string that uniquely identifies the type of error. An example appears below:
Documentation for API version 1 resources
Version 1 of the Marketplace API remains available and some resource documentation is available.