The Confluence Cloud REST API

Content - attachments

Get attachments

GET /wiki/rest/api/content/{id}/child/attachment

Returns the attachments for a piece of content.

By default, the following objects are expanded: metadata.

Permissions required: Permission to view the content. If the content is a blog post, 'View' permission for the space is required.

App scope required: READ

OAuth scopes required:

read:confluence-content.summary

Request

Path parameters

id Required

string

The ID of the content to be queried for its attachments.

Query parameters

expand

Array<string>

A multi-value parameter indicating which properties of the content to expand.

childTypes.all returns whether the content has attachments, comments, or child pages. Use this if you only need to check whether the content has children of a particular type.
childTypes.attachment returns whether the content has attachments.
childTypes.comment returns whether the content has comments.
childTypes.page returns whether the content has child pages.
container returns the space that the content is in. This is the same as the information returned by Get space.
metadata.currentuser returns information about the current user in relation to the content, including when they last viewed it, modified it, contributed to it, or added it as a favorite.
metadata.properties returns content properties that have been set via the Confluence REST API.
metadata.labels returns the labels that have been added to the content.
metadata.frontend this property is only used by Atlassian.
operations returns the operations for the content, which are used when setting permissions.
children.page returns pages that are descendants at the level immediately below the content.
children.attachment returns all attachments for the content.
children.comment returns all comments on the content.
restrictions.read.restrictions.user returns the users that have permission to read the content.
restrictions.read.restrictions.group returns the groups that have permission to read the content. Note that this may return deleted groups, because deleting a group doesn't remove associated restrictions.
restrictions.update.restrictions.user returns the users that have permission to update the content.
restrictions.update.restrictions.group returns the groups that have permission to update the content. Note that this may return deleted groups because deleting a group doesn't remove associated restrictions.
history returns the history of the content, including the date it was created.
history.lastUpdated returns information about the most recent update of the content, including who updated it and when it was updated.
history.previousVersion returns information about the update prior to the current content update.
history.contributors returns all of the users who have contributed to the content.
history.nextVersion returns information about the update after to the current content update.
ancestors returns the parent page, if the content is a page.
body returns the body of the content in different formats, including the editor format, view format, and export format.
version returns information about the most recent update of the content, including who updated it and when it was updated.
descendants.page returns pages that are descendants at any level below the content.
descendants.attachment returns all attachments for the content, same as children.attachment.
descendants.comment returns all comments on the content, same as children.comment.
space returns the space that the content is in. This is the same as the information returned by Get space.

In addition, the following comment-specific expansions can be used:

extensions.inlineProperties returns inline comment-specific properties.
extensions.resolution returns the resolution status of each comment.

Style: form

Valid values: childTypes.all, childTypes.attachment, childTypes.comment, childTypes.page, container, metadata.currentuser, metadata.properties, metadata.labels, metadata.frontend, operations ...(Show more)

start

integer

The starting index of the returned attachments.

Default: 0, Minimum: 0, Format: int32

limit

integer

The maximum number of attachments to return per page. Note, this may be restricted by fixed system limits.

Default: 25, Minimum: 0, Format: int32

filename

string

Filter the results to attachments that match the filename.

mediaType

string

Filter the results to attachments that match the media type.

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'https://your-domain.atlassian.net/wiki/rest/api/content/{id}/child/attachment' \
  --header 'Accept: application/json'

Responses

200

404

Returned if the requested attachments are returned.

Content type	Value
application/json	ContentArray

Create or update attachment

PUT /wiki/rest/api/content/{id}/child/attachment

Adds an attachment to a piece of content. If the attachment already exists for the content, then the attachment is updated (i.e. a new version of the attachment is created).

Note, you must set a X-Atlassian-Token: nocheck header on the request for this method, otherwise it will be blocked. This protects against XSRF attacks, which is necessary as this method accepts multipart/form-data.

The media type 'multipart/form-data' is defined in RFC 1867. Most client libraries have classes that make it easier to implement multipart posts, like the MultiPartEntity Java class provided by Apache HTTP Components.

Example: This curl command attaches a file ('example.txt') to a piece of content (id='123') with a comment and minorEdits=true. If the 'example.txt' file already exists, it will update it with a new version of the attachment.

curl -D- \
  -u admin:admin \
  -X PUT \
  -H "X-Atlassian-Token: nocheck" \
  -F "file=@example.txt" \
  -F "minorEdit=true" \
  -F "comment=Example attachment comment" \
  http://myhost/rest/api/content/123/child/attachment

Permissions required: Permission to update the content.

App scope required: WRITE

OAuth scopes required:

write:confluence-file

Request

Path parameters

id Required

string

The ID of the content to add the attachment to.

Query parameters

status

string

The status of the content that the attachment is being added to. This should always be set to 'current'.

Default: current

Valid values: current, draft

Body parameters

Content type	Value
multipart/form-data	object

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request PUT \
  --url 'https://your-domain.atlassian.net/wiki/rest/api/content/{id}/child/attachment' \
  --header 'Accept: application/json'

Responses

200

403

404

Returned if the attachments were added to the content.

Content type	Value
application/json	ContentArray

Create attachment

POST /wiki/rest/api/content/{id}/child/attachment

Adds an attachment to a piece of content. This method only adds a new attachment. If you want to update an existing attachment, use Create or update attachments.

Example: This curl command attaches a file ('example.txt') to a container (id='123') with a comment and minorEdits=true.

curl -D- \
  -u admin:admin \
  -X POST \
  -H "X-Atlassian-Token: nocheck" \
  -F "file=@example.txt" \
  -F "minorEdit=true" \
  -F "comment=Example attachment comment" \
  http://myhost/rest/api/content/123/child/attachment

Permissions required: Permission to update the content.

App scope required: WRITE

OAuth scopes required:

write:confluence-file

Request

Path parameters

id Required

string

The ID of the content to add the attachment to.

Query parameters

status

string

The status of the content that the attachment is being added to.

Default: current

Valid values: current, draft

Body parameters

Content type	Value
multipart/form-data	object

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request POST \
  --url 'https://your-domain.atlassian.net/wiki/rest/api/content/{id}/child/attachment' \
  --header 'Accept: application/json'

Responses

200

400

403

404

Returned if the attachments were added to the content.

Content type	Value
application/json	ContentArray

Update attachment properties

PUT /wiki/rest/api/content/{id}/child/attachment/{attachmentId}

Updates the attachment properties, i.e. the non-binary data of an attachment like the filename, media-type, comment, and parent container.

Permissions required: Permission to update the content.

App scope required: WRITE

OAuth scopes required:

write:confluence-file

write:confluence-props

Request

Path parameters

id Required

string

The ID of the content that the attachment is attached to.

attachmentId Required

string

The ID of the attachment to update.

Body parameters

version Required

object

The attachment version. Set this to the current version number of the attachment. Note, the version number only needs to be incremented when updating the actual attachment, not its properties.

id Required

string

The ID of the attachment to be updated.

type Required

string

Set this to attachment.

Valid values: attachment

title

string

The updated name of the attachment.

Max length: 255

metadata

object

container

object

The new content to attach the attachment to.

Example

cURL

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'https://your-domain.atlassian.net/wiki/rest/api/content/{id}/child/attachment/{attachmentId}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "version": {
    "number": 19
  },
  "id": "<string>",
  "type": "attachment",
  "title": "<string>",
  "metadata": {
    "mediaType": "<string>",
    "comment": "<string>"
  },
  "container": {
    "id": "<string>",
    "type": "<string>"
  }
}'

Responses

200

400

403

404

409

Returned if the attachment is updated.

Content type	Value
application/json	Content

Update attachment data

POST /wiki/rest/api/content/{id}/child/attachment/{attachmentId}/data

Updates the binary data of an attachment, given the attachment ID, and optionally the comment and the minor edit field.

This method is essentially the same as Create or update attachments, except that it matches the attachment ID rather than the name.

Example: This curl command updates an attachment (id='att456') that is attached to a piece of content (id='123') with a comment and minorEdits=true.

curl -D- \
  -u admin:admin \
  -X POST \
  -H "X-Atlassian-Token: nocheck" \
  -F "file=@example.txt" \
  -F "minorEdit=true" \
  -F "comment=Example attachment comment" \
  http://myhost/rest/api/content/123/child/attachment/att456/data

Permissions required: Permission to update the content.

App scope required: WRITE

OAuth scopes required:

write:confluence-file

Request

Path parameters

id Required

string

The ID of the content that the attachment is attached to.

attachmentId Required

string

The ID of the attachment to update.

Body parameters

Content type	Value
multipart/form-data	object

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request POST \
  --url 'https://your-domain.atlassian.net/wiki/rest/api/content/{id}/child/attachment/{attachmentId}/data' \
  --header 'Accept: application/json'

Responses

200

400

404

Returned if the attachment is updated.

Content type	Value
application/json	Content

Confluence Cloud Developer

Confluence Cloud Developer

Content - attachments

Get attachments

Request

Path parameters

Query parameters

Example

Responses

Create or update attachment

Request

Path parameters

Query parameters

Body parameters

Example

Responses

Create attachment

Request

Path parameters

Query parameters

Body parameters

Example

Responses

Update attachment properties

Request

Path parameters

Body parameters

Example

Responses

Update attachment data

Request

Path parameters

Body parameters

Example

Responses