SpaceCat API (1.73.2)

Download OpenAPI specification:Download

The SpaceCat API is used to manage edge delivery site directory and obtain audit information.

Authentication

api_key

DEPRECATED, use scoped_api_key or ims_key. (Used for read-only operations.)

Security Scheme Type: API Key
Header parameter name: x-api-key

scoped_api_key

For endpoints which authenticate with scoped API keys

Security Scheme Type: API Key
Header parameter name: x-api-key

ims_key

Value must be a valid IMS user token which will be offline-validated.

Security Scheme Type: API Key
Header parameter name: authentication

admin_key

DEPRECATED, use scoped_api_key or ims_key. (Used for read and write operations.)

Security Scheme Type: API Key
Header parameter name: x-api-key

site

Site operations

Retrieve all sites for an organization

This endpoint is useful for retrieving all sites for an organization.

Authorizations:
api_key
path Parameters
organizationId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The organization ID in uuid format

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new site

This endpoint is useful for creating a new site.

Authorizations:
admin_key
Request Body schema: application/json
required
baseURL
required
string <url> (URL)

The base URL of the site

deliveryType
required
string (DeliveryType)
Enum: "aem_edge" "aem_cs" "other"

The type of the delivery this site is using

gitHubURL
string <url> (URL)

The optional GitHub URL of the site

goLiveDate
string or null <date-time> (DateTime)

The date and time when the site went live on AEM Edge

Responses

Request samples

Content type
application/json
{
  • "organizationId": "o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z",
  • "deliveryType": "aem_cs"
}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14",
  • "organizationId": "o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z",
  • "deliveryType": "aem_edge",
  • "goLiveDate": "2024-01-20T10:00:00Z",
  • "config": {
    },
  • "createdAt": "2023-12-15T09:30:00Z",
  • "updatedAt": "2024-01-19T11:20:00Z"
}

Retrieve all sites

This endpoint is useful for retrieving all sites.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve all sites by delivery type

This endpoint is useful for retrieving all sites by delivery type.

Authorizations:
api_key
path Parameters
deliveryType
required
string (DeliveryType)
Enum: "aem_edge" "aem_cs" "other"
Example: aem_edge

The type of the delivery this site is using

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a single site by its Base URL

This endpoint is useful for retrieving a site when you only have its Base URL. The Base URL is a unique identifier for a site other than the Site ID. The base URL provided in the path must be base64 encoded. This is to allow for URLs with special characters to be used as path parameters.

Authorizations:
api_key
path Parameters
base64BaseUrl
required
string <base64url>

Base64-encoded base URL

Responses

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14",
  • "organizationId": "o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z",
  • "deliveryType": "aem_edge",
  • "goLiveDate": "2024-01-20T10:00:00Z",
  • "config": {
    },
  • "createdAt": "2023-12-15T09:30:00Z",
  • "updatedAt": "2024-01-19T11:20:00Z"
}

Retrieve all sites including their latest audit

This endpoint is useful for retrieving all sites including their latest audit. The latest audit is determined by the auditedAt property of the audit and included in the audits array of the site object.

Authorizations:
api_key
path Parameters
auditType
required
string (AuditType)
Enum: "404" "apex" "cwv" "lhs" "lhs-desktop" "lhs-mobile" "broken-backlinks" "canonical" "sitemap" "structured-data" "costs"
Example: cwv

The type of the audit

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a single site by its ID

This endpoint is useful for retrieving a site by its ID.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

Responses

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14",
  • "organizationId": "o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z",
  • "deliveryType": "aem_edge",
  • "goLiveDate": "2024-01-20T10:00:00Z",
  • "config": {
    },
  • "createdAt": "2023-12-15T09:30:00Z",
  • "updatedAt": "2024-01-19T11:20:00Z"
}

Update a site

This endpoint is useful for updating a site. Only the fields as per the request body schema will be updated. At least one field to update must be provided in the request body.

Authorizations:
admin_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

Request Body schema: application/json
required
deliveryType
string (DeliveryType)
Enum: "aem_edge" "aem_cs" "other"

The type of the delivery this site is using

goLiveDate
string or null <date-time> (DateTime)

The date and time when the site went live on AEM Edge

object (SiteConfig)

Optional. The configuration of the site

Responses

Request samples

Content type
application/json
{
  • "organizationId": "u7y6t5r4-e3w2-x1z0-z9y8-x7v6w5u4t3s2",
  • "deliveryType": "other",
  • "goLiveDate": "2024-01-20T10:00:00Z"
}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14",
  • "organizationId": "o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z",
  • "deliveryType": "aem_edge",
  • "goLiveDate": "2024-01-20T10:00:00Z",
  • "config": {
    },
  • "createdAt": "2023-12-15T09:30:00Z",
  • "updatedAt": "2024-01-19T11:20:00Z"
}

Delete a site

This endpoint is useful for deleting a site.

Authorizations:
admin_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

Responses

Update the configuration for an audit

This endpoint is useful for updating the configuration for an audit, for example to set which URLs to skip from the audit.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

auditType
required
string (AuditType)
Enum: "404" "apex" "cwv" "lhs" "lhs-desktop" "lhs-mobile" "broken-backlinks" "canonical" "sitemap" "structured-data" "costs"
Example: cwv

The type of the audit

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

Set of urls to exclude. If empty, will remove previously excluded URLs.

Responses

Request samples

Content type
application/json

Response samples

Content type
application/json
{}

Retrieve key events for a site

This endpoint returns key events for a site chronologically, starting from the most recent and descending to the least recent

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new key event for a site

The endpoint for creating new key events for a site

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

Request Body schema: application/json
required
name
required
string

Name of the key event

type
required
string (KeyEventType)
Enum: "performance" "seo" "content" "code" "third party" "experimentation" "network" "status change"
time
string <date-time> (DateTime)

Time of the key event occurred (optional). Current time is used when the field is missing

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "performance",
  • "time": "2024-01-19T14:20:30Z"
}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14",
  • "name": "Multiple 404s detected",
  • "type": "seo",
  • "time": "2023-12-15T09:30:00Z"
}

Delete a key event

The endpoint for deleting a key event

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

keyEventId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The key event ID in uuid format

Responses

Retrieve top pages for site

Not implemented yet. This endpoint is useful for retrieving top pages for a site. The top pages will be ordered in buckets by source and geo, and in descending order by traffic within these buckets.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve top pages for site by source

Not implemented yet. This endpoint is useful for retrieving top pages for a site. The top pages will be ordered in buckets by geo, and in descending order by traffic within these buckets.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

source
required
string
Value: "ahrefs"
Example: ahrefs

The source of the top pages

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve top pages for site by source and geo

Not implemented yet. This endpoint is useful for retrieving top pages for a site. The top pages will be ordered in descending order by traffic.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

source
required
string
Value: "ahrefs"
Example: ahrefs

The source of the top pages

geo
required
string
Example: au

The geo of the top pages

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieves all experiments for the site

This endpoint provide a list of experiments obtained from RUM data for the given site along with all the experiment details.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

Responses

Response samples

Content type
application/json
[
  • {
    }
]

audit

Audit operations

Retrieve all latest audits of a given type

This endpoint is useful for retrieving all audits of a given type. Optionally, the results can be sorted in ascending order by audited at date.

Authorizations:
api_key
path Parameters
auditType
required
string (AuditType)
Enum: "404" "apex" "cwv" "lhs" "lhs-desktop" "lhs-mobile" "broken-backlinks" "canonical" "sitemap" "structured-data" "costs"
Example: cwv

The type of the audit

query Parameters
ascending
boolean
Default: false

Whether to sort ascending or descending

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve all audits for a site

This endpoint is useful for retrieving all audits for a site. Optionally, the results can be sorted in ascending order by audited at date.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

query Parameters
ascending
boolean
Default: false

Whether to sort ascending or descending

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve all audits of a given type for a site

This endpoint is useful for retrieving all audits of a given type for a site. Optionally, the results can be sorted in ascending order by audited at date.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

auditType
required
string (AuditType)
Enum: "404" "apex" "cwv" "lhs" "lhs-desktop" "lhs-mobile" "broken-backlinks" "canonical" "sitemap" "structured-data" "costs"
Example: cwv

