Marketplace API

The Marketplace API is a RESTful API that allows you to manage add-ons and your vendor account.

Versioning

Version 2 is the latest release of the Marketplace API. View the latest API documentation in the Marketplace API reference.

Authentication

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.

URI structure

All URIs start with the following prefix:

https://marketplace.atlassian.com/rest/2

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 https://marketplace.atlassian.com/rest/2/addons).

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.

Request format

All request and response representations are in JSON and use the content type application/json with the UTF-8 character set, except for PATCH requests.

The Marketplace API uses standard HTTP methods. Successful POST, PUT, and 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.

Method Description Successful response
GET All GET requests are idempotent 200
POST Creates a new entity 201
PUT Modifies all editable properties of existing entity. It cannot be applied to a collection resource 204
PATCH

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 application/json-patch+json

204
DELETE Removes an entity. It cannot be applied to a collection resource and accepts no request body 204

Pagination

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 limit and offset parameters:

  • offset Optional. Specifies the number of items to skip. The default value is 0.
  • limit Optional. Specifies the maximum page size, between 0 and 50, with a default value of 10. Setting limit=0 returns only the overall properties of a collection resource, such as the total number of available items, without getting the properties of any individual item.

If the limit argument fails to validate, the API may respond with an error like the example below:

{
	errors: [
		{
			message: "limit: Must be an integer"
		}
	]
}

Response format

All resources containing links to Atlassian Marketplace resources and web pages use the HAL specification with JSON (with some extensions as described below under POST and PUT, for cases that HAL does not cover). Such links will always be within a top-level _links or _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, /rest/2/addons
  • have a self link 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 next and prev links to retrieve the next or previous page of items:

  • next Retrieves the next page of items.
  • prev Retrieves the previous page of items.

Errors

The following response status codes may be accompanied by an error representation.

Status Description
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 path and 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:

{
	"errors": [
		{ "message": "There is a general problem." },
		{ "path": "/name", "message": "cannot be longer than 5000 characters" }
	]
}

Documentation for API version 1 resources

Version 1 of the Marketplace API remains available and some resource documentation is available.

If you are using the License Service API, then you need to be approved for access by the Atlassian Marketplace team. This is necessary because the Atlassian Marketplace team audits usage and monitors the performance of the API very closely, subject to the Atlassian Marketplace Vendor Agreement.

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport