Atlassian Confluence Audit API
The Atlassian Confluence Audit API provides tools to track and monitor user activity within Confluence for compliance and accountability.
OpenAPI Specification
openapi: 3.0.1
info:
title: 'Atlassian wiki/rest/api/audit/'
description: Needs description.
termsOfService: https://atlassian.com/terms/
version: 1.0.0
externalDocs:
description: The online and complete version of the Confluence Cloud REST API docs.
url: https://developer.atlassian.com/cloud/confluence/rest/
servers:
- url: //your-domain.atlassian.net
tags:
- name: Audit
paths:
/wiki/rest/api/audit/export:
get:
tags:
- Audit
summary: Atlassian Export Audit Records
description: >-
Exports audit records as a CSV file or ZIP
file.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>'Confluence Administrator' global permission.
operationId: atlassianExportauditrecords
parameters:
- name: startDate
in: query
description: >-
Filters the exported results to the records on or after the
`startDate`.
The `startDate` must be specified as [epoch
time](https://www.epochconverter.com/) in milliseconds.
schema:
type: string
- name: endDate
in: query
description: >-
Filters the exported results to the records on or before the
`endDate`.
The `endDate` must be specified as [epoch
time](https://www.epochconverter.com/) in milliseconds.
schema:
type: string
- name: searchString
in: query
description: >-
Filters the exported results to records that have string property
values
matching the `searchString`.
schema:
type: string
- name: format
in: query
description: The format of the export file for the audit records.
schema:
type: string
default: csv
enum:
- csv
- zip
responses:
'200':
description: Returned if the requested export of the audit records is returned.
content:
application/zip:
schema:
type: string
format: binary
text/csv:
schema:
type: string
format: binary
'403':
description: >-
Returned if the calling user does not have permission to view the
audit
log.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- read:audit-log:confluence
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:audit-log:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: INACCESSIBLE
/wiki/rest/api/audit/retention:
get:
tags:
- Audit
summary: Atlassian Get Retention Period
description: >-
Returns the retention period for records in the audit log. The
retention<br>period is how long an audit record is kept for, from
creation date until<br>it is
deleted.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>'Confluence Administrator' global permission.
operationId: atlassianGetretentionperiod
responses:
'200':
description: Returned if the requested retention period is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/RetentionPeriod'
'403':
description: >-
Returned if the calling user does not have permission to view the
audit
log.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- read:audit-log:confluence
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:audit-log:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: INACCESSIBLE
put:
tags:
- Audit
summary: Atlassian Set Retention Period
description: >-
Sets the retention period for records in the audit log. The retention
period<br>can be set to a maximum of 1
year.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>'Confluence Administrator' global permission.
operationId: atlassianSetretentionperiod
requestBody:
description: The updated retention period.
content:
application/json:
schema:
$ref: '#/components/schemas/RetentionPeriod'
required: true
responses:
'200':
description: Returned if the retention period is updated.
content:
application/json:
schema:
$ref: '#/components/schemas/RetentionPeriod'
'403':
description: >-
Returned if the calling user does not have permission to view the
audit
log.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:audit-log:confluence
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:audit-log:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-codegen-request-body-name: body
x-atlassian-connect-scope: INACCESSIBLE
/wiki/rest/api/audit/since:
get:
tags:
- Audit
summary: Atlassian Get Audit Records For Time Period
description: >-
Returns records from the audit log, for a time period back from the
current<br>date. For example, you can use this method to get the last 3
months of records.<br><br>This contains information about events like
space exports, group membership<br>changes, app installations, etc. For
more information, see<br>[Audit
log](https://confluence.atlassian.com/confcloud/audit-log-802164269.html)<br>in
the Confluence administrator's
guide.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>'Confluence Administrator' global permission.
operationId: atlassianGetauditrecordsfortimeperiod
parameters:
- name: number
in: query
description: The number of units for the time period.
schema:
type: integer
format: int64
default: 3
- name: units
in: query
description: The unit of time that the time period is measured in.
schema:
type: string
default: MONTHS
enum:
- NANOS
- MICROS
- MILLIS
- SECONDS
- MINUTES
- HOURS
- HALF_DAYS
- DAYS
- WEEKS
- MONTHS
- YEARS
- DECADES
- CENTURIES
- name: searchString
in: query
description: |-
Filters the results to records that have string property values
matching the `searchString`.
schema:
type: string
- name: start
in: query
description: The starting index of the returned records.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: |-
The maximum number of records to return per page.
Note, this may be restricted by fixed system limits.
schema:
minimum: 0
type: integer
format: int32
default: 1000
responses:
'200':
description: Returned if the requested records are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/AuditRecordArray'
'403':
description: >-
Returned if the calling user does not have permission to view the
audit
log.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- read:audit-log:confluence
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:audit-log:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: INACCESSIBLE
components:
schemas:
RetentionPeriod:
required:
- number
- units
type: object
properties:
number:
type: integer
description: The number of units for the retention period.
format: int32
units:
type: string
description: The unit of time that the retention period is measured in.
enum:
- NANOS
- MICROS
- MILLIS
- SECONDS
- MINUTES
- HOURS
- HALF_DAYS
- DAYS
- WEEKS
- MONTHS
- YEARS
- DECADES
- CENTURIES
- MILLENNIA
- ERAS
- FOREVER
AuditRecordArray:
required:
- _links
- limit
- results
- size
- start
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/AuditRecord'
start:
type: integer
format: int32
limit:
type: integer
format: int32
size:
type: integer
format: int32
_links:
$ref: '#/components/schemas/GenericLinks'
x-atlassian-narrative:
documents:
- title: About
anchor: about
body: >-
This is the reference for the Confluence Cloud REST API. This API is the
primary way to get and
modify data in Confluence Cloud, whether you are developing an app or
any other integration.
Use it to interact with Confluence entities, like pages and blog posts,
spaces, users, groups,
and more.
- title: Authentication and authorization
anchor: auth
body: >-
**Authentication:** If you are building a Cloud app, authentication is
implemented via JWT or OAuth 2.0, depending on what you are building
(see [Security
overview](https://developer.atlassian.com/cloud/confluence/security-overview/)).
Otherwise, if you are authenticating directly against the REST API, the
REST API supports basic auth (see [Basic auth for REST
APIs](https://developer.atlassian.com/cloud/confluence/basic-auth-for-rest-apis/)).
**Authorization:** If you are building a Cloud app, authorization can be
implemented by
[scopes](https://developer.atlassian.com/cloud/confluence/scopes/) or by
[OAuth 2.0 user
impersonation](https://developer.atlassian.com/cloud/confluence/oauth-2-jwt-bearer-tokens-for-apps).
Otherwise, if you are making calls directly against the REST API,
authorization is based on the user used in the authentication process.
See [Security
overview](https://developer.atlassian.com/cloud/confluence/security-overview/)
for more details on authentication and authorization.
- title: Status codes
anchor: status-code
body: >-
The Confluence REST API uses the [standard HTTP status
codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).
Responses that return an error status code will also return a response
body, similar to the following:
```json
{
"statusCode": 404,
"data": {
"authorized": false,
"valid": false,
"errors": [
{
"message": {
"translation": "This is an example error message.",
"args": []
}
}
],
"successful": false
},
"message": "This is an example error message."
}
```
- title: Using the REST API
anchor: using
body: >-
**Expansion:** The Confluence REST API uses resource expansion: some
parts of a resource are not returned unless explicitly specified. This
simplifies responses and minimizes network traffic.
To expand part of a resource in a request, use the `expand` query
parameter and specify the entities to be expanded. If you need to expand
nested entities, use the `.` dot notation. For example, the following
request will expand information about the requested content's space and
labels:
```
GET /wiki/rest/api/content/{id}?expand=space,metadata.labels
```
**Pagination:** The Confluence REST API uses pagination: a method that
returns a response with multiple objects can only return a limited
number at one time. This limits the size of responses and conserves
server resources.
Use the 'limit' and 'start' query parameters to specify pagination:
- `limit` is the number of objects to return per page. This may be
restricted by system limits.
- `start` is the index of the first item returned in the page of
results. The base index is 0.
For example, the following request will return ten content objects,
starting from the fifth object.
```
GET /wiki/rest/api/content?start=4&limit=10
```
**Special headers:**
- `X-Atlassian-Token: no-check` request header must be specified for
methods
that are protected from Cross Site Request Forgery (XSRF/CSRF) attacks.
This is
stated in the method description, if required. For more information, see
this
[KB
article](https://confluence.atlassian.com/cloudkb/xsrf-check-failed-when-calling-cloud-apis-826874382.html).
- title: Capabilities
anchor: capabilities
body: >-
**Webhooks:** A webhook is a user-defined callback over HTTP. You can
use Confluence webhooks to notify your app or web application when
certain events occur in Confluence. For example, when a page is created
or updated. To learn more, see
[Webhooks](https://developer.atlassian.com/cloud/confluence/modules/webhook/).
**Content properties:** Content properties are a key-value storage
associated with a piece of Confluence content. If you are building an
app, this is one form of persistence that you can use. You can use the
Confluence REST API to get, update, and delete content properties. To
learn more, see [Content properties in the REST
API](https://developer.atlassian.com/cloud/confluence/content-properties/).
**CQL:** The Confluence Query Language (CQL) allows you to perform
complex searches for content using an SQL-like syntax in the `search`
resource. To learn more, see [Advanced searching using
CQL](https://developer.atlassian.com/cloud/confluence/advanced-searching-using-cql/).