The type of the audit

query Parameters
ascending
boolean
Default: false

Whether to sort ascending or descending

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a single audit for a site

This endpoint is useful for retrieving a single audit for a site. The audit is identified by the auditedAt property of the audit and the audit type.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

auditType
required
string (AuditType)
Enum: "404" "apex" "cwv" "lhs" "lhs-desktop" "lhs-mobile" "broken-backlinks" "canonical" "sitemap" "structured-data" "costs"
Example: cwv

The type of the audit

auditedAt
required
string <date-time> (DateTime)
Example: 2024-01-19T14:20:30Z

The date and time of the audit in ISO 8601 format

Responses

Response samples

Content type
application/json
Example
{
  • "siteId": "a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14",
  • "auditedAt": "2024-01-20T12:00:00Z",
  • "expiresAt": "2024-07-20T12:00:00Z",
  • "auditType": "cwv",
  • "isError": false,
  • "deliveryType": "aem_edge",
  • "auditResult": {
    },
  • "previousAuditResult": {
    }
}

Retrieve all audits for a site

This endpoint is useful for retrieving all audits for a site. Optionally, the results can be sorted in ascending order by audited at date.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

query Parameters
ascending
boolean
Default: false

Whether to sort ascending or descending

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve the latest audit for a site

This endpoint is useful for retrieving the latest audit for a site. The latest audit is determined by the given audit type and will be included in the audits array of the site object.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

auditType
required
string (AuditType)
Enum: "404" "apex" "cwv" "lhs" "lhs-desktop" "lhs-mobile" "broken-backlinks" "canonical" "sitemap" "structured-data" "costs"
Example: cwv

The type of the audit

Responses

Response samples

Content type
application/json
Example
{
  • "siteId": "a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14",
  • "auditedAt": "2024-01-20T12:00:00Z",
  • "expiresAt": "2024-07-20T12:00:00Z",
  • "auditType": "cwv",
  • "isError": false,
  • "deliveryType": "aem_edge",
  • "auditResult": {
    },
  • "previousAuditResult": {
    }
}

Update the configuration for an audit

This endpoint is useful for updating the configuration for an audit, for example to set which URLs to skip from the audit.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

auditType
required
string (AuditType)
Enum: "404" "apex" "cwv" "lhs" "lhs-desktop" "lhs-mobile" "broken-backlinks" "canonical" "sitemap" "structured-data" "costs"
Example: cwv

The type of the audit

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

Set of urls to exclude. If empty, will remove previously excluded URLs.

Responses

Request samples

Content type
application/json

Response samples

Content type
application/json
{}

auth

Init authentication against 3rd party services

Authenticate with Google

This endpoint is used to authenticate with Google. The user will be redirected to the Google authentication flow.

path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

Responses

organization

Organization operations

Create a new organization

This endpoint is useful for creating a new organization.

Authorizations:
admin_key
Request Body schema: application/json
required
name
required
string

The name of the organization

imsOrgId
string (ImsOrganizationId)

Optional. The ID of the Adobe IMS organization

object (OrganizationConfig)

Optional. The configuration of the organization

Responses

Request samples

Content type
application/json
{
  • "name": "Example Organization",
  • "imsOrgId": "1234567890ABCDEF12345678@AdobeOrg",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z",
  • "name": "Example Organization",
  • "imsOrgId": "1234567890ABCDEF12345678@AdobeOrg",
  • "config": {
    },
  • "createdAt": "2023-12-15T09:30:00Z",
  • "updatedAt": "2024-01-19T11:20:00Z"
}

Retrieve all organizations

This endpoint is useful for retrieving all organizations.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a single organization by its ID

This endpoint is useful for retrieving an organization by its ID.

Authorizations:
api_key
path Parameters
organizationId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The organization ID in uuid format

Responses

Response samples

Content type
application/json
{
  • "id": "o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z",
  • "name": "Example Organization",
  • "imsOrgId": "1234567890ABCDEF12345678@AdobeOrg",
  • "config": {
    },
  • "createdAt": "2023-12-15T09:30:00Z",
  • "updatedAt": "2024-01-19T11:20:00Z"
}

