Admin API

Version: 20.x

The Admin API is a REST API that enables you to administer your Experience Edge for XM tenants.

Base URL

The base URL for the Admin API is https://edge.sitecorecloud.io/api/admin/v1.

Authentication

All endpoints use bearer authorization.

Headers

The following header is required:

Name

Format

Purpose

Authorization

Bearer {Token}

A JSON web token (JWT). Request a JWT for Experience Edge XM using OAuth.

Time-to-live

The time-to-live (TTL) determines the maximum time that content and media items are retained in the cache, which might be purged before that time expires. The TTL values for content (contentCacheTtl) and media items (mediaCacheTtl) are included as response parameters returned by several Admin API endpoints. The default value of both parameters is four hours:

RequestResponse
{
    "contentCacheTtl": "04:00:00",
    "contentCacheAutoClear": true,
    "mediaCacheTtl": "04:00:00",
    "mediaCacheAutoClear": true,
    "tenantCacheAutoClear": true
}

To set or update TTL values, use a string with the following notation:

RequestResponse
{days}.{hours}:(minutes}:{seconds}

For example, "720.00:00:00" sets the value to 720 days, and "00:15:00" sets the value to 15 minutes.

Endpoints

The Admin API has the following endpoints:

  • ClearCacheForTenant - clears the entire cache for a given tenant.

  • DeleteContent - removes tenant data from the data storage.

  • GetSettings - lists all available settings for a tenant.

  • UpdateSettings - updates all available settings for a tenant.

  • PatchSettings - updates a setting for a tenant using one or more Patch operations.

  • CreateWebhook - creates a new webhook.

  • UpdateWebhook - updates an existing webhook.

  • DeleteWebhook - deletes a specific webhook.

  • ListWebhooks - lists all webhooks for a tenant.

  • GetWebhookById - gets a specific tenant webhook.

ClearCacheForTenant

Clears the entire cache for a given tenant.

Relative route

/cache

HTTP verb

DELETE

Response format

Accepted status code (202)

DeleteContent

Removes tenant data from the data storage.

Relative route

/content

HTTP verb

DELETE

Example

https://edge.sitecorecloud.io/api/admin/v1/content

Response format

Accepted status code (202)

GetSettings

Lists all available settings for a tenant.

Relative route

/settings

HTTP verb

GET

Example

https://edge.sitecorecloud.io/api/admin/v1/settings

Response format

The settings for the tenant.

RequestResponse
{
    "contentCacheTtl": "04:00:00",
    "contentCacheAutoClear": true,
    "mediaCacheTtl": "04:00:00",
    "mediaCacheAutoClear": true,
    "tenantCacheAutoClear": true
}

UpdateSettings

Updates all available settings for a tenant.

Relative route

/settings

HTTP verb

PUT

Example

https://edge.sitecorecloud.io/api/admin/v1/settings

Body format

RequestResponse
{
    "contentCacheTtl": "04:00:00",
    "contentCacheAutoClear": true,
    "mediaCacheTtl": "04:00:00",
    "mediaCacheAutoClear": true,
    "tenantCacheAutoClear": true
}

Response status code

Accepted (202)

PatchSettings

Updates a setting using a patch operation or multiple patch operations. It uses the JSON patch format for operations and content-type headers as specified in https://tools.ietf.org/html/rfc6902.

Relative route

/settings

HTTP verb

PATCH

Example

https://edge.sitecorecloud.io/api/admin/v1/settings

Headers

Content-Type: application/json-patch+json

Body format

A settings operation. Only replace operations are allowed. For more information, see https://tools.ietf.org/html/rfc6902#section-4.3. The following example updates the contentcachettl setting to 15 minutes:

RequestResponse
[
    {
        "op":"replace",
        "path":"/contentcacheautoclear",
        "value":true
    },
    {
        "op":"replace",
        "path":"/contentcachettl",
        "value":"00:15:00"
    }
]

Response format

The settings for the tenant.

RequestResponse
{
    "contentCacheTtl": "00:15:00",
    "contentCacheAutoClear": true,
    "mediaCacheTtl": "04:00:00",
    "mediaCacheAutoClear": true,
    "tenantCacheAutoClear": true
}

