Confluence REST API documentation

POST

Converts between content body representations.

Not all representations can be converted to/from other formats. Supported conversions:

Source Representation	Destination Representation Supported
storage	view,export_view,editor
editor	storage
view	None
export_view	None

acceptable request representations:

• application/json [expand]

available response representations:

• application/json [expand]

GET

Returns a paginated list of attachment Content entities within a single container.

Example request URIs:

1. http://example.com/rest/api/content/1234/attachments?start=0&limit=10
2. http://example.com/rest/api/content/1234/attachments?filename=myfile.txt&expand=version,container

request query parameters

parameter	value	description
expand	string Default:
start	int
limit	int Default: 50
filename	string
mediaType	string

available response representations:

• [expand]
  Returned if there is no content with the given id, or if the calling user does not have permission to view the content.

available response representations:

• application/json (attachments) [expand]
  Returns a JSON representation of a list of attachment Content entities

  XML Schema

  Source:

POST

Add one or more attachments to a Confluence Content entity, with optional comments.

Comments are optional, but if included there must be as many comments as there are files, and the comments must be in the same order as the files.

This resource expects a multipart post. The media-type multipart/form-data is defined in RFC 1867. Most client libraries have classes that make dealing with multipart posts simple. For instance, in Java the Apache HTTP Components library provides a MultiPartEntity that makes it simple to submit a multipart POST.

In order to protect against XSRF attacks, because this method accepts multipart/form-data, it has XSRF protection on it. This means you must submit a header of X-Atlassian-Token: nocheck with the request, otherwise it will be blocked.

The name of the multipart/form-data parameter that contains attachments must be "file"

A simple example to attach a file called "myfile.txt" to the container with id "123", with a comment included:

curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: nocheck" -F "file=@myfile.txt;comment=This is my File" http://myhost/rest/api/1/content/123/attachments

A example to attach a file called "myfile.txt" to the container with id "123", with a comment, and set the minorEdits flag to be true:

curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: nocheck" -F "file=@myfile.txt;minorEdit=true;comment=This is my
               File" http://myhost/rest/api/1/content/123/attachments

An example to upload the same file, with no comment:

curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: nocheck" -F "file=@myfile.txt" http://myhost/rest/api/1/content/123/attachments/456/data

Example request URIs:

1. http://example.com/rest/api/content/1234/attachments

available response representations:

• [expand]
  Returned if the requested content is not found, the user does not have permission to view it, or if the attachments exceeds the maximum configured attachment size.

available response representations:

• application/json [expand]

available response representations:

• [expand]
  Returned if attachments is disabled or if you don't have permission to add attachments to this content.

PUT

Update the non-binary data of an Attachment.

This resource can be used to update an attachment's filename, media-type, comment, and parent container.

Example request URI:

1. http://example.com/rest/api/content/1234/attachments/5678

acceptable request representations:

• application/json [expand]

available response representations:

• [expand]
  Returned if the version of the supplied Attachment does not match the next version of the Attachment stored in the database.

available response representations:

• [expand]
  Returned if no attachment is found for the attachmentId.

available response representations:

• application/json [expand]

available response representations:

• [expand]
  Returned if the attachment id or the attachment version number are invalid.

available response representations:

• [expand]
  Returned if you are not permitted to update or move the attachment to a different container.

POST

Update the binary data of an Attachment, and optionally the comment.

Comments are optional, but if included there must be as many comments as there are files, and the comments must be in the same order as the files.

This resource expects a multipart post. The media-type multipart/form-data is defined in RFC 1867. Most client libraries have classes that make dealing with multipart posts simple. For instance, in Java the Apache HTTP Components library provides a MultiPartEntity that makes it simple to submit a multipart POST.

In order to protect against XSRF attacks, because this method accepts multipart/form-data, it has XSRF protection on it. This means you must submit a header of X-Atlassian-Token: nocheck with the request, otherwise it will be blocked.

The name of the multipart/form-data parameter that contains attachments must be "file"

A simple example to upload a file called "myfile.txt" to the Attachment with id "456" in a container with id "123", with the comment updated, and minorEdit set to true:

curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: nocheck" -F "file=@myfile.txt;minorEdit=true;comment=This is my
               updated File" http://myhost/rest/api/1/content/123/attachments/456/data

An example to upload the same file, with no comment:

curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: nocheck" -F "file=@myfile.txt" http://myhost/rest/api/1/content/123/attachments/456/data

Example request URI:

1. http://example.com/rest/api/content/1234/attachments/5678/data

available response representations:

• [expand]
  Returned if no attachment is found for the attachmentId.

available response representations:

• application/json [expand]