Update an organization

This endpoint is useful for updating an organization. Only the fields as per the request body schema will be updated. At least one field to update must be provided in the request body.

Authorizations:
admin_key
path Parameters
organizationId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The organization ID in uuid format

Request Body schema: application/json
required
name
string

The name of the organization

imsOrgId
string (ImsOrganizationId)

Optional. The ID of the Adobe IMS organization

object (OrganizationConfig)

Optional. The configuration of the organization

Responses

Request samples

Content type
application/json
{
  • "name": "Example Organization",
  • "imsOrgId": "1234567890ABCDEF12345678@AdobeOrg",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z",
  • "name": "Example Organization",
  • "imsOrgId": "1234567890ABCDEF12345678@AdobeOrg",
  • "config": {
    },
  • "createdAt": "2023-12-15T09:30:00Z",
  • "updatedAt": "2024-01-19T11:20:00Z"
}

Delete an organization

This endpoint is useful for deleting an organization.

Authorizations:
admin_key
path Parameters
organizationId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The organization ID in uuid format

Responses

Retrieve all sites for an organization

This endpoint is useful for retrieving all sites for an organization.

Authorizations:
api_key
path Parameters
organizationId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The organization ID in uuid format

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve an organization by IMS Org ID

This endpoint is useful for retrieving an organization by IMS Org ID.

Authorizations:
api_key
path Parameters
imsOrgId
required
string (ImsOrganizationId)
Example: 1234567890ABCDEF12345678@AdobeOrg

An IMS organization ID

Responses

Response samples

Content type
application/json
{
  • "id": "o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z",
  • "name": "Example Organization",
  • "imsOrgId": "1234567890ABCDEF12345678@AdobeOrg",
  • "config": {
    },
  • "createdAt": "2023-12-15T09:30:00Z",
  • "updatedAt": "2024-01-19T11:20:00Z"
}

Retrieve Slack config for an organization by IMS Org ID

This endpoint is useful for retrieving the Slack config of an organization by IMS Org ID.

Authorizations:
api_key
path Parameters
imsOrgId
required
string (ImsOrganizationId)
Example: 1234567890ABCDEF12345678@AdobeOrg

An IMS organization ID

Responses

Response samples

Content type
application/json
{}

trigger

Trigger operations

Trigger an audit Deprecated

Warning: This API is deprecated, will be removed in future versions and should no longer be used or enhanced. Please use the Slack commands to trigger audits on-demand.

This endpoint is useful for triggering an audit. The audit will be run asynchronously and the response will be returned immediately.

The audit type is determined by the type parameter and must be one of the following:

  • 404
  • apex
  • cwv
  • lhs
  • lhs-desktop
  • lhs-mobile

The URL can be either a site ID or a base URL depending on the audit type.

Authorizations:
admin_key
query Parameters
url
required
string

The URL or Site ID to trigger the audit for

type
required
string (AuditType)
Enum: "404" "apex" "cwv" "lhs" "lhs-desktop" "lhs-mobile" "broken-backlinks" "canonical" "sitemap" "structured-data" "costs"
Example: type=cwv

The type of the audit to trigger

Responses

hooks

Webhooks for receiving events

Process fulfillment_completed events

This endpoint can be used to process an array of fulfillment_completed events, in the format produced by the Fulfillment Gateway and delivered by the Hoolihan pipeline. In particular, it is intended to be used to handle contract fulfillment events which involve an Edge Delivery Services fulfillable item "code".

Authorizations:
admin_key
Request Body schema: application/json
required
Array
id
required
string

The Hoolihan ID of the event

topic
required
string

The name of the Hoolihan topic that the event was received on

required
object (HoolihanEventValue)

Value of the event, which contains the message payload from the publishing system

partition
required
integer

The partition index that the event was received on

offset
required
integer

The offset of the event within the partition

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Process incoming site discovery hooks from CDN logs

This endpoint processes hooks that include x-forwarded-host header value from CDN logs Upon receiving the incoming webhook, it initiates a sequence of validation and sanitization procedures Once successful sanitization and validation are completed, it proceeds to send a Slack message notifying about the discovered domain

