API docs by Redocly

AEM Admin API (12.70.10)

Download OpenAPI specification:

License: Apache 2.0

AEM Admin API is used to manage the lifecycle of content and code.

status

Status operations

General status

Returns the overall status of the respective resource. (If the ?edit=auto query param is set, this requires a call to your content source see https://www.aem.live/docs/limits#rate-limits-number-of-preview-operations-per-time)

Authorizations:
NoneAuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

path
required
string

Relative path of the resource

query Parameters
string or string

Optional URL of the edit (authoring) document

Responses

Response samples

Content type
application/json

Success response of a preview document.

{}

Start a bulk status job

Fetches the status of all resources specified in the paths property in the payload. If a path ends with /*, it is assumed to be a folder and is recursively processed.

The response will contain the folliowing information about a resource: path, sourceLastModified, previewLastModified and publishLastModified. It is possible to filter the information returned, by passing a combination of edit, preview and live in the select property in the payload.

Note that the bulk status is performed asynchronously and the response will contain information about the created job.

Authorizations:
NoneAuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

Request Body schema: application/json
paths
required
Array of strings

paths to filter the bulk status

forceAsync
boolean

forces the job to be executed asynchronous, even for a small number of given paths.

select
Array of strings
Items Enum: "edit" "preview" "live"

a combination of edit, preview and live. The default is ['preview','live'].

pathsOnly
boolean
Default: false

only return paths

Responses

Request samples

Content type
application/json
{
  • "select": [
    ],
  • "paths": [
    ]
}

Response samples

Content type
application/json

Success response.

{}

publish

Publish operations

Publish Status

Returns the publish status of the respective resource.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

path
required
string

Relative path of the resource

Responses

Response samples

Content type
application/json

Success response of a published document.

{}

Publish a resource

Publish a resource by copying the resource content from the preview content-bus partition to the live content-bus partition. It additionally purges the live cdn and the byo cdn, if configured.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

path
required
string

Relative path of the resource

query Parameters
forceUpdateRedirects
boolean

forces an update of the redirects (only applies when updating/publishing redirects.json)

disableNotifications
boolean

disables notifications for affected resources

Responses

Response samples

Content type
application/json

Success response of the published document.

{}

Un-publish a resource

Un-publish a resource by deleting the content from from the live content-bus partition. It additionally purges the live cdn and the byo cdn, if configured.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

path
required
string

Relative path of the resource

query Parameters
disableNotifications
boolean

disables notifications for affected resources

Responses

Start a bulk publish job

Updates live resources specified in the paths property in the payload.
By default, only new and modified resources are updated, unless the forceUpdate property is set to true.
Note that configuration files, like /.helix/config or redirects.json, are always ignored during bulk publish.
Note that the bulk publish is performed asynchronously and this request will return information to the created job.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

Request Body schema: application/json
forceUpdate
boolean

forces an update of the resources during bulk-publish

forceAsync
boolean

forces the job to be executed asynchronous, even for a small number of given paths.

paths
required
Array of strings

paths to filter the bulk publish

delete
boolean
Default: false

delete the resources from publish

Responses

Request samples

Content type
application/json
{
  • "forceUpdate": true,
  • "paths": [
    ],
  • "delete": false
}

Response samples

Content type
application/json

Success response.

{}

preview

Preview operations

Preview status

Returns the preview status of the respective resource.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

path
required
string

Relative path of the resource

Responses

Response samples

Content type
application/json

Success response of a preview document.

{}

Update preview

Updates the preview resource by fetching the latest content from the content providers (e.g. sharepoint, google docs, BYOM) and storing it in preview.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

path
required
string

Relative path of the resource

query Parameters
forceUpdateRedirects
boolean

forces an update of the redirects (only applies when updating/publishing redirects.json)

hlx-word2md-version
string

selects the version to use when invoking the word2md service.

hlx-gdocs2md-version
string

selects the version to use when invoking the gdocs2md service.

hlx-html2md-version
string

selects the version to use when invoking the html2md service.

Responses

Response samples

Content type
application/json

Success response.

{}

Delete preview

Deletes a preview resource from the preview partition in the content-bus..

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

path
required
string

Relative path of the resource

Responses

Start a bulk preview job

Updates preview resources specified in the paths property in the payload. If a path ends with /*, it is assume to be folder and is recursively previewed.
By default, only new and modified resources are updated, unless the forceUpdate property is set to true.
Note that configuration files, like /.helix/config or redirects.json, are always ignored during bulk preview.
Note that the bulk preview is performed asynchronously and this request will return information to the created job.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

query Parameters
hlx-word2md-version
string

selects the version to use when invoking the word2md service.

hlx-gdocs2md-version
string

selects the version to use when invoking the gdocs2md service.

hlx-html2md-version
string

selects the version to use when invoking the html2md service.

Request Body schema: application/json
forceUpdate
boolean

forces an update of the resources during bulk-preview

forceAsync
boolean

forces the job to be executed asynchronous, even for a small number of given paths.

paths
required
Array of strings

paths to filter the bulk preview

delete
boolean
Default: false

delete the resources from preview

Responses

Request samples

Content type
application/json
{
  • "forceUpdate": true,
  • "paths": [
    ],
  • "delete": false
}

Response samples

Content type
application/json

Success response.

{}

code

Code bus operations

Code bus status

Returns the code bus status of the respective resource.

Authorizations:
NoneAuthCookie
path Parameters
owner
required
string

Repository owner.

repo
required
string

Name of the repository

ref
required
string

Ref (branch) of repository.

path
required
string

Relative path of the resource

query Parameters
string or string

Optional branch specifier in case the branch name contains slashes or uppercase characters.

Responses

Response samples

Content type
application/json

Success response of a code document.

{}

Update code

Updates the code-bus resource by fetching the latest content from github and storing it in the code-bus. If the last path segment is a *, it will recursively update the code-bus with the respective github tree (directory). It additionally purges the live cdn and the byo cdn, if configured.

Authorizations:
NoneAuthCookie
path Parameters
owner
required
string

Repository owner.

repo
required
string

Name of the repository

ref
required
string

Ref (branch) of repository.

path
required
string

Relative path of the resource

query Parameters
string or string

Optional branch specifier in case the branch name contains slashes or uppercase characters.

Responses

Response samples

Content type
application/json

Success response.

[]

Delete code

Deletes a code resource from the code-bus It additionally purges the live cdn and the byo cdn, if configured.

Authorizations:
AuthCookie
path Parameters
owner
required
string

Repository owner.

repo
required
string

Name of the repository

ref
required
string

Ref (branch) of repository.

path
required
string

Relative path of the resource

query Parameters
string or string

Optional branch specifier in case the branch name contains slashes or uppercase characters.

Responses

Batch update code

Processes a change event and updates the code-bus accordingly. It additionally purges the live cdn and the byo cdn, if configured.

Authorizations:
NoneAuthCookie
path Parameters
owner
required
string

Repository owner.

repo
required
string

Name of the repository

ref
required
string

Ref (branch) of repository.

Request Body schema: application/json
source
string

event source, eg: 'github'

baseRef
string

base ref for branch operations

required
Array of objects (changeEntry)

array of changes

Array
type
required
string
Enum: "added" "deleted" "modified"

change type

path
required
string

Relative path of changed resource or * if this as a branch event.

time
string <date-time>

timestamp of change

commit
string

commit sha of change

contentType
string

the content type of the changed resource

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "type": "github",
  • "baseRef": "",
  • "installationId": 995843,
  • "changes": [
    ]
}

Response samples

Content type
application/json

Success response.

[]

cache

Cache operations

Purge live cache

Purges the resource from the respective live cdn. It optionally invokes the byo cdn purging hook, if configured.

Authorizations:
NoneAuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

path
required
string

Relative path of the resource

Responses

index

Index operations

Index Status

Returns the index status of the respective resource.

Authorizations:
NoneAuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

path
required
string

Relative path of the resource

Responses

Response samples

Content type
application/json

Success response of an index document.

{}

Re-index a resource.

Index a resource. If the last path segment is a *, it will recursively reindex all published resources below that sub tree.

Authorizations:
NoneAuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

path
required
string

Relative path of the resource

Responses

Response samples

Content type
application/json

Success response of indexing a resource.

{}

Remove a resource from the index.

Removes a resource from the index.

Authorizations:
NoneAuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

path
required
string

Relative path of the resource

Responses

Response samples

Content type
application/json

Success response of removing a resource from the index.

{
  • "webPath": "/en/2021/blog",
  • "resourcePath": "/en/2021/blog.md",
  • "index": {
    }
}

sitemap

Sitemap operations

Generates a sitemap

Generates a sitemap. The path specified should be the destination path of a sitemap.

Authorizations:
None
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

path
required
string

Relative path of the resource

Responses

Response samples

Content type
application/json

Success response of generating a sitemap

{
  • "paths": [
    ]
}

snapshot

Snapshot operations

List snapshots

Returns a list of snapshot IDs

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Responses

Response samples

Content type
application/json

Success response of list snapshots.

{}

Snapshot Manifest

Returns the snapshot manifest

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

snapshotId
required
string

Id of the snapshot

Responses

Response samples

Content type
application/json

Success response of a snapshot manifest.

{
  • "manifest": {
    },
  • "links": {}
}

Update snapshot Manifest

Updates the Snapshot manifest and allows to lock or unlock the snapshot. Note that in order to lock the snapshot, the request role also needs to include the preview:write permission, and in order to unlock the snapshot, the live:write permission is needed.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

snapshotId
required
string

Id of the snapshot

Request Body schema: application/json
locked
boolean
title
string
description
string
object
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "locked": true,
  • "title": "string",
  • "description": "string",
  • "metadata": { }
}

Response samples

Content type
application/json

Success response of a snapshot manifest.

{
  • "manifest": {
    },
  • "links": {}
}

Snapshot status

Returns the snapshot status of the respective resource.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

snapshotId
required
string

Id of the snapshot

path
required
string

Relative path of the resource

Responses

Response samples

Content type
application/json

Success response of a snapshot document.

{}

Add resource to snapshot

Creates a snapshot of the specified resource and stores it in the preview partition below the .snapshot/snapshotId folder. If the path param ends with a *, a snapshot of the entire subtree is created. If the snapshot is locked, a 409 response is returned.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

snapshotId
required
string

Id of the snapshot

path
required
string

Relative path of the resource

query Parameters
filter
any
Default: "all"
Enum: "all" "modified"

Filters the resources that are selected for snapshot. If set to modified only the resources that have a preview date newer than the live date are selected.

Responses

Delete snapshot

Deletes a snapshot resource from the preview partition in the content-bus. If the path param ends with a *, the entire subtree is deleted. If the snapshot is locked, a 409 response is returned.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

snapshotId
required
string

Id of the snapshot

path
required
string

Relative path of the resource

Responses

Start a bulk snapshot job

Add all resources specified in the paths property in the payload.
By default, only new and modified resources are updated, unless the forceUpdate property is set to true.
Note that the bulk snapshot is performed synchronously for arrays with fewer than 200 resources and no wildcard paths, and asynchronously otherwise.
Note that without the appropriate application/json content type header, the request will be treated as a wildcard add with no body, resulting in all resources being added to the snapshot.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

snapshotId
required
string

Id of the snapshot

Request Body schema: application/json
forceUpdate
boolean

forces an update of the resources during bulk snapshot

paths
required
Array of strings

paths of resources to include in the bulk snapshot

Responses

Request samples

Content type
application/json
Example
{
  • "forceUpdate": true,
  • "paths": [
    ]
}

Response samples

Content type
application/json
Example

Successful job completed synchronously response.

{
  • "status": 202,
  • "messageId": "37e92eec-020c-4eae-8f80-3db444c25056",
  • "job": {
    },
  • "links": {}
}

Publish snapshot resource

Publish snapshot resources by copying the resource content from the snapshot location to the live content-bus partition. It additionally purges the live cdn and the byo cdn, if configured. If the path param ends with a * the resources of the path's entire subtree is published.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

snapshotId
required
string

Id of the snapshot

path
required
string

Relative path of the resource

query Parameters
publish
any
Value: "true"

Indicates that the snapshot should be published.

Responses

Response samples

Content type
application/json

Success response of the published document.

{}

Publish snapshot

Publish a snapshot by copying all resources from the snapshot location to the live content-bus partition. It additionally purges the live cdn and the byo cdn, if configured.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

snapshotId
required
string

Id of the snapshot

query Parameters
publish
any
Value: "true"

Indicates that the snapshot should be published.

Responses

Response samples

Content type
application/json

Success response of the published document.

{}

Change snapshot review state

Performs a review operation on the snapshot. request locks the snapshot; approve publishes all resources, clears, and unlocks the snapshot; reject unlocks the snapshot. All operations can contain an optional message parameter which will be included in logs and events.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

snapshotId
required
string

Id of the snapshot

query Parameters
review
any
Enum: "request" "approve" "reject"

State to move the snapshot into.

message
string

Message of the review action, included in logs and events.

Responses

authentication

The API uses your existing Identity Provider (IDP) to authenticate users with administrative access. The general flow is that you open /login in a browser, select the IDP you want to use, and then are redirected to the IDP login page. After successful login, you are redirected back to the Admin API with an auth token in the response cookie (auth_token). This token is then used to authenticate all subsequent requests.

Alternatively, you can provide an authorization: token $API_KEY header. In order to obtain an API_KEY, talk to your AEM project lead.

Login Selection

Provides a selection of available IDP logins

Authorizations:
None

Responses

Response samples

Content type
application/json
Example

Success response.

{}

Auto login

Redirects to IDP corresponding the project setup

Authorizations:
None
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

Responses

Logout

Logs out the current session and redirects to the login screen

Authorizations:
None

Responses

Profile information

Display profile information

Authorizations:
NoneAuthCookie

Responses

Response samples

Content type
application/json

Success response.

{
  • "profile": {
    },
  • "links": {}
}

log

Log operations

Returns logs

Returns logs for a project. If there are more logs for the timespan specified, there will be a next link in the response to load the next batch.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

query Parameters
from
string

Indicates the starting date to get logs from. If not specified, uses the current date minus 15 minutes.

to
string

Indicates the ending date to get logs from. If not specified, uses the current date.

since
string
Example: since=5m

Indicates the time span to retrieve logs for, as a number and a unit in short notation (s, m, h or d). Not usable in combination with either from or to.

nextToken
string

Token returned from a previous call to continue

Responses

Response samples

Content type
application/json

Success response of a log request.

{
  • "from": "2023-11-07T14:00:00.000Z",
  • "to": "2023-11-07T16:15:12.454Z",
  • "entries": [
    ],
  • "nextToken": "ABAB==",
  • "links": {}
}

Add logs

Add logs to a project. The body should be in JSON format and contain an array called entries.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

Request Body schema: application/json
entries
required
Array of objects

entries to add to the logs

Responses

Request samples

Content type
application/json

This posts one entry to the audit log. To see what the added entry would look like, see the second entry in the getLog example.

{
  • "entries": [
    ]
}

job

Job operations

Job List

Returns the job list of jobs

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

topic
required
string

Topic of a job

Responses

Response samples

Content type
application/json

Success response of a job list.

{}

Job Status

Returns the job status

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

topic
required
string

Topic of a job

jobName
required
string

Name of a job

Responses

Response samples

Content type
application/json

Success response.

{}

Stop job

Stops a job.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

topic
required
string

Topic of a job

jobName
required
string

Name of a job

Responses

Job Status Details

Returns the job status

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

ref
required
string

Ref (branch) of repository.

topic
required
string

Topic of a job

jobName
required
string

Name of a job

Responses

Response samples

Content type
application/json

Success response.

{}

Org Config

Org Config operations

OrgConfig

version
required
integer
Default: 1
Value: 1
created
required
string <date-time> (created)

the date and time this configuration was created.

lastModified
required
string <date-time> (lastModified)

the date and time this configuration was modified last.

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

Array of objects (users)
Array
id
required
string^[a-zA-Z0-9-_=]+$
email
required
string <email>
name
string
roles
required
Array of strings
Items Enum: "admin" "author" "publish" "develop" "basic_author" "basic_publish" "config" "config_admin"
object (groups)
pattern property
object (Group)

A group of members. Can be referenced in access.admin.role.

required
Array of objects
object (secrets)

Defines organization level secrets.

pattern property
object or object
One of
hash
required
string^[a-zA-Z0-9-_=]+$
id
required
string^[a-zA-Z0-9-_=]+$
type
required
string
Enum: "hashed" "key"
created
required
string <date-time>
lastModified
required
string <date-time>
description
string
object (apikeys)

Stores information about generated admin API keys. The keys listed here have no operational meaning, but are used to track the keys that have been generated.

pattern property
object
id
required
string^[a-zA-Z0-9-_/+]+$

the API token id (jti)

created
required
string <date-time>
expiration
required
string <date-time>
roles
required
Array of strings
subject
required
string

the subject of the API token (sub)

description
string
object (tokens)
Deprecated

site tokens. deprecated: use the org secrets instead.

pattern property
object
id
string^[a-zA-Z0-9-_=]+$
hash
string^[a-zA-Z0-9-_=]+$
created
string <date-time>
object (org-access)
object
apiKeyId
Array of strings

the id of the API key(s) that are allowed to access this org (admin).

{
  • "version": 1,
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "title": "string",
  • "description": "string",
  • "users": [
    ],
  • "groups": { },
  • "secrets": { },
  • "apiKeys": { },
  • "tokens": { },
  • "access": {
    }
}

GroupsConfig

pattern property
object (Group)

A group of members. Can be referenced in access.admin.role.

required
Array of objects
Array
email
required
string <email>
name
string
{ }

SecretsConfig

pattern property
object or object
One of
hash
required
string^[a-zA-Z0-9-_=]+$
id
required
string^[a-zA-Z0-9-_=]+$
type
required
string
Enum: "hashed" "key"
created
required
string <date-time>
lastModified
required
string <date-time>
description
string
{ }

Read Organisation Config

Returns the organisation level configuration.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

Responses

Response samples

Content type
application/json
{
  • "version": 1,
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "title": "string",
  • "description": "string",
  • "users": [
    ],
  • "groups": { },
  • "secrets": { },
  • "apiKeys": { },
  • "tokens": { },
  • "access": {
    }
}

Update Organisation Config

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

Request Body schema: application/json
version
required
integer
Default: 1
Value: 1
created
required
string <date-time> (created)

the date and time this configuration was created.

lastModified
required
string <date-time> (lastModified)

the date and time this configuration was modified last.

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

Array of objects (users)
Array
id
required
string^[a-zA-Z0-9-_=]+$
email
required
string <email>
name
string
roles
required
Array of strings
Items Enum: "admin" "author" "publish" "develop" "basic_author" "basic_publish" "config" "config_admin"
object (groups)
pattern property
object (Group)

A group of members. Can be referenced in access.admin.role.

required
Array of objects
object (secrets)

Defines organization level secrets.

pattern property
object or object
One of
hash
required
string^[a-zA-Z0-9-_=]+$
id
required
string^[a-zA-Z0-9-_=]+$
type
required
string
Enum: "hashed" "key"
created
required
string <date-time>
lastModified
required
string <date-time>
description
string
object (apikeys)

Stores information about generated admin API keys. The keys listed here have no operational meaning, but are used to track the keys that have been generated.

pattern property
object
id
required
string^[a-zA-Z0-9-_/+]+$

the API token id (jti)

created
required
string <date-time>
expiration
required
string <date-time>
roles
required
Array of strings
subject
required
string

the subject of the API token (sub)

description
string
object (tokens)
Deprecated

site tokens. deprecated: use the org secrets instead.

pattern property
object
id
string^[a-zA-Z0-9-_=]+$
hash
string^[a-zA-Z0-9-_=]+$
created
string <date-time>
object (org-access)
object
apiKeyId
Array of strings

the id of the API key(s) that are allowed to access this org (admin).

Responses

Request samples

Content type
application/json
{
  • "version": 1,
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "title": "string",
  • "description": "string",
  • "users": [
    ],
  • "groups": { },
  • "secrets": { },
  • "apiKeys": { },
  • "tokens": { },
  • "access": {
    }
}

Response samples

Content type
application/json
{ }

Create Organisation Config

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

Request Body schema: application/json
version
required
integer
Default: 1
Value: 1
created
required
string <date-time> (created)

the date and time this configuration was created.

lastModified
required
string <date-time> (lastModified)

the date and time this configuration was modified last.

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

Array of objects (users)
Array
id
required
string^[a-zA-Z0-9-_=]+$
email
required
string <email>
name
string
roles
required
Array of strings
Items Enum: "admin" "author" "publish" "develop" "basic_author" "basic_publish" "config" "config_admin"
object (groups)
pattern property
object (Group)

A group of members. Can be referenced in access.admin.role.

required
Array of objects
object (secrets)

Defines organization level secrets.

pattern property
object or object
One of
hash
required
string^[a-zA-Z0-9-_=]+$
id
required
string^[a-zA-Z0-9-_=]+$
type
required
string
Enum: "hashed" "key"
created
required
string <date-time>
lastModified
required
string <date-time>
description
string
object (apikeys)

Stores information about generated admin API keys. The keys listed here have no operational meaning, but are used to track the keys that have been generated.

pattern property
object
id
required
string^[a-zA-Z0-9-_/+]+$

the API token id (jti)

created
required
string <date-time>
expiration
required
string <date-time>
roles
required
Array of strings
subject
required
string

the subject of the API token (sub)

description
string
object (tokens)
Deprecated

site tokens. deprecated: use the org secrets instead.

pattern property
object
id
string^[a-zA-Z0-9-_=]+$
hash
string^[a-zA-Z0-9-_=]+$
created
string <date-time>
object (org-access)
object
apiKeyId
Array of strings

the id of the API key(s) that are allowed to access this org (admin).

Responses

Request samples

Content type
application/json
{
  • "version": 1,
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "title": "string",
  • "description": "string",
  • "users": [
    ],
  • "groups": { },
  • "secrets": { },
  • "apiKeys": { },
  • "tokens": { },
  • "access": {
    }
}

Delete Organisation Config

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

Responses

List Users

Returns the org users

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new org user

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

Request Body schema: application/json
One of
email
required
string

email of the user

roles
required
Array of strings
Items Enum: "admin" "author" "publish" "develop" "basic_author" "basic_publish" "config" "config_admin"

role of the user

Responses

Request samples

Content type
application/json
Example
{
  • "email": "string",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "email": "user@example.com",
  • "name": "string",
  • "roles": [
    ]
}

Read user

Returns the user

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

id
required
string

user id.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "email": "user@example.com",
  • "name": "string",
  • "roles": [
    ]
}

Delete user

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

id
required
string

user id.

Responses

List org secrets

Returns the org secrets

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

Responses

Response samples

Content type
application/json
{ }

Create new org secret

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

Request Body schema: application/json
One of
description
string

Responses

Request samples

Content type
application/json
Example
{
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "description": "string",
  • "value": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z"
}

Read secret

Returns the secret

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

id
required
string

secret id.

Responses

Response samples

Content type
application/json
{ }

Delete org secret

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

id
required
string

secret id.

Responses

Read secret

Returns the secret

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

id
required
string

secret id.

Responses

Response samples

Content type
application/json
{ }

Site Config

Please note that most of the configuration objects that have an explicit schema can also be addressed directly, even if not listed in this documentation.
For example the production CDN configuration can be managed via the /config/{org}/sites/{site}/cdn/prod.json endpoint.

SiteConfig

version
required
integer
Default: 1
Value: 1
name
string^[a-z0-9]+(?:-[a-z0-9]+)*$

Site name; part of the hostname

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

created
required
string <date-time> (created)

the date and time this configuration was created.

lastModified
required
string <date-time> (lastModified)

the date and time this configuration was modified last.

required
object (content)

Defines the content bus location and source.

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

contentBusId
required
string
required
Google Content Source (object) or Onedrive Content Source (object) or Markup Content Source (object)
One of
type
required
any
Value: "google"
url
required
string <uri>
id
required
string

Google drive ID of the root folder; updated automatically when updating the url.

Markup Content Source (object)

Overlay from a BYOM source. Previewing resources will try the overlay source first. Please note, that the overlay config is tied to the base content and not to the site config. I.e. it's not possible to have multiple sites with different overlays on the same base content.

One of
type
required
any
Value: "markup"
url
required
string <uri>
suffix
string
required
object (code)

Defines the code bus location and source.

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

owner
required
string^[a-zA-Z0-9_-]+$
repo
required
string^[a-zA-Z0-9_-]+$
required
object
type
required
any
Value: "github"
url
required
string <uri>
raw_url
string <uri>
secretId
string^[a-zA-Z0-9-_=]+$
owner
string^[a-zA-Z0-9_-]+$
repo
string^[a-zA-Z0-9_-]+$
object (folders)
^/[a-zA-Z0-9-_/.]*$
pattern property
string
object (headers)
pattern property
Array of objects (keyValuePair)
Array
key
required
string
value
required
string
object (cdn)
Fastly CDN Config (object) or Cloudflare CDN Config (object) or Akamai CDN Config (object) or Managed CDN Config (object) or Cloudfront CDN Config (object) or EmptyConfig (object)
One of
type
required
string
Value: "fastly"
host
required
string

production host

route
Array of strings

Routes on the CDN that are rendered with Franklin

serviceId
required
string

The Fastly Service ID

authToken
required
string

A Fastly token for purging

object
host
required
string

Sidekick config to override the default previewHost. it supports parameters $owner and $repo

object
host
required
string

Sidekick config to override the default liveHost. it supports parameters $owner and $repo

object
host
required
string

Sidekick config to override the default reviewHost. it supports parameters $owner and $repo

object (access)
object (access-admin)
object (Role)
boolean or string
Default: "auto"

Enforce authentication if set to true. If set to 'auto' it will enforce authentication if a role mapping is defined. defaults to 'auto'.

defaultRole
Array of strings
Items Enum: "admin" "author" "publish" "develop" "basic_author" "basic_publish" "config" "config_admin"

the default roles assigned to the users. defaults to basic_publish for unauthenticated setups.

apiKeyId
Array of strings

the id of the API key(s). this is used to validate the API KEYS and allows to invalidate them.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (tokens)
Deprecated

site tokens. deprecated: use the org secrets instead.

pattern property
object
id
string^[a-zA-Z0-9-_=]+$
hash
string^[a-zA-Z0-9-_=]+$
created
string <date-time>
object (secrets)

Defines organization level secrets.

pattern property
object or object
One of
hash
required
string^[a-zA-Z0-9-_=]+$
id
required
string^[a-zA-Z0-9-_=]+$
type
required
string
Enum: "hashed" "key"
created
required
string <date-time>
lastModified
required
string <date-time>
description
string
object (apikeys)

Stores information about generated admin API keys. The keys listed here have no operational meaning, but are used to track the keys that have been generated.

pattern property
object
id
required
string^[a-zA-Z0-9-_/+]+$

the API token id (jti)

created
required
string <date-time>
expiration
required
string <date-time>
roles
required
Array of strings
subject
required
string

the subject of the API token (sub)

description
string
object (groups)
pattern property
object (Group)

A group of members. Can be referenced in access.admin.role.

required
Array of objects
object (sidekick)
editUrlLabel
string

The label of the custom editing environment.

editUrlPattern
string

The URL pattern for the custom editing environment. Supports placeholders like {{contentSourceUrl}} or {{pathname}}.

host
string <hostname>

The host name of the production website (overrides cdn.prod.host)

liveHost
string <hostname>

The host name of the live environment (overrides cdn.live.host, defaults to *.aem.live)

Array of objects (sidekickPlugin)
Array
badgeVariant
string
Enum: "gray" "red" "orange" "yellow" "chartreuse" "celery" "green" "seafoam" "cyan" "blue" "indigo" "purple" "fuchsia" "magenta"

The variant of the badge following the Adobe Spectrum badge variants

containerId
string

The ID of the container to add this plugin to

environments
Array of strings
Default: "any"
Items Enum: "any" "dev" "admin" "edit" "preview" "review" "live" "prod"

The environments to display this plugin in

event
string

The name of a custom event to fire when the button is clicked (defaults to id)

excludePaths
Array of strings

Excludes the plugin from these paths

id
required
string

The unique plugin ID

includePaths
Array of strings

Includes the plugin on these paths (overrides excludePaths)

isBadge
boolean

Renders the plugin as a badge

isContainer
boolean

Renders the plugin as a container for other plugins

isPalette
boolean

Opens the URL in a palette instead of a new tab

isPopover
boolean

Opens the URL in a popover instead of a new tab

paletteRect
string

The dimensions and position of the palette (top, left, bottom, right, width, height)

passConfig
boolean

Append ref, repo, owner, host, and project as query params to the URL

passReferrer
boolean

Append the referrer URL as a query param to the URL

pinned
boolean

Renders the plugin in the bar (true, default) or the menu (false)

popoverRect
string

The dimensions of the popover (width, height)

title
string

The button text

object non-empty

The button text in other supported languages

url
string

The URL to open when the button is clicked

previewHost
string <hostname>

The host name of the preview environment (overrides cdn.preview.host, defaults to *.aem.page)

project
string

The name of the project to display in the sidekick

reviewHost
string <hostname>

The host name of the review environment (overrides cdn.review.host, defaults to *.aem.reviews)

Array of objects (sidekickSpecialView)
Array
id
required
string

The unique view ID

path
required
string

Open the special view on this path

viewer
required
string

The URL of the special view. The resource path will be passed to it via 'path' parameter

object (metadata-source)
source
Array of strings
object (robots)
txt
string
public
object (public)

Public configuration

object (events)
required
object
target
required
string^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$
object (features)

Features configuration

pattern property
object
property name*
additional property
any
object (limits)

Features configuration

pattern property
object
description
string
property name*
additional property
any
object
profile
string^[0-9a-zA-Z-_]+$
{
  • "version": 1,
  • "name": "string",
  • "title": "string",
  • "description": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "content": {
    },
  • "code": {
    },
  • "folders": { },
  • "headers": { },
  • "cdn": {
    },
  • "access": {
    },
  • "tokens": { },
  • "secrets": { },
  • "apiKeys": { },
  • "groups": { },
  • "sidekick": {
    },
  • "metadata": {
    },
  • "robots": {
    },
  • "public": { },
  • "events": {
    },
  • "features": { },
  • "limits": { },
  • "extends": {
    }
}

SiteConfigList

required
Array of objects
Array
name
required
string
{
  • "sites": [
    ]
}

AdminAccessConfig

object (Role)
^[a-z-_]+$
pattern property
Array of strings

The email glob of the users or a group reference for the respective role.

boolean or string
Default: "auto"

Enforce authentication if set to true. If set to 'auto' it will enforce authentication if a role mapping is defined. defaults to 'auto'.

One of
boolean
Default: "auto"

Enforce authentication if set to true. If set to 'auto' it will enforce authentication if a role mapping is defined. defaults to 'auto'.

defaultRole
Array of strings
Items Enum: "admin" "author" "publish" "develop" "basic_author" "basic_publish" "config" "config_admin"

the default roles assigned to the users. defaults to basic_publish for unauthenticated setups.

apiKeyId
Array of strings

the id of the API key(s). this is used to validate the API KEYS and allows to invalidate them.

{
  • "role": { },
  • "requireAuth": "auto",
  • "defaultRole": [
    ],
  • "apiKeyId": [
    ]
}

SiteAccessConfig

allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

{
  • "allow": [
    ],
  • "secretId": [
    ],
  • "apiKeyId": [
    ]
}

AccessConfig

object (access-admin)
object (Role)
^[a-z-_]+$
pattern property
Array of strings

The email glob of the users or a group reference for the respective role.

boolean or string
Default: "auto"

Enforce authentication if set to true. If set to 'auto' it will enforce authentication if a role mapping is defined. defaults to 'auto'.

One of
boolean
Default: "auto"

Enforce authentication if set to true. If set to 'auto' it will enforce authentication if a role mapping is defined. defaults to 'auto'.

defaultRole
Array of strings
Items Enum: "admin" "author" "publish" "develop" "basic_author" "basic_publish" "config" "config_admin"

the default roles assigned to the users. defaults to basic_publish for unauthenticated setups.

apiKeyId
Array of strings

the id of the API key(s). this is used to validate the API KEYS and allows to invalidate them.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

{
  • "admin": {
    },
  • "site": {
    },
  • "preview": {
    },
  • "live": {
    }
}

CDNConfig

Fastly CDN Config (object) or Cloudflare CDN Config (object) or Akamai CDN Config (object) or Managed CDN Config (object) or Cloudfront CDN Config (object) or EmptyConfig (object)
One of
type
required
string
Value: "fastly"
host
required
string

production host

route
Array of strings

Routes on the CDN that are rendered with Franklin

serviceId
required
string

The Fastly Service ID

authToken
required
string

A Fastly token for purging

object
host
required
string

Sidekick config to override the default previewHost. it supports parameters $owner and $repo

object
host
required
string

Sidekick config to override the default liveHost. it supports parameters $owner and $repo

object
host
required
string

Sidekick config to override the default reviewHost. it supports parameters $owner and $repo

{
  • "prod": {
    },
  • "live": {
    },
  • "preview": {
    },
  • "review": {
    }
}

CodeConfig

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

owner
required
string^[a-zA-Z0-9_-]+$
repo
required
string^[a-zA-Z0-9_-]+$
required
object
type
required
any
Value: "github"
url
required
string <uri>
raw_url
string <uri>
secretId
string^[a-zA-Z0-9-_=]+$
owner
string^[a-zA-Z0-9_-]+$
repo
string^[a-zA-Z0-9_-]+$
{
  • "title": "string",
  • "description": "string",
  • "owner": "string",
  • "repo": "string",
  • "source": {}
}

ContentConfig

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

contentBusId
required
string
required
Google Content Source (object) or Onedrive Content Source (object) or Markup Content Source (object)
One of
type
required
any
Value: "google"
url
required
string <uri>
id
required
string

Google drive ID of the root folder; updated automatically when updating the url.

Markup Content Source (object)

Overlay from a BYOM source. Previewing resources will try the overlay source first. Please note, that the overlay config is tied to the base content and not to the site config. I.e. it's not possible to have multiple sites with different overlays on the same base content.

One of
type
required
any
Value: "markup"
url
required
string <uri>
suffix
string
{
  • "title": "string",
  • "description": "string",
  • "contentBusId": "string",
  • "source": {},
  • "overlay": {}
}

FoldersConfig

^/[a-zA-Z0-9-_/.]*$
pattern property
string
{ }

HeadersConfig

pattern property
Array of objects (keyValuePair)
Array
key
required
string
value
required
string
{ }

MetadataConfig

source
Array of strings
{
  • "source": [
    ]
}

PublicConfig

object (PublicConfig)

Public configuration

{ }

GroupsConfig

pattern property
object (Group)

A group of members. Can be referenced in access.admin.role.

required
Array of objects
Array
email
required
string <email>
name
string
{ }

RobotsConfig

txt
string
{
  • "txt": "string"
}

SidekickConfig

editUrlLabel
string

The label of the custom editing environment.

editUrlPattern
string

The URL pattern for the custom editing environment. Supports placeholders like {{contentSourceUrl}} or {{pathname}}.

host
string <hostname>

The host name of the production website (overrides cdn.prod.host)

liveHost
string <hostname>

The host name of the live environment (overrides cdn.live.host, defaults to *.aem.live)

Array of objects (sidekickPlugin)
Array
badgeVariant
string
Enum: "gray" "red" "orange" "yellow" "chartreuse" "celery" "green" "seafoam" "cyan" "blue" "indigo" "purple" "fuchsia" "magenta"

The variant of the badge following the Adobe Spectrum badge variants

containerId
string

The ID of the container to add this plugin to

environments
Array of strings
Default: "any"
Items Enum: "any" "dev" "admin" "edit" "preview" "review" "live" "prod"

The environments to display this plugin in

event
string

The name of a custom event to fire when the button is clicked (defaults to id)

excludePaths
Array of strings

Excludes the plugin from these paths

id
required
string

The unique plugin ID

includePaths
Array of strings

Includes the plugin on these paths (overrides excludePaths)

isBadge
boolean

Renders the plugin as a badge

isContainer
boolean

Renders the plugin as a container for other plugins

isPalette
boolean

Opens the URL in a palette instead of a new tab

isPopover
boolean

Opens the URL in a popover instead of a new tab

paletteRect
string

The dimensions and position of the palette (top, left, bottom, right, width, height)

passConfig
boolean

Append ref, repo, owner, host, and project as query params to the URL

passReferrer
boolean

Append the referrer URL as a query param to the URL

pinned
boolean

Renders the plugin in the bar (true, default) or the menu (false)

popoverRect
string

The dimensions of the popover (width, height)

title
string

The button text

object non-empty

The button text in other supported languages

url
string

The URL to open when the button is clicked

previewHost
string <hostname>

The host name of the preview environment (overrides cdn.preview.host, defaults to *.aem.page)

project
string

The name of the project to display in the sidekick

reviewHost
string <hostname>

The host name of the review environment (overrides cdn.review.host, defaults to *.aem.reviews)

Array of objects (sidekickSpecialView)
Array
id
required
string

The unique view ID

path
required
string

Open the special view on this path

viewer
required
string

The URL of the special view. The resource path will be passed to it via 'path' parameter

{
  • "editUrlLabel": "string",
  • "editUrlPattern": "string",
  • "host": "example.com",
  • "liveHost": "example.com",
  • "plugins": [
    ],
  • "previewHost": "example.com",
  • "project": "string",
  • "reviewHost": "example.com",
  • "specialViews": [
    ]
}

TokensConfig

pattern property
object
id
string^[a-zA-Z0-9-_=]+$
hash
string^[a-zA-Z0-9-_=]+$
created
string <date-time>
{ }

SecretsConfig

pattern property
object or object
One of
hash
required
string^[a-zA-Z0-9-_=]+$
id
required
string^[a-zA-Z0-9-_=]+$
type
required
string
Enum: "hashed" "key"
created
required
string <date-time>
lastModified
required
string <date-time>
description
string
{ }

List Site Config

Returns the site level configuration names.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

Responses

Response samples

Content type
application/json
{
  • "sites": [
    ]
}

Read Site Config

Returns the site level configuration. If migrate is set to true, the configuration will be aggregated based on the legacy config (fstab, .helix/config.xlsx, etc).

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

query Parameters
migrate
boolean

indicates to migrate the config.

validate
boolean

indicates to validate the config to be migrated. only effective when migrate is set to true.

Responses

Response samples

Content type
application/json
{
  • "version": 1,
  • "name": "string",
  • "title": "string",
  • "description": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "content": {
    },
  • "code": {
    },
  • "folders": { },
  • "headers": { },
  • "cdn": {
    },
  • "access": {
    },
  • "tokens": { },
  • "secrets": { },
  • "apiKeys": { },
  • "groups": { },
  • "sidekick": {
    },
  • "metadata": {
    },
  • "robots": {
    },
  • "public": { },
  • "events": {
    },
  • "features": { },
  • "limits": { },
  • "extends": {
    }
}

Update Site Config.

Stores new site configuration. If migrate is set to true, the configuration will be aggregated based on the legacy config (fstab, .helix/config.xlsx, etc) and will overwrite the existing configuration.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

query Parameters
migrate
boolean

indicates to migrate the config.

validate
boolean

indicates to validate the config to be migrated. only effective when migrate is set to true.

Request Body schema: application/json
version
required
integer
Default: 1
Value: 1
name
string^[a-z0-9]+(?:-[a-z0-9]+)*$

Site name; part of the hostname

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

created
required
string <date-time> (created)

the date and time this configuration was created.

lastModified
required
string <date-time> (lastModified)

the date and time this configuration was modified last.

required
object (content)

Defines the content bus location and source.

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

contentBusId
required
string
required
Google Content Source (object) or Onedrive Content Source (object) or Markup Content Source (object)
One of
type
required
any
Value: "google"
url
required
string <uri>
id
required
string

Google drive ID of the root folder; updated automatically when updating the url.

Markup Content Source (object)

Overlay from a BYOM source. Previewing resources will try the overlay source first. Please note, that the overlay config is tied to the base content and not to the site config. I.e. it's not possible to have multiple sites with different overlays on the same base content.

One of
type
required
any
Value: "markup"
url
required
string <uri>
suffix
string
required
object (code)

Defines the code bus location and source.

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

owner
required
string^[a-zA-Z0-9_-]+$
repo
required
string^[a-zA-Z0-9_-]+$
required
object
type
required
any
Value: "github"
url
required
string <uri>
raw_url
string <uri>
secretId
string^[a-zA-Z0-9-_=]+$
owner
string^[a-zA-Z0-9_-]+$
repo
string^[a-zA-Z0-9_-]+$
object (folders)
^/[a-zA-Z0-9-_/.]*$
pattern property
string
object (headers)
pattern property
Array of objects (keyValuePair)
Array
key
required
string
value
required
string
object (cdn)
Fastly CDN Config (object) or Cloudflare CDN Config (object) or Akamai CDN Config (object) or Managed CDN Config (object) or Cloudfront CDN Config (object) or EmptyConfig (object)
One of
type
required
string
Value: "fastly"
host
required
string

production host

route
Array of strings

Routes on the CDN that are rendered with Franklin

serviceId
required
string

The Fastly Service ID

authToken
required
string

A Fastly token for purging

object
host
required
string

Sidekick config to override the default previewHost. it supports parameters $owner and $repo

object
host
required
string

Sidekick config to override the default liveHost. it supports parameters $owner and $repo

object
host
required
string

Sidekick config to override the default reviewHost. it supports parameters $owner and $repo

object (access)
object (access-admin)
object (Role)
boolean or string
Default: "auto"

Enforce authentication if set to true. If set to 'auto' it will enforce authentication if a role mapping is defined. defaults to 'auto'.

defaultRole
Array of strings
Items Enum: "admin" "author" "publish" "develop" "basic_author" "basic_publish" "config" "config_admin"

the default roles assigned to the users. defaults to basic_publish for unauthenticated setups.

apiKeyId
Array of strings

the id of the API key(s). this is used to validate the API KEYS and allows to invalidate them.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (tokens)
Deprecated

site tokens. deprecated: use the org secrets instead.

pattern property
object
id
string^[a-zA-Z0-9-_=]+$
hash
string^[a-zA-Z0-9-_=]+$
created
string <date-time>
object (secrets)

Defines organization level secrets.

pattern property
object or object
One of
hash
required
string^[a-zA-Z0-9-_=]+$
id
required
string^[a-zA-Z0-9-_=]+$
type
required
string
Enum: "hashed" "key"
created
required
string <date-time>
lastModified
required
string <date-time>
description
string
object (apikeys)

Stores information about generated admin API keys. The keys listed here have no operational meaning, but are used to track the keys that have been generated.

pattern property
object
id
required
string^[a-zA-Z0-9-_/+]+$

the API token id (jti)

created
required
string <date-time>
expiration
required
string <date-time>
roles
required
Array of strings
subject
required
string

the subject of the API token (sub)

description
string
object (groups)
pattern property
object (Group)

A group of members. Can be referenced in access.admin.role.

required
Array of objects
object (sidekick)
editUrlLabel
string

The label of the custom editing environment.

editUrlPattern
string

The URL pattern for the custom editing environment. Supports placeholders like {{contentSourceUrl}} or {{pathname}}.

host
string <hostname>

The host name of the production website (overrides cdn.prod.host)

liveHost
string <hostname>

The host name of the live environment (overrides cdn.live.host, defaults to *.aem.live)

Array of objects (sidekickPlugin)
Array
badgeVariant
string
Enum: "gray" "red" "orange" "yellow" "chartreuse" "celery" "green" "seafoam" "cyan" "blue" "indigo" "purple" "fuchsia" "magenta"

The variant of the badge following the Adobe Spectrum badge variants

containerId
string

The ID of the container to add this plugin to

environments
Array of strings
Default: "any"
Items Enum: "any" "dev" "admin" "edit" "preview" "review" "live" "prod"

The environments to display this plugin in

event
string

The name of a custom event to fire when the button is clicked (defaults to id)

excludePaths
Array of strings

Excludes the plugin from these paths

id
required
string

The unique plugin ID

includePaths
Array of strings

Includes the plugin on these paths (overrides excludePaths)

isBadge
boolean

Renders the plugin as a badge

isContainer
boolean

Renders the plugin as a container for other plugins

isPalette
boolean

Opens the URL in a palette instead of a new tab

isPopover
boolean

Opens the URL in a popover instead of a new tab

paletteRect
string

The dimensions and position of the palette (top, left, bottom, right, width, height)

passConfig
boolean

Append ref, repo, owner, host, and project as query params to the URL

passReferrer
boolean

Append the referrer URL as a query param to the URL

pinned
boolean

Renders the plugin in the bar (true, default) or the menu (false)

popoverRect
string

The dimensions of the popover (width, height)

title
string

The button text

object non-empty

The button text in other supported languages

url
string

The URL to open when the button is clicked

previewHost
string <hostname>

The host name of the preview environment (overrides cdn.preview.host, defaults to *.aem.page)

project
string

The name of the project to display in the sidekick

reviewHost
string <hostname>

The host name of the review environment (overrides cdn.review.host, defaults to *.aem.reviews)

Array of objects (sidekickSpecialView)
Array
id
required
string

The unique view ID

path
required
string

Open the special view on this path

viewer
required
string

The URL of the special view. The resource path will be passed to it via 'path' parameter

object (metadata-source)
source
Array of strings
object (robots)
txt
string
public
object (public)

Public configuration

object (events)
required
object
target
required
string^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$
object (features)

Features configuration

pattern property
object
property name*
additional property
any
object (limits)

Features configuration

pattern property
object
description
string
property name*
additional property
any
object
profile
string^[0-9a-zA-Z-_]+$

Responses

Request samples

Content type
application/json
{
  • "version": 1,
  • "name": "string",
  • "title": "string",
  • "description": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "content": {
    },
  • "code": {
    },
  • "folders": { },
  • "headers": { },
  • "cdn": {
    },
  • "access": {
    },
  • "tokens": { },
  • "secrets": { },
  • "apiKeys": { },
  • "groups": { },
  • "sidekick": {
    },
  • "metadata": {
    },
  • "robots": {
    },
  • "public": { },
  • "events": {
    },
  • "features": { },
  • "limits": { },
  • "extends": {
    }
}

Response samples

Content type
application/json
{
  • "version": 1,
  • "name": "string",
  • "title": "string",
  • "description": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "content": {
    },
  • "code": {
    },
  • "folders": { },
  • "headers": { },
  • "cdn": {
    },
  • "access": {
    },
  • "tokens": { },
  • "secrets": { },
  • "apiKeys": { },
  • "groups": { },
  • "sidekick": {
    },
  • "metadata": {
    },
  • "robots": {
    },
  • "public": { },
  • "events": {
    },
  • "features": { },
  • "limits": { },
  • "extends": {
    }
}

Create Site Config

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Request Body schema: application/json
version
required
integer
Default: 1
Value: 1
name
string^[a-z0-9]+(?:-[a-z0-9]+)*$

Site name; part of the hostname

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

created
required
string <date-time> (created)

the date and time this configuration was created.

lastModified
required
string <date-time> (lastModified)

the date and time this configuration was modified last.

required
object (content)

Defines the content bus location and source.

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

contentBusId
required
string
required
Google Content Source (object) or Onedrive Content Source (object) or Markup Content Source (object)
One of
type
required
any
Value: "google"
url
required
string <uri>
id
required
string

Google drive ID of the root folder; updated automatically when updating the url.

Markup Content Source (object)

Overlay from a BYOM source. Previewing resources will try the overlay source first. Please note, that the overlay config is tied to the base content and not to the site config. I.e. it's not possible to have multiple sites with different overlays on the same base content.

One of
type
required
any
Value: "markup"
url
required
string <uri>
suffix
string
required
object (code)

Defines the code bus location and source.

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

owner
required
string^[a-zA-Z0-9_-]+$
repo
required
string^[a-zA-Z0-9_-]+$
required
object
type
required
any
Value: "github"
url
required
string <uri>
raw_url
string <uri>
secretId
string^[a-zA-Z0-9-_=]+$
owner
string^[a-zA-Z0-9_-]+$
repo
string^[a-zA-Z0-9_-]+$
object (folders)
^/[a-zA-Z0-9-_/.]*$
pattern property
string
object (headers)
pattern property
Array of objects (keyValuePair)
Array
key
required
string
value
required
string
object (cdn)
Fastly CDN Config (object) or Cloudflare CDN Config (object) or Akamai CDN Config (object) or Managed CDN Config (object) or Cloudfront CDN Config (object) or EmptyConfig (object)
One of
type
required
string
Value: "fastly"
host
required
string

production host

route
Array of strings

Routes on the CDN that are rendered with Franklin

serviceId
required
string

The Fastly Service ID

authToken
required
string

A Fastly token for purging

object
host
required
string

Sidekick config to override the default previewHost. it supports parameters $owner and $repo

object
host
required
string

Sidekick config to override the default liveHost. it supports parameters $owner and $repo

object
host
required
string

Sidekick config to override the default reviewHost. it supports parameters $owner and $repo

object (access)
object (access-admin)
object (Role)
boolean or string
Default: "auto"

Enforce authentication if set to true. If set to 'auto' it will enforce authentication if a role mapping is defined. defaults to 'auto'.

defaultRole
Array of strings
Items Enum: "admin" "author" "publish" "develop" "basic_author" "basic_publish" "config" "config_admin"

the default roles assigned to the users. defaults to basic_publish for unauthenticated setups.

apiKeyId
Array of strings

the id of the API key(s). this is used to validate the API KEYS and allows to invalidate them.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (tokens)
Deprecated

site tokens. deprecated: use the org secrets instead.

pattern property
object
id
string^[a-zA-Z0-9-_=]+$
hash
string^[a-zA-Z0-9-_=]+$
created
string <date-time>
object (secrets)

Defines organization level secrets.

pattern property
object or object
One of
hash
required
string^[a-zA-Z0-9-_=]+$
id
required
string^[a-zA-Z0-9-_=]+$
type
required
string
Enum: "hashed" "key"
created
required
string <date-time>
lastModified
required
string <date-time>
description
string
object (apikeys)

Stores information about generated admin API keys. The keys listed here have no operational meaning, but are used to track the keys that have been generated.

pattern property
object
id
required
string^[a-zA-Z0-9-_/+]+$

the API token id (jti)

created
required
string <date-time>
expiration
required
string <date-time>
roles
required
Array of strings
subject
required
string

the subject of the API token (sub)

description
string
object (groups)
pattern property
object (Group)

A group of members. Can be referenced in access.admin.role.

required
Array of objects
object (sidekick)
editUrlLabel
string

The label of the custom editing environment.

editUrlPattern
string

The URL pattern for the custom editing environment. Supports placeholders like {{contentSourceUrl}} or {{pathname}}.

host
string <hostname>

The host name of the production website (overrides cdn.prod.host)

liveHost
string <hostname>

The host name of the live environment (overrides cdn.live.host, defaults to *.aem.live)

Array of objects (sidekickPlugin)
Array
badgeVariant
string
Enum: "gray" "red" "orange" "yellow" "chartreuse" "celery" "green" "seafoam" "cyan" "blue" "indigo" "purple" "fuchsia" "magenta"

The variant of the badge following the Adobe Spectrum badge variants

containerId
string

The ID of the container to add this plugin to

environments
Array of strings
Default: "any"
Items Enum: "any" "dev" "admin" "edit" "preview" "review" "live" "prod"

The environments to display this plugin in

event
string

The name of a custom event to fire when the button is clicked (defaults to id)

excludePaths
Array of strings

Excludes the plugin from these paths

id
required
string

The unique plugin ID

includePaths
Array of strings

Includes the plugin on these paths (overrides excludePaths)

isBadge
boolean

Renders the plugin as a badge

isContainer
boolean

Renders the plugin as a container for other plugins

isPalette
boolean

Opens the URL in a palette instead of a new tab

isPopover
boolean

Opens the URL in a popover instead of a new tab

paletteRect
string

The dimensions and position of the palette (top, left, bottom, right, width, height)

passConfig
boolean

Append ref, repo, owner, host, and project as query params to the URL

passReferrer
boolean

Append the referrer URL as a query param to the URL

pinned
boolean

Renders the plugin in the bar (true, default) or the menu (false)

popoverRect
string

The dimensions of the popover (width, height)

title
string

The button text

object non-empty

The button text in other supported languages

url
string

The URL to open when the button is clicked

previewHost
string <hostname>

The host name of the preview environment (overrides cdn.preview.host, defaults to *.aem.page)

project
string

The name of the project to display in the sidekick

reviewHost
string <hostname>

The host name of the review environment (overrides cdn.review.host, defaults to *.aem.reviews)

Array of objects (sidekickSpecialView)
Array
id
required
string

The unique view ID

path
required
string

Open the special view on this path

viewer
required
string

The URL of the special view. The resource path will be passed to it via 'path' parameter

object (metadata-source)
source
Array of strings
object (robots)
txt
string
public
object (public)

Public configuration

object (events)
required
object
target
required
string^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$
object (features)

Features configuration

pattern property
object
property name*
additional property
any
object (limits)

Features configuration

pattern property
object
description
string
property name*
additional property
any
object
profile
string^[0-9a-zA-Z-_]+$

Responses

Request samples

Content type
application/json
{
  • "version": 1,
  • "name": "string",
  • "title": "string",
  • "description": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "content": {
    },
  • "code": {
    },
  • "folders": { },
  • "headers": { },
  • "cdn": {
    },
  • "access": {
    },
  • "tokens": { },
  • "secrets": { },
  • "apiKeys": { },
  • "groups": { },
  • "sidekick": {
    },
  • "metadata": {
    },
  • "robots": {
    },
  • "public": { },
  • "events": {
    },
  • "features": { },
  • "limits": { },
  • "extends": {
    }
}

Response samples

Content type
application/json
{
  • "version": 1,
  • "name": "string",
  • "title": "string",
  • "description": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "content": {
    },
  • "code": {
    },
  • "folders": { },
  • "headers": { },
  • "cdn": {
    },
  • "access": {
    },
  • "tokens": { },
  • "secrets": { },
  • "apiKeys": { },
  • "groups": { },
  • "sidekick": {
    },
  • "metadata": {
    },
  • "robots": {
    },
  • "public": { },
  • "events": {
    },
  • "features": { },
  • "limits": { },
  • "extends": {
    }
}

Delete Site Config

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Responses

Read Site robots.txt Config

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Responses

Update Site robots.txt Config.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Request Body schema: text/plain
string

Responses

List access tokens

Returns the access tokens

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Responses

Response samples

Content type
application/json
{ }

Create new access token

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "value": "string",
  • "created": "2019-08-24T14:15:22Z"
}

Read access token

Returns the access token

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

id
required
string

access token id.

Responses

Response samples

Content type
application/json
{ }

Delete access token

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

id
required
string

access token id.

Responses

List site secrets

Returns the site secrets

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Responses

Response samples

Content type
application/json
{ }

Create new site secret

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Request Body schema: application/json
One of
description
string

Responses

Request samples

Content type
application/json
Example
{
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "description": "string",
  • "value": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z"
}

Read secret

Returns the secret

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

id
required
string

secret id.

Responses

Response samples

Content type
application/json
{ }

Delete site secret

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

id
required
string

secret id.

Responses

Read Aggregated Site Config

Returns the aggregated site level configuration. This includes the inherited values from the profile.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Responses

Response samples

Content type
application/json
{
  • "version": 1,
  • "name": "string",
  • "title": "string",
  • "description": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "content": {
    },
  • "code": {
    },
  • "folders": { },
  • "headers": { },
  • "cdn": {
    },
  • "access": {
    },
  • "tokens": { },
  • "secrets": { },
  • "apiKeys": { },
  • "groups": { },
  • "sidekick": {
    },
  • "metadata": {
    },
  • "robots": {
    },
  • "public": { },
  • "events": {
    },
  • "features": { },
  • "limits": { },
  • "extends": {
    }
}

Profile Config

Please note that most of the configuration objects that have an explicit schema can also be addressed directly, even if not listed in this documentation.
For example the production CDN configuration can be managed via the /config/{org}/profiles/default-profile/cdn/prod.json endpoint.

ProfileConfig

version
required
integer
Default: 1
Value: 1
title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

created
required
string <date-time> (created)

the date and time this configuration was created.

lastModified
required
string <date-time> (lastModified)

the date and time this configuration was modified last.

object (content)

Defines the content bus location and source.

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

contentBusId
required
string
required
Google Content Source (object) or Onedrive Content Source (object) or Markup Content Source (object)
One of
type
required
any
Value: "google"
url
required
string <uri>
id
required
string

Google drive ID of the root folder; updated automatically when updating the url.

Markup Content Source (object)

Overlay from a BYOM source. Previewing resources will try the overlay source first. Please note, that the overlay config is tied to the base content and not to the site config. I.e. it's not possible to have multiple sites with different overlays on the same base content.

One of
type
required
any
Value: "markup"
url
required
string <uri>
suffix
string
object (code)

Defines the code bus location and source.

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

owner
required
string^[a-zA-Z0-9_-]+$
repo
required
string^[a-zA-Z0-9_-]+$
required
object
type
required
any
Value: "github"
url
required
string <uri>
raw_url
string <uri>
secretId
string^[a-zA-Z0-9-_=]+$
owner
string^[a-zA-Z0-9_-]+$
repo
string^[a-zA-Z0-9_-]+$
object (folders)
^/[a-zA-Z0-9-_/.]*$
pattern property
string
object (headers)
pattern property
Array of objects (keyValuePair)
Array
key
required
string
value
required
string
object (cdn)
Fastly CDN Config (object) or Cloudflare CDN Config (object) or Akamai CDN Config (object) or Managed CDN Config (object) or Cloudfront CDN Config (object) or EmptyConfig (object)
One of
type
required
string
Value: "fastly"
host
required
string

production host

route
Array of strings

Routes on the CDN that are rendered with Franklin

serviceId
required
string

The Fastly Service ID

authToken
required
string

A Fastly token for purging

object
host
required
string

Sidekick config to override the default previewHost. it supports parameters $owner and $repo

object
host
required
string

Sidekick config to override the default liveHost. it supports parameters $owner and $repo

object
host
required
string

Sidekick config to override the default reviewHost. it supports parameters $owner and $repo

object (access)
object (access-admin)
object (Role)
boolean or string
Default: "auto"

Enforce authentication if set to true. If set to 'auto' it will enforce authentication if a role mapping is defined. defaults to 'auto'.

defaultRole
Array of strings
Items Enum: "admin" "author" "publish" "develop" "basic_author" "basic_publish" "config" "config_admin"

the default roles assigned to the users. defaults to basic_publish for unauthenticated setups.

apiKeyId
Array of strings

the id of the API key(s). this is used to validate the API KEYS and allows to invalidate them.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (tokens)
Deprecated

site tokens. deprecated: use the org secrets instead.

pattern property
object
id
string^[a-zA-Z0-9-_=]+$
hash
string^[a-zA-Z0-9-_=]+$
created
string <date-time>
object (secrets)

Defines organization level secrets.

pattern property
object or object
One of
hash
required
string^[a-zA-Z0-9-_=]+$
id
required
string^[a-zA-Z0-9-_=]+$
type
required
string
Enum: "hashed" "key"
created
required
string <date-time>
lastModified
required
string <date-time>
description
string
object (groups)
pattern property
object (Group)

A group of members. Can be referenced in access.admin.role.

required
Array of objects
object (sidekick)
editUrlLabel
string

The label of the custom editing environment.

editUrlPattern
string

The URL pattern for the custom editing environment. Supports placeholders like {{contentSourceUrl}} or {{pathname}}.

host
string <hostname>

The host name of the production website (overrides cdn.prod.host)

liveHost
string <hostname>

The host name of the live environment (overrides cdn.live.host, defaults to *.aem.live)

Array of objects (sidekickPlugin)
Array
badgeVariant
string
Enum: "gray" "red" "orange" "yellow" "chartreuse" "celery" "green" "seafoam" "cyan" "blue" "indigo" "purple" "fuchsia" "magenta"

The variant of the badge following the Adobe Spectrum badge variants

containerId
string

The ID of the container to add this plugin to

environments
Array of strings
Default: "any"
Items Enum: "any" "dev" "admin" "edit" "preview" "review" "live" "prod"

The environments to display this plugin in

event
string

The name of a custom event to fire when the button is clicked (defaults to id)

excludePaths
Array of strings

Excludes the plugin from these paths

id
required
string

The unique plugin ID

includePaths
Array of strings

Includes the plugin on these paths (overrides excludePaths)

isBadge
boolean

Renders the plugin as a badge

isContainer
boolean

Renders the plugin as a container for other plugins

isPalette
boolean

Opens the URL in a palette instead of a new tab

isPopover
boolean

Opens the URL in a popover instead of a new tab

paletteRect
string

The dimensions and position of the palette (top, left, bottom, right, width, height)

passConfig
boolean

Append ref, repo, owner, host, and project as query params to the URL

passReferrer
boolean

Append the referrer URL as a query param to the URL

pinned
boolean

Renders the plugin in the bar (true, default) or the menu (false)

popoverRect
string

The dimensions of the popover (width, height)

title
string

The button text

object non-empty

The button text in other supported languages

url
string

The URL to open when the button is clicked

previewHost
string <hostname>

The host name of the preview environment (overrides cdn.preview.host, defaults to *.aem.page)

project
string

The name of the project to display in the sidekick

reviewHost
string <hostname>

The host name of the review environment (overrides cdn.review.host, defaults to *.aem.reviews)

Array of objects (sidekickSpecialView)
Array
id
required
string

The unique view ID

path
required
string

Open the special view on this path

viewer
required
string

The URL of the special view. The resource path will be passed to it via 'path' parameter

object (metadata-source)
source
Array of strings
object (robots)
txt
string
public
object (public)

Public configuration

object (events)
required
object
target
required
string^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$
object (features)

Features configuration

pattern property
object
property name*
additional property
any
object (limits)

Features configuration

pattern property
object
description
string
property name*
additional property
any
{
  • "version": 1,
  • "title": "string",
  • "description": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "content": {
    },
  • "code": {
    },
  • "folders": { },
  • "headers": { },
  • "cdn": {
    },
  • "access": {
    },
  • "tokens": { },
  • "secrets": { },
  • "groups": { },
  • "sidekick": {
    },
  • "metadata": {
    },
  • "robots": {
    },
  • "public": { },
  • "events": {
    },
  • "features": { },
  • "limits": { }
}

ProfileConfigList

required
Array of objects
Array
name
required
string
{
  • "profiles": [
    ]
}

AdminAccessConfig

object (Role)
^[a-z-_]+$
pattern property
Array of strings

The email glob of the users or a group reference for the respective role.

boolean or string
Default: "auto"

Enforce authentication if set to true. If set to 'auto' it will enforce authentication if a role mapping is defined. defaults to 'auto'.

One of
boolean
Default: "auto"

Enforce authentication if set to true. If set to 'auto' it will enforce authentication if a role mapping is defined. defaults to 'auto'.

defaultRole
Array of strings
Items Enum: "admin" "author" "publish" "develop" "basic_author" "basic_publish" "config" "config_admin"

the default roles assigned to the users. defaults to basic_publish for unauthenticated setups.

apiKeyId
Array of strings

the id of the API key(s). this is used to validate the API KEYS and allows to invalidate them.

{
  • "role": { },
  • "requireAuth": "auto",
  • "defaultRole": [
    ],
  • "apiKeyId": [
    ]
}

SiteAccessConfig

allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

{
  • "allow": [
    ],
  • "secretId": [
    ],
  • "apiKeyId": [
    ]
}

AccessConfig

object (access-admin)
object (Role)
^[a-z-_]+$
pattern property
Array of strings

The email glob of the users or a group reference for the respective role.

boolean or string
Default: "auto"

Enforce authentication if set to true. If set to 'auto' it will enforce authentication if a role mapping is defined. defaults to 'auto'.

One of
boolean
Default: "auto"

Enforce authentication if set to true. If set to 'auto' it will enforce authentication if a role mapping is defined. defaults to 'auto'.

defaultRole
Array of strings
Items Enum: "admin" "author" "publish" "develop" "basic_author" "basic_publish" "config" "config_admin"

the default roles assigned to the users. defaults to basic_publish for unauthenticated setups.

apiKeyId
Array of strings

the id of the API key(s). this is used to validate the API KEYS and allows to invalidate them.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

{
  • "admin": {
    },
  • "site": {
    },
  • "preview": {
    },
  • "live": {
    }
}

CDNConfig

Fastly CDN Config (object) or Cloudflare CDN Config (object) or Akamai CDN Config (object) or Managed CDN Config (object) or Cloudfront CDN Config (object) or EmptyConfig (object)
One of
type
required
string
Value: "fastly"
host
required
string

production host

route
Array of strings

Routes on the CDN that are rendered with Franklin

serviceId
required
string

The Fastly Service ID

authToken
required
string

A Fastly token for purging

object
host
required
string

Sidekick config to override the default previewHost. it supports parameters $owner and $repo

object
host
required
string

Sidekick config to override the default liveHost. it supports parameters $owner and $repo

object
host
required
string

Sidekick config to override the default reviewHost. it supports parameters $owner and $repo

{
  • "prod": {
    },
  • "live": {
    },
  • "preview": {
    },
  • "review": {
    }
}

CodeConfig

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

owner
required
string^[a-zA-Z0-9_-]+$
repo
required
string^[a-zA-Z0-9_-]+$
required
object
type
required
any
Value: "github"
url
required
string <uri>
raw_url
string <uri>
secretId
string^[a-zA-Z0-9-_=]+$
owner
string^[a-zA-Z0-9_-]+$
repo
string^[a-zA-Z0-9_-]+$
{
  • "title": "string",
  • "description": "string",
  • "owner": "string",
  • "repo": "string",
  • "source": {}
}

ContentConfig

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

contentBusId
required
string
required
Google Content Source (object) or Onedrive Content Source (object) or Markup Content Source (object)
One of
type
required
any
Value: "google"
url
required
string <uri>
id
required
string

Google drive ID of the root folder; updated automatically when updating the url.

Markup Content Source (object)

Overlay from a BYOM source. Previewing resources will try the overlay source first. Please note, that the overlay config is tied to the base content and not to the site config. I.e. it's not possible to have multiple sites with different overlays on the same base content.

One of
type
required
any
Value: "markup"
url
required
string <uri>
suffix
string
{
  • "title": "string",
  • "description": "string",
  • "contentBusId": "string",
  • "source": {},
  • "overlay": {}
}

FoldersConfig

^/[a-zA-Z0-9-_/.]*$
pattern property
string
{ }

HeadersConfig

pattern property
Array of objects (keyValuePair)
Array
key
required
string
value
required
string
{ }

MetadataConfig

source
Array of strings
{
  • "source": [
    ]
}

PublicConfig

object (PublicConfig)

Public configuration

{ }

RobotsConfig

txt
string
{
  • "txt": "string"
}

SidekickConfig

editUrlLabel
string

The label of the custom editing environment.

editUrlPattern
string

The URL pattern for the custom editing environment. Supports placeholders like {{contentSourceUrl}} or {{pathname}}.

host
string <hostname>

The host name of the production website (overrides cdn.prod.host)

liveHost
string <hostname>

The host name of the live environment (overrides cdn.live.host, defaults to *.aem.live)

Array of objects (sidekickPlugin)
Array
badgeVariant
string
Enum: "gray" "red" "orange" "yellow" "chartreuse" "celery" "green" "seafoam" "cyan" "blue" "indigo" "purple" "fuchsia" "magenta"

The variant of the badge following the Adobe Spectrum badge variants

containerId
string

The ID of the container to add this plugin to

environments
Array of strings
Default: "any"
Items Enum: "any" "dev" "admin" "edit" "preview" "review" "live" "prod"

The environments to display this plugin in

event
string

The name of a custom event to fire when the button is clicked (defaults to id)

excludePaths
Array of strings

Excludes the plugin from these paths

id
required
string

The unique plugin ID

includePaths
Array of strings

Includes the plugin on these paths (overrides excludePaths)

isBadge
boolean

Renders the plugin as a badge

isContainer
boolean

Renders the plugin as a container for other plugins

isPalette
boolean

Opens the URL in a palette instead of a new tab

isPopover
boolean

Opens the URL in a popover instead of a new tab

paletteRect
string

The dimensions and position of the palette (top, left, bottom, right, width, height)

passConfig
boolean

Append ref, repo, owner, host, and project as query params to the URL

passReferrer
boolean

Append the referrer URL as a query param to the URL

pinned
boolean

Renders the plugin in the bar (true, default) or the menu (false)

popoverRect
string

The dimensions of the popover (width, height)

title
string

The button text

object non-empty

The button text in other supported languages

url
string

The URL to open when the button is clicked

previewHost
string <hostname>

The host name of the preview environment (overrides cdn.preview.host, defaults to *.aem.page)

project
string

The name of the project to display in the sidekick

reviewHost
string <hostname>

The host name of the review environment (overrides cdn.review.host, defaults to *.aem.reviews)

Array of objects (sidekickSpecialView)
Array
id
required
string

The unique view ID

path
required
string

Open the special view on this path

viewer
required
string

The URL of the special view. The resource path will be passed to it via 'path' parameter

{
  • "editUrlLabel": "string",
  • "editUrlPattern": "string",
  • "host": "example.com",
  • "liveHost": "example.com",
  • "plugins": [
    ],
  • "previewHost": "example.com",
  • "project": "string",
  • "reviewHost": "example.com",
  • "specialViews": [
    ]
}

TokensConfig

pattern property
object
id
string^[a-zA-Z0-9-_=]+$
hash
string^[a-zA-Z0-9-_=]+$
created
string <date-time>
{ }

SecretsConfig

pattern property
object or object
One of
hash
required
string^[a-zA-Z0-9-_=]+$
id
required
string^[a-zA-Z0-9-_=]+$
type
required
string
Enum: "hashed" "key"
created
required
string <date-time>
lastModified
required
string <date-time>
description
string
{ }

Read secret

Returns the secret

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

id
required
string

secret id.

Responses

Response samples

Content type
application/json
{ }

List Profile Config

Returns the configuration profile names.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

Responses

Response samples

Content type
application/json
{
  • "profiles": [
    ]
}

Read Profile Config

Returns the Profile level configuration.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

profile
required
string

profile name.

Responses

Response samples

Content type
application/json
{
  • "version": 1,
  • "title": "string",
  • "description": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "content": {
    },
  • "code": {
    },
  • "folders": { },
  • "headers": { },
  • "cdn": {
    },
  • "access": {
    },
  • "tokens": { },
  • "secrets": { },
  • "groups": { },
  • "sidekick": {
    },
  • "metadata": {
    },
  • "robots": {
    },
  • "public": { },
  • "events": {
    },
  • "features": { },
  • "limits": { }
}

Update Profile Config

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

profile
required
string

profile name.

Request Body schema: application/json
version
required
integer
Default: 1
Value: 1
title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

created
required
string <date-time> (created)

the date and time this configuration was created.

lastModified
required
string <date-time> (lastModified)

the date and time this configuration was modified last.

object (content)

Defines the content bus location and source.

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

contentBusId
required
string
required
Google Content Source (object) or Onedrive Content Source (object) or Markup Content Source (object)
One of
type
required
any
Value: "google"
url
required
string <uri>
id
required
string

Google drive ID of the root folder; updated automatically when updating the url.

Markup Content Source (object)

Overlay from a BYOM source. Previewing resources will try the overlay source first. Please note, that the overlay config is tied to the base content and not to the site config. I.e. it's not possible to have multiple sites with different overlays on the same base content.

One of
type
required
any
Value: "markup"
url
required
string <uri>
suffix
string
object (code)

Defines the code bus location and source.

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

owner
required
string^[a-zA-Z0-9_-]+$
repo
required
string^[a-zA-Z0-9_-]+$
required
object
type
required
any
Value: "github"
url
required
string <uri>
raw_url
string <uri>
secretId
string^[a-zA-Z0-9-_=]+$
owner
string^[a-zA-Z0-9_-]+$
repo
string^[a-zA-Z0-9_-]+$
object (folders)
^/[a-zA-Z0-9-_/.]*$
pattern property
string
object (headers)
pattern property
Array of objects (keyValuePair)
Array
key
required
string
value
required
string
object (cdn)
Fastly CDN Config (object) or Cloudflare CDN Config (object) or Akamai CDN Config (object) or Managed CDN Config (object) or Cloudfront CDN Config (object) or EmptyConfig (object)
One of
type
required
string
Value: "fastly"
host
required
string

production host

route
Array of strings

Routes on the CDN that are rendered with Franklin

serviceId
required
string

The Fastly Service ID

authToken
required
string

A Fastly token for purging

object
host
required
string

Sidekick config to override the default previewHost. it supports parameters $owner and $repo

object
host
required
string

Sidekick config to override the default liveHost. it supports parameters $owner and $repo

object
host
required
string

Sidekick config to override the default reviewHost. it supports parameters $owner and $repo

object (access)
object (access-admin)
object (Role)
boolean or string
Default: "auto"

Enforce authentication if set to true. If set to 'auto' it will enforce authentication if a role mapping is defined. defaults to 'auto'.

defaultRole
Array of strings
Items Enum: "admin" "author" "publish" "develop" "basic_author" "basic_publish" "config" "config_admin"

the default roles assigned to the users. defaults to basic_publish for unauthenticated setups.

apiKeyId
Array of strings

the id of the API key(s). this is used to validate the API KEYS and allows to invalidate them.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (tokens)
Deprecated

site tokens. deprecated: use the org secrets instead.

pattern property
object
id
string^[a-zA-Z0-9-_=]+$
hash
string^[a-zA-Z0-9-_=]+$
created
string <date-time>
object (secrets)

Defines organization level secrets.

pattern property
object or object
One of
hash
required
string^[a-zA-Z0-9-_=]+$
id
required
string^[a-zA-Z0-9-_=]+$
type
required
string
Enum: "hashed" "key"
created
required
string <date-time>
lastModified
required
string <date-time>
description
string
object (groups)
pattern property
object (Group)

A group of members. Can be referenced in access.admin.role.

required
Array of objects
object (sidekick)
editUrlLabel
string

The label of the custom editing environment.

editUrlPattern
string

The URL pattern for the custom editing environment. Supports placeholders like {{contentSourceUrl}} or {{pathname}}.

host
string <hostname>

The host name of the production website (overrides cdn.prod.host)

liveHost
string <hostname>

The host name of the live environment (overrides cdn.live.host, defaults to *.aem.live)

Array of objects (sidekickPlugin)
Array
badgeVariant
string
Enum: "gray" "red" "orange" "yellow" "chartreuse" "celery" "green" "seafoam" "cyan" "blue" "indigo" "purple" "fuchsia" "magenta"

The variant of the badge following the Adobe Spectrum badge variants

containerId
string

The ID of the container to add this plugin to

environments
Array of strings
Default: "any"
Items Enum: "any" "dev" "admin" "edit" "preview" "review" "live" "prod"

The environments to display this plugin in

event
string

The name of a custom event to fire when the button is clicked (defaults to id)

excludePaths
Array of strings

Excludes the plugin from these paths

id
required
string

The unique plugin ID

includePaths
Array of strings

Includes the plugin on these paths (overrides excludePaths)

isBadge
boolean

Renders the plugin as a badge

isContainer
boolean

Renders the plugin as a container for other plugins

isPalette
boolean

Opens the URL in a palette instead of a new tab

isPopover
boolean

Opens the URL in a popover instead of a new tab

paletteRect
string

The dimensions and position of the palette (top, left, bottom, right, width, height)

passConfig
boolean

Append ref, repo, owner, host, and project as query params to the URL

passReferrer
boolean

Append the referrer URL as a query param to the URL

pinned
boolean

Renders the plugin in the bar (true, default) or the menu (false)

popoverRect
string

The dimensions of the popover (width, height)

title
string

The button text

object non-empty

The button text in other supported languages

url
string

The URL to open when the button is clicked

previewHost
string <hostname>

The host name of the preview environment (overrides cdn.preview.host, defaults to *.aem.page)

project
string

The name of the project to display in the sidekick

reviewHost
string <hostname>

The host name of the review environment (overrides cdn.review.host, defaults to *.aem.reviews)

Array of objects (sidekickSpecialView)
Array
id
required
string

The unique view ID

path
required
string

Open the special view on this path

viewer
required
string

The URL of the special view. The resource path will be passed to it via 'path' parameter

object (metadata-source)
source
Array of strings
object (robots)
txt
string
public
object (public)

Public configuration

object (events)
required
object
target
required
string^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$
object (features)

Features configuration

pattern property
object
property name*
additional property
any
object (limits)

Features configuration

pattern property
object
description
string
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "version": 1,
  • "title": "string",
  • "description": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "content": {
    },
  • "code": {
    },
  • "folders": { },
  • "headers": { },
  • "cdn": {
    },
  • "access": {
    },
  • "tokens": { },
  • "secrets": { },
  • "groups": { },
  • "sidekick": {
    },
  • "metadata": {
    },
  • "robots": {
    },
  • "public": { },
  • "events": {
    },
  • "features": { },
  • "limits": { }
}

Response samples

Content type
application/json
{
  • "version": 1,
  • "title": "string",
  • "description": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "content": {
    },
  • "code": {
    },
  • "folders": { },
  • "headers": { },
  • "cdn": {
    },
  • "access": {
    },
  • "tokens": { },
  • "secrets": { },
  • "groups": { },
  • "sidekick": {
    },
  • "metadata": {
    },
  • "robots": {
    },
  • "public": { },
  • "events": {
    },
  • "features": { },
  • "limits": { }
}

Create Profile Config

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

profile
required
string

profile name.

Request Body schema: application/json
version
required
integer
Default: 1
Value: 1
title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

created
required
string <date-time> (created)

the date and time this configuration was created.

lastModified
required
string <date-time> (lastModified)

the date and time this configuration was modified last.

object (content)

Defines the content bus location and source.

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

contentBusId
required
string
required
Google Content Source (object) or Onedrive Content Source (object) or Markup Content Source (object)
One of
type
required
any
Value: "google"
url
required
string <uri>
id
required
string

Google drive ID of the root folder; updated automatically when updating the url.

Markup Content Source (object)

Overlay from a BYOM source. Previewing resources will try the overlay source first. Please note, that the overlay config is tied to the base content and not to the site config. I.e. it's not possible to have multiple sites with different overlays on the same base content.

One of
type
required
any
Value: "markup"
url
required
string <uri>
suffix
string
object (code)

Defines the code bus location and source.

title
string (title)

human readable title. has no influence on the configuration.

description
string (description)

description for clarity. has no influence on the configuration.

owner
required
string^[a-zA-Z0-9_-]+$
repo
required
string^[a-zA-Z0-9_-]+$
required
object
type
required
any
Value: "github"
url
required
string <uri>
raw_url
string <uri>
secretId
string^[a-zA-Z0-9-_=]+$
owner
string^[a-zA-Z0-9_-]+$
repo
string^[a-zA-Z0-9_-]+$
object (folders)
^/[a-zA-Z0-9-_/.]*$
pattern property
string
object (headers)
pattern property
Array of objects (keyValuePair)
Array
key
required
string
value
required
string
object (cdn)
Fastly CDN Config (object) or Cloudflare CDN Config (object) or Akamai CDN Config (object) or Managed CDN Config (object) or Cloudfront CDN Config (object) or EmptyConfig (object)
One of
type
required
string
Value: "fastly"
host
required
string

production host

route
Array of strings

Routes on the CDN that are rendered with Franklin

serviceId
required
string

The Fastly Service ID

authToken
required
string

A Fastly token for purging

object
host
required
string

Sidekick config to override the default previewHost. it supports parameters $owner and $repo

object
host
required
string

Sidekick config to override the default liveHost. it supports parameters $owner and $repo

object
host
required
string

Sidekick config to override the default reviewHost. it supports parameters $owner and $repo

object (access)
object (access-admin)
object (Role)
boolean or string
Default: "auto"

Enforce authentication if set to true. If set to 'auto' it will enforce authentication if a role mapping is defined. defaults to 'auto'.

defaultRole
Array of strings
Items Enum: "admin" "author" "publish" "develop" "basic_author" "basic_publish" "config" "config_admin"

the default roles assigned to the users. defaults to basic_publish for unauthenticated setups.

apiKeyId
Array of strings

the id of the API key(s). this is used to validate the API KEYS and allows to invalidate them.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (access-site)
allow
Array of strings

The email glob of the users or a group reference that are allowed access

secretId
Array of strings[ items^[a-zA-Z0-9-_=+/]+$ ]

IDs of the hashed secrets that are allowed.

apiKeyId
Array of strings
Deprecated

IDs of the api keys that are allowed. This is deprecated. use secretId instead.

object (tokens)
Deprecated

site tokens. deprecated: use the org secrets instead.

pattern property
object
id
string^[a-zA-Z0-9-_=]+$
hash
string^[a-zA-Z0-9-_=]+$
created
string <date-time>
object (secrets)

Defines organization level secrets.

pattern property
object or object
One of
hash
required
string^[a-zA-Z0-9-_=]+$
id
required
string^[a-zA-Z0-9-_=]+$
type
required
string
Enum: "hashed" "key"
created
required
string <date-time>
lastModified
required
string <date-time>
description
string
object (groups)
pattern property
object (Group)

A group of members. Can be referenced in access.admin.role.

required
Array of objects
object (sidekick)
editUrlLabel
string

The label of the custom editing environment.

editUrlPattern
string

The URL pattern for the custom editing environment. Supports placeholders like {{contentSourceUrl}} or {{pathname}}.

host
string <hostname>

The host name of the production website (overrides cdn.prod.host)

liveHost
string <hostname>

The host name of the live environment (overrides cdn.live.host, defaults to *.aem.live)

Array of objects (sidekickPlugin)
Array
badgeVariant
string
Enum: "gray" "red" "orange" "yellow" "chartreuse" "celery" "green" "seafoam" "cyan" "blue" "indigo" "purple" "fuchsia" "magenta"

The variant of the badge following the Adobe Spectrum badge variants

containerId
string

The ID of the container to add this plugin to

environments
Array of strings
Default: "any"
Items Enum: "any" "dev" "admin" "edit" "preview" "review" "live" "prod"

The environments to display this plugin in

event
string

The name of a custom event to fire when the button is clicked (defaults to id)

excludePaths
Array of strings

Excludes the plugin from these paths

id
required
string

The unique plugin ID

includePaths
Array of strings

Includes the plugin on these paths (overrides excludePaths)

isBadge
boolean

Renders the plugin as a badge

isContainer
boolean

Renders the plugin as a container for other plugins

isPalette
boolean

Opens the URL in a palette instead of a new tab

isPopover
boolean

Opens the URL in a popover instead of a new tab

paletteRect
string

The dimensions and position of the palette (top, left, bottom, right, width, height)

passConfig
boolean

Append ref, repo, owner, host, and project as query params to the URL

passReferrer
boolean

Append the referrer URL as a query param to the URL

pinned
boolean

Renders the plugin in the bar (true, default) or the menu (false)

popoverRect
string

The dimensions of the popover (width, height)

title
string

The button text

object non-empty

The button text in other supported languages

url
string

The URL to open when the button is clicked

previewHost
string <hostname>

The host name of the preview environment (overrides cdn.preview.host, defaults to *.aem.page)

project
string

The name of the project to display in the sidekick

reviewHost
string <hostname>

The host name of the review environment (overrides cdn.review.host, defaults to *.aem.reviews)

Array of objects (sidekickSpecialView)
Array
id
required
string

The unique view ID

path
required
string

Open the special view on this path

viewer
required
string

The URL of the special view. The resource path will be passed to it via 'path' parameter

object (metadata-source)
source
Array of strings
object (robots)
txt
string
public
object (public)

Public configuration

object (events)
required
object
target
required
string^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$
object (features)

Features configuration

pattern property
object
property name*
additional property
any
object (limits)

Features configuration

pattern property
object
description
string
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "version": 1,
  • "title": "string",
  • "description": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "content": {
    },
  • "code": {
    },
  • "folders": { },
  • "headers": { },
  • "cdn": {
    },
  • "access": {
    },
  • "tokens": { },
  • "secrets": { },
  • "groups": { },
  • "sidekick": {
    },
  • "metadata": {
    },
  • "robots": {
    },
  • "public": { },
  • "events": {
    },
  • "features": { },
  • "limits": { }
}

Delete Profile Config

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

profile
required
string

profile name.

Responses

Read Profile robots.txt Config

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

profile
required
string

profile name.

Responses

Update Profile robots.txt Config.

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

profile
required
string

profile name.

Request Body schema: text/plain
string

Responses

List access tokens

Returns the access tokens

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

profile
required
string

profile name.

Responses

Response samples

Content type
application/json
{ }

Create new access token

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

profile
required
string

profile name.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "value": "string",
  • "created": "2019-08-24T14:15:22Z"
}

Read access token

Returns the access token

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

profile
required
string

profile name.

id
required
string

access token id.

Responses

Response samples

Content type
application/json
{ }

Delete access token

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

profile
required
string

profile name.

id
required
string

access token id.

Responses

List profile secrets

Returns the profile secrets

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

profile
required
string

profile name.

Responses

Response samples

Content type
application/json
{ }

Create new profile secret

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

profile
required
string

profile name.

Request Body schema: application/json
One of
description
string

Responses

Request samples

Content type
application/json
Example
{
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "description": "string",
  • "value": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "lastModified": "2019-08-24T14:15:22Z"
}

Read secret

Returns the secret

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

profile
required
string

profile name.

id
required
string

secret id.

Responses

Response samples

Content type
application/json
{ }

Delete profile secret

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

profile
required
string

profile name.

id
required
string

secret id.

Responses

Index Config

A configuration containing one or more index definitions.

IndexConfig

version
integer
Default: 1
Value: 1
object
pattern property
object (An individual index)
include
Array of strings (Include)

Glob patterns for paths where this index is used.

exclude
Array of strings (Exclude)

Glob patterns for paths where this index must not be used.

target
string <uri-reference>

The data sink to store the extracted data in. This can be an Excel workbook, a Google spreadsheet or an S3 object

required
object (Properties)

The properties to add to the index

{
  • "version": 1,
  • "indices": { }
}

Read Index Configuration

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Responses

Response samples

Content type
text/yaml

Success response of reading an index configuration

version: 1
indices:
  default:
    include:
      - '/**'
    target: /query-index.json
    properties:
      lastModified:
        select: none
        value: parseTimestamp(headers["last-modified"], "ddd, DD MMM YYYY hh:mm:ss GMT")

Update Index Configuration

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Request Body schema: text/yaml
required
version
integer
Default: 1
Value: 1
object
pattern property
object (An individual index)
include
Array of strings (Include)

Glob patterns for paths where this index is used.

exclude
Array of strings (Exclude)

Glob patterns for paths where this index must not be used.

target
string <uri-reference>

The data sink to store the extracted data in. This can be an Excel workbook, a Google spreadsheet or an S3 object

required
object (Properties)

The properties to add to the index

Responses

Create Index Configuration

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Request Body schema: text/yaml
required
version
integer
Default: 1
Value: 1
object
pattern property
object (An individual index)
include
Array of strings (Include)

Glob patterns for paths where this index is used.

exclude
Array of strings (Exclude)

Glob patterns for paths where this index must not be used.

target
string <uri-reference>

The data sink to store the extracted data in. This can be an Excel workbook, a Google spreadsheet or an S3 object

required
object (Properties)

The properties to add to the index

Responses

Delete Index Configuration

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Responses

Sitemap Config

A configuration containing one or more sitemap definitions.

SitemapConfig

version
integer
Default: 1
Value: 1
object
pattern property
object
source
string (Source)

The source resource path to get records from. These records should at least contain a path property.

origin
string (Origin)

The origin to prepend to paths found in the source.

destination
string (Path)

The destination resource path to store sitemap to.

lastmod
string (Lastmod)

The format to use for last modification of a location. If not present, no last modification is added.

object (Sitemap Languages)

The languages to add to the sitemap

extension
string (Location extension)

Extension to append to every location generated for this sitemap. Default is empty

{
  • "version": 1,
  • "sitemaps": { }
}

Read Sitemap Configuration

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Responses

Response samples

Content type
text/yaml

Success response of reading a sitemap configuration

version: 1
sitemaps:
  default:
    source: /sitemap-index.json
    destination: /sitemap.xml
    lastmod: YYYY-MM-DD

Update Sitemap Configuration

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Request Body schema: text/yaml
required
version
integer
Default: 1
Value: 1
object
pattern property
object
source
string (Source)

The source resource path to get records from. These records should at least contain a path property.

origin
string (Origin)

The origin to prepend to paths found in the source.

destination
string (Path)

The destination resource path to store sitemap to.

lastmod
string (Lastmod)

The format to use for last modification of a location. If not present, no last modification is added.

object (Sitemap Languages)

The languages to add to the sitemap

extension
string (Location extension)

Extension to append to every location generated for this sitemap. Default is empty

Responses

Create Sitemap Configuration

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Request Body schema: text/yaml
required
version
integer
Default: 1
Value: 1
object
pattern property
object
source
string (Source)

The source resource path to get records from. These records should at least contain a path property.

origin
string (Origin)

The origin to prepend to paths found in the source.

destination
string (Path)

The destination resource path to store sitemap to.

lastmod
string (Lastmod)

The format to use for last modification of a location. If not present, no last modification is added.

object (Sitemap Languages)

The languages to add to the sitemap

extension
string (Location extension)

Extension to append to every location generated for this sitemap. Default is empty

Responses

Delete Sitemap Configuration

Authorizations:
AuthCookie
path Parameters
org
required
string

organisation name.

site
required
string

site id.

Responses