Response status code

OK (200)

CreateWebhook

Creates a new webhook.

Important

When creating a webhook, you must use an HTTPS URI, and not HTTP.

Relative route

/webhooks

HTTP verb

POST

Body format

A webhook structure. Refer to Webhook objects to learn more about the various JSON objects used within the webhooks endpoint of the Edge Admin API.

RequestResponse
{
  "label": "My new webhook",
  "uri": "https://www.mysite.com/hooks/edge-hook",
  "method": "POST",
  "headers": {
    "x-header": "bar"
  },
  "body": "{\"rebuild\":\"true\"}",
  "createdBy": "anco",
  "executionMode": "OnEnd"
}

Response format

A webhook structure. Refer to Webhook objects to learn more about the various JSON objects used within the webhooks endpoint of the Edge Admin API.

RequestResponse
{
  "id": "5678",
  "tenantId": "mysite-corp",
  "label": "webhook 29",
  "uri": "https://www.mysite.com/hooks/edge-hook",
  "method": "POST",
  "headers": {
    "x-header": "bar"
  },
  "body": "{\"rebuild\":\"true\"}",
  "createdBy": "anco",
  "created": "2021-03-26T10:44:04.6107312+00:00",
  "executionMode": "OnEnd"
}

Response header

Returns the location of the new webhook. For example:

Location: https://edge.sitecorecloud.io/api/admin/v1/webhooks/12345

Response status code

Created (201)

UpdateWebhook

Updates an existing webhook.

Relative route

/webhooks/{id}

HTTP verb

PUT

Body format

A webhook structure. Refer to Webhook objects to learn more about the various JSON objects used within the webhooks endpoint of the Edge Admin API.

RequestResponse
{
  "label": "webhook 29",
  "uri": "https://www.acme.com/hooks/edge-hook",
  "method": "GET",
  "headers": {
    "x-header": "bar"
  },
  "body": "{\"rebuild\":\"true\"}",
  "createdBy": "anco",
  "created": "2021-03-26T10:44:04.6107312+00:00",
  "executionMode": "OnEnd"
}

Response status code

No content (204)

DeleteWebhook

Deletes a specific webhook.

Relative route

/webhooks/{id}

HTTP verb

DELETE

Example

https://edge.sitecorecloud.io/api/admin/v1/webhooks/789

Response status

No content (204)

ListWebhooks

Lists all webhooks for a tenant.

Relative route

/webhooks

HTTP verb

GET

Example

https://edge.sitecorecloud.io/api/admin/v1/webhooks

Response format

An array of webhooks. Refer to Webhook objects to learn more about the various JSON objects used within the webhooks endpoint of the Edge Admin API.

RequestResponse
[
  {
      "id": "1234",
      "tenantId": "test-tenant",
      "label": "webhook 92",
      "uri": "https://localhost/",
      "method": "POST",
      "body": "This is my optional body content",
      "created": "2021-03-26T10:44:04.6107312+00:00"
  },
  {
    "id": "5678",
    "tenantId": "test-tenant",
    "label": "webhook 29",
    "uri": "https://localhost/",
    "method": "POST",
    "headers": {
        "x-header": "bar"
    },
    "createdBy": "anco",
    "created": "2021-03-26T10:44:04.6107312+00:00"
    "executionMode": "OnEnd"
  }
]

GetWebhookById

Gets a specific tenant webhook by ID.

Relative route

/webhooks/{id}

HTTP verb

GET

Example

https://edge.sitecorecloud.io/api/admin/v1/webhooks/789

Response format

RequestResponse
{
      "id": "1234",
      "tenantId": "test-tenant",
      "label": "webhook 92",
      "uri": "https://localhost/",
      "method": "POST",
      "headers": {
          "x-header": "foo"
      },
      "body": "Optional body content",
      "createdBy": "adn",
      "created": "2021-03-26T10:44:04.6107312+00:00"
      "executionMode": "OnEnd"
  }

Do you have some feedback for us?

If you have suggestions for improving this article,