Authorizations:
api_key
path Parameters
hookSecret
required
string

Secret for the incoming webhook

Request Body schema: application/json
required
forwardedHost
string

value of x-forwarded-host header in the CDN log which trggered the domain discovery alert

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "forwardedHost": "blog.adobe.com, main--blog--adobecom.hlx.live, main--blog--adobecom.hlx.live, main--blog--adobecom.hlx-fastly.page"
}

Process incoming site discovery hooks from RUM logs

This endpoint processes hooks that include URL and domain information from RUM logs Upon receiving the incoming webhook, it initiates a sequence of validation and sanitization procedures Once successful sanitization and validation are completed, it proceeds to send a Slack message notifying about the discovered domain

Authorizations:
api_key
path Parameters
hookSecret
required
string

Secret for the incoming webhook

Request Body schema: application/json
required
url
string <url> (URL)

URL of the page which triggered the domain discovery alert

domain
string <domain> (Domain)

Domain of the page which triggered the domain discovery alert

property name*
additional property
any

Responses

Request samples

Content type
application/json
{}

Process setup completed events for site integration with analytics

Not implemented yet (will be via https://github.com/adobe/spacecat-api-service/issues/237). Process setup completed events for site integration with analytics.

Authorizations:
api_key
path Parameters
hookSecret
required
string

Secret for the incoming webhook

Request Body schema: application/json
required
required
object

The reporting details

required
object

The configuration for the data collection to embed on the site.

required
object

The data store details

object

The data schema details

required
object

The data mapping details

property name*
additional property
any

Responses

Request samples

Content type
application/json
Example
{}

slack

Slack channel management

Request invitation to an existing Slack channel of an organization

This endpoint can be used to invite a user to their organization's Slack channel by IMS user ID, which is read from the IMS API via the provided user access token. As a prerequisite, there must be an existing Spacecat organization and Slack channel for the given IMS org ID.

Authorizations:
admin_key
Request Body schema: application/json
required
imsOrgId
required
string (ImsOrganizationId)

The ID of the Adobe IMS organization

imsUserAccessToken
required
string (ImsUserAccessToken)

The IMS access token of the user to invite to the Slack channel

Responses

Request samples

Content type
application/json
{
  • "imsOrgId": "1234567890ABCDEF12345678@AdobeOrg",
  • "imsUserAccessToken": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6IjEyMzQ1IiwidHlwZSI6ImFjY2Vzc190b2tlbiIsImNsaWVudF9pZCI6ImV4YW1wbGVfYXBwIiwidXNlcl9pZCI6Ijk4NzY1NDc4OTBBQkNERUYxMjM0NTY3OEBhYmNkZWYxMjM0NTY3ODkuZSIsImFzIjoiaW1zLW5hMSIsImFhX2lkIjoiMTIzNDU2Nzg5MEFCQ0RFRjEyMzQ1Njc4QGFkb2JlLmNvbSIsImNyZWF0ZWRfYXQiOiIxNzEwMjQ3MDAwMDAwIn0.MRDpxgxSHDj4DmA182hPnjMAnKkly-VUJ_bXpQ-J8EQ"
}

api-keys

API key management

Create a new API key

Note: Not implemented yet.

This endpoint can be used to create a new API key with a set of scopes. The scoped API key will be returned in the response only once. The scoped API key can be used to authenticate the Spacecat APIs by including it in the x-api-key header.

Authorizations:
ims_key
header Parameters
x-gw-ims-org-id
string
Example: 1234567890ABCDEF12345678@AdobeOrg

IMS Organization Id of the client.

Request Body schema: application/json
name
required
string

The name of the API key

features
Array of strings

The features the API key is for

domains
required
Array of strings <domain> (Domain) [ items <domain > ]

The domains the API key is allowed to access

Responses

Request samples

Content type
application/json
{
  • "name": "Example API Key",
  • "features": [
    ],
  • "domains": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "name": "string",
  • "scopes": [
    ],
  • "createdAt": "2024-01-19T14:20:30Z",
  • "expiresAt": "2024-01-19T14:20:30Z",
  • "apiKey": "string"
}

Get all API keys owned by the given IMS client

Note: Not implemented yet.

This endpoint can be used to list all the API keys created by the client.

Authorizations:
ims_key
header Parameters
x-gw-ims-org-id
string
Example: 1234567890ABCDEF12345678@AdobeOrg

IMS Organization Id of the client.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete an API key

Note: Not implemented yet.

This endpoint can be used to delete an API key. The API key will be marked as deleted in the system and will no longer be valid for authentication. Only keys created by this IMS client can be deleted by it.

Authorizations:
ims_key
path Parameters
apiKeyId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The API key ID in uuid format

header Parameters
x-gw-ims-org-id
string
Example: 1234567890ABCDEF12345678@AdobeOrg

IMS Organization Id of the client.

Responses

import

APIs for importing content to Edge Delivery Services

Create a new import job

This endpoint can be used to start a new import job with a set of URLs, import API key, optional import.js mapping file, and optional custom headers. The import job will be processed asynchronously and the status of the job can be queried at the /tools/import/jobs/{jobId} endpoint. If there is no import queue available at the time of the request, a 503 Service Unavailable response will be returned. A single import job per client is permitted, otherwise a 429 Too Many Requests response will be returned.

Authorizations:
scoped_api_key
header Parameters
x-api-key
string

Client-specific import API key. This same key will be required to fetch the job status, and final .zip result.

Request Body schema: multipart/form-data
required
urls
required
Array of strings <url> (URL) [ items <url > ]

The URLs to import

object (ImportOptions)

Optional configuration params, defined as a JSON object

importScript
string <binary>

Optional import.js mapping file

customHeaders
object

Optional custom headers to send with each HTTP request

Responses

Response samples

Content type
application/json
{
  • "id": "12d6ac8e-d5e4-4788-90eb-b69e10e745fd",
  • "status": "RUNNING",
  • "startTime": "2024-01-19T14:20:30Z",
  • "urlCount": 25,
  • "successCount": 15,
  • "failedCount": 0
}

Query the status of an import job

This endpoint can be used to query the status of an import job, given its jobId.

Authorizations:
scoped_api_key
path Parameters
jobId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The job ID in uuid format

header Parameters
x-api-key
string

Client-specific import API key. Must match the key used to start the import job.

Responses

Response samples

Content type
application/json
{
  • "id": "12d6ac8e-d5e4-4788-90eb-b69e10e745fd",
  • "status": "RUNNING",
  • "startTime": "2024-01-19T14:20:30Z",
  • "urlCount": 25,
  • "successCount": 15,
  • "failedCount": 0
}

Delete an import job

This endpoint can be used to delete an import job, given its jobId. This operation will remove all import URL entities in addition to the import job itself. The imports.delete scope is required on the API key used to delete the import job, and only jobs created by the provided key can be deleted.

Authorizations:
scoped_api_key
path Parameters
jobId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The job ID in uuid format

header Parameters
x-api-key
string

Client-specific import API key. Must match the key used to start the import job, and include the imports.delete scope.

Responses

Query the progress of an import job

This endpoint can be used to query the progress of an import job, given its jobId.

Authorizations:
scoped_api_key
path Parameters
jobId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The job ID in uuid format

header Parameters
x-api-key
string

Client-specific import API key. Must match the key used to start the import job.

Responses

Response samples

Content type
application/json
{
  • "pending": 0,
  • "redirect": 0,
  • "running": 0,
  • "completed": 1,
  • "failed": 0
}

Request a pre-signed URL to download the result of an import job as a .zip archive

This endpoint can be used to download an archive of an import job, which will include all the resulting documents that were generated as part of the import. It will also include the import-report.xlsx file, which contains a summary of the import job.

Authorizations:
scoped_api_key
path Parameters
jobId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The job ID in uuid format

header Parameters
x-api-key
string

Client-specific import API key. Must match the key used to start the import job.

Responses

Response samples

Content type
application/json

Send a prompt to the import assistant

Note: Not implemented yet.

This endpoint can be used to send prompts to the import assistant. Each prompt will make use of AI to analyze a URL and return choices in response to the request.

Authorizations:
scoped_api_key
header Parameters
x-api-key
string

Client-specific import API key.

Request Body schema: application/json
url
required
string <url> (URL)

The URL to analyze

command
required
string

Assistant command to execute. Examples are 'start', 'cleanup', 'block', 'cells'.

prompt
string

Optional prompt to provide context for the analysis.

options
object

Optional configuration options required by the command.

Responses

Request samples

Content type
application/json
{}

Response samples

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

scrape

APIs for scraping web pages

Scrape a set of URLs

Warning: prototype endpoint. This endpoint allows you to scrape a set of URLs. The URLs are scraped in parallel and the results are returned in the same order as the input. The maximum number of URLs that can be scraped in a single request is 10.

Authorizations:
api_key
Request Body schema: application/json
urls
required
Array of strings <url> (URL) [ items <url > ]

The URLs to scrape. The URLs must be unique. Limit of 10 URLs per request.

Responses

Request samples

Content type
application/json

Response samples

Content type
application/json
{
  • "id": "12d6ac8e-d5e4-4788-90eb-b69e10e745fd",
  • "status": "COMPLETE",
  • "startTime": "2024-01-19T14:20:30Z",
  • "urlCount": 10,
  • "successCount": 9,
  • "failedCount": 1,
  • "results": []
}

configuration

Get all application configurations

Authorizations:
admin_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the latest application configuration

Authorizations:
admin_key

Responses

Response samples

Content type
application/json
{
  • "version": "string",
  • "jobs": [
    ],
  • "queues": {
    }
}

Get a specific version of the application configuration

Authorizations:
admin_key
path Parameters
version
required
string

Responses

Response samples

Content type
application/json
{
  • "version": "string",
  • "jobs": [
    ],
  • "queues": {
    }
}

key event

Retrieve key events for a site

This endpoint returns key events for a site chronologically, starting from the most recent and descending to the least recent

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new key event for a site

The endpoint for creating new key events for a site

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

Request Body schema: application/json
required
name
required
string

Name of the key event

type
required
string (KeyEventType)
Enum: "performance" "seo" "content" "code" "third party" "experimentation" "network" "status change"
time
string <date-time> (DateTime)

Time of the key event occurred (optional). Current time is used when the field is missing

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "performance",
  • "time": "2024-01-19T14:20:30Z"
}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14",
  • "name": "Multiple 404s detected",
  • "type": "seo",
  • "time": "2023-12-15T09:30:00Z"
}

Delete a key event

The endpoint for deleting a key event

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

keyEventId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The key event ID in uuid format

Responses

top pages

Retrieve top pages for site

Not implemented yet. This endpoint is useful for retrieving top pages for a site. The top pages will be ordered in buckets by source and geo, and in descending order by traffic within these buckets.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve top pages for site by source

Not implemented yet. This endpoint is useful for retrieving top pages for a site. The top pages will be ordered in buckets by geo, and in descending order by traffic within these buckets.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

source
required
string
Value: "ahrefs"
Example: ahrefs

The source of the top pages

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve top pages for site by source and geo

Not implemented yet. This endpoint is useful for retrieving top pages for a site. The top pages will be ordered in descending order by traffic.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

source
required
string
Value: "ahrefs"
Example: ahrefs

The source of the top pages

geo
required
string
Example: au

The geo of the top pages

Responses

Response samples

Content type
application/json
[
  • {
    }
]

experimental

Retrieve site metrics by source

This endpoint is useful for retrieving site metrics by source.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

source
required
string
Value: "ahrefs"
Example: ahrefs

The source of the top pages

metric
required
string
Value: "organic-traffic"
Example: organic-traffic

The name of the site metric

Responses

Response samples

Content type
application/json
[
  • {
    }
]

experiments

Retrieves all experiments for the site

This endpoint provide a list of experiments obtained from RUM data for the given site along with all the experiment details.

Authorizations:
api_key
path Parameters
siteId
required
string <uuid> (Id)
Example: 123e4567-e89b-12d3-a456-426614174000

The site ID in uuid format

Responses

Response samples

Content type
application/json
[
  • {
    }
]