available response representations:

• [expand]
  Returned if the attachment id is invalid.

GET

Returns a piece of Content.

Example request: http://example.com/rest/api/content/1234?expand=space,body.view,version,container

request query parameters

parameter	value	description
type	string Default: page
spaceKey	string
title	string
postingDay	string
expand	string Default:	A comma separated list of properties to expand on the content. Default value: history,space,version
start	int
limit	int Default: 25

available response representations:

• [expand]
  Returned if there is no content with the given id, or if the calling user does not have permission to view the content.

available response representations:

• application/json (content) [expand]
  Returns a full JSON representation of a piece of content

  XML Schema

  Source:

POST

Creates a new piece of Content.

acceptable request representations:

• application/json [expand]

available response representations:

• application/json (content) [expand]
  Returns a full JSON representation of a piece of content

  XML Schema

  Source:

DELETE

Deletes a piece of Content.

GET

Returns a piece of Content.

Example request: http://example.com/rest/api/content/1234?expand=space,body.view,version,container

request query parameters

parameter	value	description
expand	string Default: history,space,version	A comma separated list of properties to expand on the content. Default value: history,space,version

available response representations:

• [expand]
  Returned if there is no content with the given id, or if the calling user does not have permission to view the content.

available response representations:

• application/json (content) [expand]
  Returns a full JSON representation of a piece of content

  XML Schema

  Source:

PUT

Updates a piece of Content.

The body contains the representation of the content.

acceptable request representations:

• application/json [expand]

available response representations:

• [expand]
  Returned if there is no content with the given id, or if the calling user does not have permission to view the content.

available response representations:

• application/json (content) [expand]
  Returns a full JSON representation of a piece of content

  XML Schema

  Source:

GET

Returns the history of a particular piece of content

request query parameters

parameter	value	description
expand	string Default:	the properties on content history to expand

available response representations:

• [expand]
  Returned if there is no content with the given id, or if the calling user does not have permission to view the content.

available response representations:

• application/json (history) [expand]
  Returns a full JSON representation of the content's history

  XML Schema

  Source:

GET

Returns the body of a macro (in storage format) with the given hash. This resource is primarily used by connect applications that require the body of macro to perform their work.

The hash is generated by connect during render time of the local macro holder and is usually only relevant during the scope of one request. For optimisation purposes, this hash will usually live for multiple requests.

available response representations:

• [expand]
  Returned if there is no content with the given id, or if the calling user does not have permission to view the content, or there is no macro matching the given hash.

available response representations:

• application/json (macro) [expand]
  Returns a json representation of a macro.

  XML Schema

  Source:

GET

Returns the list of labels on a piece of Content.
Example request: http://example.com/rest/api/content/1234/labels?prefix=global&start=0&limit=200

request query parameters

parameter	value	description
prefix	string
start	int
limit	int Default: 200

available response representations:

• [expand]
  Returned if there is no content with the given id, or if the calling user does not have permission to view the content.

available response representations:

• application/json (labels) [expand]
  Returns a JSON representation of the labels on a piece of content

  XML Schema

  Source:

POST

Adds a list of labels to the specified content.

The body is the json representation of the list.

Example body: [ { "prefix": "global", "name": "label2" }, { "prefix": "global", "name": "label2" } ]

acceptable request representations:

• application/json [expand]

available response representations:

• [expand]
  Returned if there is no content with the given id, or if the calling user does not have permission to view the content.

available response representations:

• application/json (labels) [expand]
  Returns a JSON representation of the labels on a piece of content

  XML Schema

  Source:

GET

Returns a map of the descendants of a piece of Content. Content can have multiple types of descendants - for example a Page can have descendants that are also Pages, but it can also have Comments and Attachments.

The {@link ContentType}(s) of the descendants returned is specified by the "expand" query parameter in the request - this parameter can include expands for multiple descendant types.
If no types are included in the expand parameter, the map returned will just list the descendant types that are available to be expanded for the {@link Content} referenced by the "id" path parameter.

Currently the only supported descendants are comment descendants of non-comment Content.

Example requests for a page with id "1234":

• http://example.com/rest/api/content/1234/descendant
• http://example.com/rest/api/content/1234/descendant?expand=comment.body.VIEW
• http://example.com/rest/api/content/1234/descendant?expand=comment&start=20&limit=10

request query parameters

parameter	value	description
expand	string Default:

available response representations:

• [expand]
  Returned if there is no content with the given id, or if the calling user does not have permission to view the content.

available response representations:

• application/json (descendants_map) [expand]
  Returns a JSON map representing multiple ordered collections of content descendants, keyed by content type

  XML Schema

  Source:

