Atlassian Confluence Analytics API
The Atlassian Confluence Analytics API provides tools to collect, analyze, and visualize user engagement and content performance within Confluence.
OpenAPI Specification
openapi: 3.0.1
info:
title: 'Atlassian wiki/rest/api/analytics/'
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: Analytics
paths:
/wiki/rest/api/analytics/content/{contentId}/views:
get:
tags:
- Analytics
summary: Atlassian Get Views
description: Get the total number of views a piece of content has.
operationId: atlassianGetviews
parameters:
- name: contentId
in: path
description: The ID of the content to get the views for.
required: true
schema:
type: string
- name: fromDate
in: query
description: The number of views for the content since the date.
schema:
type: string
example: '2021-03-21T00:00:00.000Z'
responses:
'200':
description: Returns the total number of views for the content.
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: The content ID.
count:
type: integer
description: The total number of views for the content.
'400':
description: Returned if client input is invalid.
'401':
description: Returned if the authentication credentials are incorrect.
content: {}
'403':
description: |-
Returned if the authentication credentials are missing
from the request.
content: {}
'404':
description: |-
Returned if;
- There is no content with the given ID.
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-content.summary
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-content.summary
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:analytics.content:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
/wiki/rest/api/analytics/content/{contentId}/viewers:
get:
tags:
- Analytics
summary: Atlassian Get Viewers
description: Get the total number of distinct viewers a piece of content has.
operationId: atlassianGetviewers
parameters:
- name: contentId
in: path
description: The ID of the content to get the viewers for.
required: true
schema:
type: string
- name: fromDate
in: query
description: The number of views for the content since the date.
schema:
type: string
example: '2021-03-21T00:00:00.000Z'
responses:
'200':
description: Returns the total number of distinct viewers for the content.
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: The content ID.
count:
type: integer
description: The total number of distinct viewers for the content.
'400':
description: Returned if client input is invalid.
'401':
description: Returned if the authentication credentials are incorrect.
content: {}
'403':
description: |-
Returned if the authentication credentials are missing
from the request.
content: {}
'404':
description: |-
Returned if;
- There is no content with the given ID.
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-content.summary
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-content.summary
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:analytics.content:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
components:
schemas: {}
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/).