GET

Returns the direct descendants of a piece of Content, limited to a single descendant type.

The {@link ContentType}(s) of the descendants returned is specified by the "type" path parameter in the request.

Currently the only supported descendants are comment descendants of non-comment Content.

Example requests for a page with id "1234":

• http://example.com/rest/api/content/1234/descendant/comment
• http://example.com/rest/api/content/1234/descendant/comment?expand=body.VIEW
• http://example.com/rest/api/content/1234/descendant/comment?start=20&limit=10

request query parameters

parameter	value	description
expand	string Default:
start	int
limit	int Default: 25

available response representations:

• [expand]
  Returned if there is no content with the given id, or if the calling user does not have permission to view the content.

available response representations:

• application/json (descendants) [expand]
  Returns a JSON map representing multiple ordered collections of content descendants, keyed by content type

  XML Schema

  Source:

GET

request query parameters

parameter	value	description
spaceKey	string
expand	string Default:
start	int
limit	int Default: 25

available response representations:

• application/json [expand]

POST

Creates a new Space.

The incoming Space does not include an id, but must include a Key and Name, and should include a Description.

acceptable request representations:

• application/json [expand]

available response representations:

• application/json (space) [expand]
  Returns a full JSON representation of a space

  XML Schema

  Source:

GET

Returns the content in this given space

Example request: http://example.com/rest/api/space/TEST/content/1234?expand=space,body.view,version,container

request query parameters

parameter	value	description
depth	string Default: all
expand	string Default:
start	int
limit	int Default: 25

available response representations:

• [expand]
  Returned if there is no content with the given id, or if the calling user does not have permission to view the content.

available response representations:

• application/json (content) [expand]
  Returns a full JSON representation of a piece of content

  XML Schema

  Source:

GET

Returns information about a space.

request query parameters

parameter	value	description
expand	string Default:	a comma separated list of properties to expand on the space

available response representations:

• [expand]
  Returned if there is no space with the given key, or if the calling user does not have permission to view the space.

available response representations:

• application/json (space) [expand]
  Returns a full JSON representation of a space

  XML Schema

  Source:

POST

Creates a new private Space, viewable only by its creator.

The incoming Space does not include an id, but must include a Key and Name, and should include a Description.

acceptable request representations:

• application/json [expand]

available response representations:

• application/json (space) [expand]
  Returns a full JSON representation of a space

  XML Schema

  Source:

GET

Returns the content in this given space with the given type

Example request: http://example.com/rest/api/space/TEST/content/1234?type=page,expand=space,body.view,version,container

request query parameters

parameter	value	description
depth	string Default: all
expand	string Default:
start	int
limit	int Default: 25

available response representations:

• [expand]
  Returned if there is no content with the given id, or if the calling user does not have permission to view the content.

available response representations:

• application/json (content) [expand]
  Returns a full JSON representation of a piece of content

  XML Schema

  Source:

GET

Returns a map of the direct children of a piece of Content. Content can have multiple types of children - for example a Page can have children that are also Pages, but it can also have Comments and Attachments.

The {@link ContentType}(s) of the children returned is specified by the "expand" query parameter in the request - this parameter can include expands for multiple child types.
If no types are included in the expand parameter, the map returned will just list the child types that are available to be expanded for the {@link Content} referenced by the "id" path parameter.

Example requests:

• http://example.com/rest/api/content/1234/children
• http://example.com/rest/api/content/1234/children?expand=page.body.VIEW,comment
• http://example.com/rest/api/content/1234/children?expand=page&start=20&limit=10

request query parameters

parameter	value	description
expand	string Default:

available response representations:

• [expand]
  Returned if there is no content with the given id, or if the calling user does not have permission to view the content.

available response representations:

• application/json (children_map) [expand]
  Returns a JSON map representing multiple ordered collections of content children, keyed by content type

  XML Schema

  Source:

GET

Returns the direct children of a piece of Content, limited to a single child type.

The {@link ContentType}(s) of the children returned is specified by the "type" path parameter in the request.

Example requests:

• http://example.com/rest/api/content/1234/children/page
• http://example.com/rest/api/content/1234/children/comment
• http://example.com/rest/api/content/1234/children/page?expand=body.VIEW
• http://example.com/rest/api/content/1234/children/comment?start=20&limit=10

request query parameters

parameter	value	description
expand	string Default:
start	int
limit	int Default: 25

available response representations:

• [expand]
  Returned if there is no content with the given id, or if the calling user does not have permission to view the content.

available response representations:

• application/json (children) [expand]
  Returns a JSON map representing multiple ordered collections of content children, keyed by content type

  XML Schema

  Source: