SpaceCat logo
API docs by Redocly

SpaceCat API (1.102.0)

Download OpenAPI specification:

URL: https://github.com/adobe/spacecat-api-service License: Apache 2.0 Terms of Service

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: authorization

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
name
string

The name of the site

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",
  • "baseURL": "https://www.newsite.com",
  • "deliveryType": "aem_cs",
  • "name": "New Site"
}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14",
  • "organizationId": "o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z",
  • "baseURL": "https://example-site.com",
  • "name": "Example Site",
  • "deliveryType": "aem_edge",
  • "deliveryConfig": {},
  • "gitHubURL": "https://github.com/example/repo",
  • "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",
  • "baseURL": "https://example-site.com",
  • "name": "Example Site",
  • "deliveryType": "aem_edge",
  • "deliveryConfig": {},
  • "gitHubURL": "https://github.com/example/repo",
  • "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" "meta-tags" "broken-internal-links" "experimentation-opportunities"
Example: cwv

The type of the audit

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get latest site metrics

Retrieves the latest metrics for a specific site, including RUM (Real User Monitoring) data and organic traffic metrics. Returns zeroed values if no data is available or no RUM domain key is configured.

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
{
  • "pageViewsChange": 0,
  • "ctrChange": 0,
  • "projectedTrafficValue": 0
}

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",
  • "baseURL": "https://example-site.com",
  • "name": "Example Site",
  • "deliveryType": "aem_edge",
  • "deliveryConfig": {},
  • "gitHubURL": "https://github.com/example/repo",
  • "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
name
string

The name of the site

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

The type of the delivery this site is using

object (DeliveryConfig)

The delivery configuration of the site

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",
  • "name": "New Site",
  • "deliveryConfig": {},
  • "goLiveDate": "2024-01-20T10:00:00Z"
}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14",
  • "organizationId": "o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z",
  • "baseURL": "https://example-site.com",
  • "name": "Example Site",
  • "deliveryType": "aem_edge",
  • "deliveryConfig": {},
  • "gitHubURL": "https://github.com/example/repo",
  • "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" "meta-tags" "broken-internal-links" "experimentation-opportunities"
Example: cwv

The type of the audit

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

Set of URLs to exclude. If empty, previously excluded URLs will be removed

Array of objects

List of grouped URL patterns for categorization. Each entry should include a name and a URL pattern. If empty, previously grouped URLs will be removed

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Retrieves brand guidelines for a site

This endpoint provide the brand guidelines for the given site, if brandId is configured in the site configuration.

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": "urn:aaid:sc:VA6C2:e64205e7-13ca-51e8-8b83-8d8ef1ebf911",
  • "name": "Brand Foo Bar Example",
  • "imsOrgId": "1234567890ABCDEF12345678@AdobeOrg",
  • "createdAt": "2025-01-01T00:00:00Z",
  • "updatedAt": "2025-02-01T00:00:00Z",
  • "toneOfVoice": [
    ],
  • "coreValues": [
    ],
  • "guidelines": [
    ],
  • "restrictions": [
    ],
  • "additionalGuidelines": [
    ]
}

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
Enum: "ahrefs" "google"
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
Enum: "ahrefs" "google"
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
[
  • {
    }
]

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
Enum: "ahrefs" "google"
Example: ahrefs

The source of the top pages

metric
required
string
Enum: "organic-traffic" "organic-keywords"
Example: organic-traffic

The name of the site metric

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve page metrics by source

This endpoint is useful for retrieving page metrics by source. Currently only organic-keywords is supported as a metric and only for source ahrefs.

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
Enum: "ahrefs" "google"
Example: ahrefs

The source of the top pages

metric
required
string
Enum: "organic-traffic" "organic-keywords"
Example: organic-traffic

The name of the site metric

base64PageUrl
required
string <base64url>

Base64-encoded page URL

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" "meta-tags" "broken-internal-links" "experimentation-opportunities"
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" "meta-tags" "broken-internal-links" "experimentation-opportunities"
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" "meta-tags" "broken-internal-links" "experimentation-opportunities"
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
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "siteId": "456e4567-e89b-12d3-a456-426614174000",
  • "auditedAt": "2024-01-20T12:00:00Z",
  • "expiresAt": "2024-07-20T12:00:00Z",
  • "deliveryType": "aem_edge",
  • "fullAuditRef": "https://some-audit-system/full-report/1234",
  • "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" "meta-tags" "broken-internal-links" "experimentation-opportunities"
Example: cwv

The type of the audit

Responses

Response samples

Content type
application/json
Example
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "siteId": "456e4567-e89b-12d3-a456-426614174000",
  • "auditedAt": "2024-01-20T12:00:00Z",
  • "expiresAt": "2024-07-20T12:00:00Z",
  • "deliveryType": "aem_edge",
  • "fullAuditRef": "https://some-audit-system/full-report/1234",
  • "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" "meta-tags" "broken-internal-links" "experimentation-opportunities"
Example: cwv

The type of the audit

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

Set of URLs to exclude. If empty, previously excluded URLs will be removed

Array of objects

List of grouped URL patterns for categorization. Each entry should include a name and a URL pattern. If empty, previously grouped URLs will be removed

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

Check Google Search Console authentication status for a site

This endpoint is used to check if a site is connected to Google Search Console and verify authentication status.

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
{
  • "status": "Site is connected to Google Search Console"
}

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

Retrieves brands for an organization

This endpoint provide a list of brands the user have access to in the given organization.

Authorizations:
ims_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 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" "meta-tags" "broken-internal-links" "experimentation-opportunities"
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

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
required
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",
  • "deletedAt": "2024-01-19T14:20:30Z",
  • "revokedAt": "2024-01-19T14:20:30Z",
  • "apiKey": "string"
}

Get all API keys owned by the given IMS client

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

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 starts a new import job with a set of URLs, an import API key, an optional import.js mapping file, and optional custom headers. The job runs asynchronously, and its status can be queried at /tools/import/jobs/{jobId}.

If no import queue is available when the request is made, the endpoint returns a 503 Service Unavailable response. Each client is allowed only one active import job; additional requests will receive a 429 Too Many Requests response.

An import job may include a type, specifying the kind of job to create. The available options are 'doc' and 'xwalk', with 'doc' as the default if no type is provided.

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

Patch an import job

This endpoint can be used to stop an import job, given its jobId. This operation will prevent any further scraping of the import job URLs, and mark the job status as STOPPED. The results will not be saved to storage, allowing the user to start a new import immediately.

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.write scope.

Request Body schema: application/json
Array
op
string
Value: "replace"

The operation to perform on the import job

path
string

The path of the attribute to update

value
string
Value: "STOPPED"

The value to set

Responses

Request samples

Content type
application/json
[
  • {
    }
]

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
{}

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
object (ImportOptionsBase)

Optional configuration params, defined as a JSON object

customHeaders
object

Optional custom headers to send with each HTTP request

required
Array of objects

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": {
    }
}

Enable or disable audits for sites

Use this endpoint to enable or disable specific audit types for your sites.

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

The type of audit to be enabled or disabled.

enable
required
boolean

Set to true to enable the audit, or false to disable it.

Responses

Request samples

Content type
application/json
[]

Response samples

Content type
application/json
{
  • "status": 0,
  • "message": "string"
}

brands

Retrieves brands for an organization

This endpoint provide a list of brands the user have access to in the given organization.

Authorizations:
ims_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
[
  • {
    }
]

metrics

Get latest site metrics

Retrieves the latest metrics for a specific site, including RUM (Real User Monitoring) data and organic traffic metrics. Returns zeroed values if no data is available or no RUM domain key is configured.

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
{
  • "pageViewsChange": 0,
  • "ctrChange": 0,
  • "projectedTrafficValue": 0
}

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
Enum: "ahrefs" "google"
Example: ahrefs

The source of the top pages

metric
required
string
Enum: "organic-traffic" "organic-keywords"
Example: organic-traffic

The name of the site metric

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve page metrics by source

This endpoint is useful for retrieving page metrics by source. Currently only organic-keywords is supported as a metric and only for source ahrefs.

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
Enum: "ahrefs" "google"
Example: ahrefs

The source of the top pages

metric
required
string
Enum: "organic-traffic" "organic-keywords"
Example: organic-traffic

The name of the site metric

base64PageUrl
required
string <base64url>

Base64-encoded page URL

Responses

Response samples

Content type
application/json
[
  • {
    }
]

brand-guidelines

Retrieves brand guidelines for a site

This endpoint provide the brand guidelines for the given site, if brandId is configured in the site configuration.

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": "urn:aaid:sc:VA6C2:e64205e7-13ca-51e8-8b83-8d8ef1ebf911",
  • "name": "Brand Foo Bar Example",
  • "imsOrgId": "1234567890ABCDEF12345678@AdobeOrg",
  • "createdAt": "2025-01-01T00:00:00Z",
  • "updatedAt": "2025-02-01T00:00:00Z",
  • "toneOfVoice": [
    ],
  • "coreValues": [
    ],
  • "guidelines": [
    ],
  • "restrictions": [
    ],
  • "additionalGuidelines": [
    ]
}

opportunities

Retrieve a list of all opportunities for a specific site

Authorizations:
ims_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 opportunity for a specific site

Authorizations:
ims_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
auditId
required
string <uuid> (Id)

UUID of the audit result that triggered this opportunity

runbook
required
string <url>

URL to the runbook for this opportunity

type
required
string (OpportunityType)
Enum: "broken-backlinks" "broken-internal-links"

Type of opportunity

BrokenBacklinksOpportunityData (object) or BrokenInternalLinksOpportunityData (object)

Optional map of type-specific data relevant to this opportunity

origin
required
string (OpportunityOrigin)
Enum: "AUTOMATION" "ESS_OPS" "AI"

Origin of opportunity

title
required
string

Title of this opportunity

description
string

Description of this opportunity

BrokenBacklinksGuidance (object) or BrokenInternalLinksGuidance (object)

Guidance text specific to this opportunity

tags
Array of strings

Optional list of tags

Responses

Request samples

Content type
application/json

Example for a broken backlinks opportunity create

{
  • "auditId": "123e4567-e89b-12d3-a456-426614174000",
  • "runbook": "https://example.com/runbook/broken-backlinks",
  • "type": "broken-backlinks",
  • "origin": "AUTOMATION",
  • "title": "Authoritative domains are linking to invalid SecurBank URLs. This could impact your SEO.",
  • "description": "Provide the correct target URL that each of the broken backlinks should be redirected to.",
  • "guidance": {
    },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "siteId": "123e4567-e89b-12d3-a456-426614174000",
  • "auditId": "123e4567-e89b-12d3-a456-426614174000",
  • "runbook": "https://example.com/runbook/broken-backlinks",
  • "type": "broken-backlinks",
  • "data": { },
  • "origin": "ESS_OPS",
  • "title": "Authoritative domains are linking to invalid SecurBank URLs. This could impact your SEO.",
  • "description": "Provide the correct target URL that each of the broken backlinks should be redirected to.",
  • "status": "IN_PROGRESS",
  • "guidance": {
    },
  • "tags": [
    ],
  • "createdAt": "2024-01-19T14:20:30Z",
  • "updatedAt": "2024-01-19T14:20:30Z"
}

Retrieve opportunities for a specific site filtered by status

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

The site ID in uuid format

status
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve details of a specific opportunity

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

The site ID in uuid format

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

The opportunity ID in uuid format

Responses

Response samples

Content type
application/json

Example for a broken backlinks opportunity

{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "siteId": "a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14",
  • "auditId": "123e4567-e89b-12d3-a456-426614174000",
  • "runbook": "https://example.com/runbook/broken-backlinks",
  • "type": "broken-backlinks",
  • "origin": "AUTOMATION",
  • "title": "Authoritative domains are linking to invalid SecurBank URLs. This could impact your SEO.",
  • "description": "Provide the correct target URL that each of the broken backlinks should be redirected to.",
  • "status": "IN_PROGRESS",
  • "guidance": {
    },
  • "tags": [
    ],
  • "createdAt": "2024-01-20T12:00:00Z",
  • "updatedAt": "2024-07-23T12:00:00Z"
}

Update specific attributes of an existing opportunity

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

The site ID in uuid format

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

The opportunity ID in uuid format

Request Body schema: application/json
required
runbook
string <url>

URL to the runbook for this opportunity

BrokenBacklinksOpportunityData (object) or BrokenInternalLinksOpportunityData (object)

Optional map of type-specific data relevant to this opportunity

title
string

Title of this opportunity

description
string

Description of this opportunity

status
string (OpportunityStatus)
Enum: "NEW" "IN_PROGRESS" "IGNORED" "RESOLVED"

Status of this opportunity

BrokenBacklinksGuidance (object) or BrokenInternalLinksGuidance (object)

Guidance text specific to this opportunity

tags
Array of strings

Optional list of tags

Responses

Request samples

Content type
application/json

Example for a broken backlinks opportunity update

{}

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "siteId": "123e4567-e89b-12d3-a456-426614174000",
  • "auditId": "123e4567-e89b-12d3-a456-426614174000",
  • "runbook": "https://example.com/runbook/broken-backlinks",
  • "type": "broken-backlinks",
  • "data": { },
  • "origin": "ESS_OPS",
  • "title": "Authoritative domains are linking to invalid SecurBank URLs. This could impact your SEO.",
  • "description": "Provide the correct target URL that each of the broken backlinks should be redirected to.",
  • "status": "IN_PROGRESS",
  • "guidance": {
    },
  • "tags": [
    ],
  • "createdAt": "2024-01-19T14:20:30Z",
  • "updatedAt": "2024-01-19T14:20:30Z"
}

Delete an opportunity and associated suggestions + fixes

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

The site ID in uuid format

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

The opportunity ID in uuid format

Responses

opportunity-suggestions

Retrieve a list of all suggestions for a specific opportunity

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

The site ID in uuid format

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

The opportunity ID in uuid format

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create and add a list of one or more suggestions to an opportunity in one transaction

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

The site ID in uuid format

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

The opportunity ID in uuid format

Request Body schema: application/json
required
Array
type
required
string (SuggestionType)
Enum: "REDIRECT_UPDATE" "EXPERIMENT" "CONTENT_UPDATE" "METADATA_UPDATE"

Type of suggestion:

  • REDIRECT_UPDATE: Add or update a redirect as suggested
  • EXPERIMENT: Run the experiment with the given suggestions
  • CONTENT_UPDATE: Update the content to the suggested
  • METADATA_UPDATE: Update the metadata to the suggested
rank
required
number

Type-specific numeric rank value (e.g., "domainTraffic" for a broken-backlink) helps sorting

required
BrokenBacklinksRedirectData (object) or BrokenInternalLinksSuggestionData (object)

Map containing type-specific details of what fix is suggested

BrokenBacklinksKpiDeltas (object) or BrokenInternalLinksKpiDeltas (object)

Map containing metrics estimated to experience lifts or losses due to the issue

Responses

Request samples

Content type
application/json

Example for a broken backlinks suggestion create list

[]

Response samples

Content type
application/json

Example for a broken backlinks suggestion create list response

{}

Retrieve suggestions for a specific opportunity filtered by status

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

The site ID in uuid format

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

The opportunity ID in uuid format

status
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve details of a specific suggestion

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

The site ID in uuid format

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

The opportunity ID in uuid format

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

The suggestion ID in uuid format

Responses

Response samples

Content type
application/json

Example for a broken backlinks suggestion

{}

Update specific attributes of an existing suggestion

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

The site ID in uuid format

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

The opportunity ID in uuid format

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

The suggestion ID in uuid format

Request Body schema: application/json
required
rank
number

Type-specific numeric rank value (e.g., "domainTraffic" for a broken-backlink) helps sorting

BrokenBacklinksRedirectData (object) or BrokenInternalLinksSuggestionData (object)

Map containing type-specific details of what fix is suggested

BrokenBacklinksKpiDeltas (object) or BrokenInternalLinksKpiDeltas (object)

Map containing metrics estimated to experience lifts or losses due to the issue

Responses

Request samples

Content type
application/json

Example for a broken backlinks suggestion update

{}

Response samples

Content type
application/json

Example for a broken backlinks suggestion

{}

Delete a suggestion

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

The site ID in uuid format

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

The opportunity ID in uuid format

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

The suggestion ID in uuid format

Responses

Update the status of one or multiple suggestions in one transaction

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

The site ID in uuid format

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

The opportunity ID in uuid format

Request Body schema: application/json
required
Array
id
required
string <uuid> (Id)

UUID of this suggestion

status
required
string (SuggestionStatus)
Enum: "NEW" "APPROVED" "SKIPPED" "FIXED" "ERROR"

Status of this suggestion; status reflects overall fix execution, flagged here for optimization

Responses

Request samples

Content type
application/json

Example for broken backlinks suggestions status update

[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json

Example for broken backlinks suggestions status update response

{
  • "suggestions": [
    ],
  • "metadata": {
    }
}

Trigger autofix for one or multiple suggestions, and set them to 'In Progress'

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

The site ID in uuid format

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

The opportunity ID in uuid format

Request Body schema: application/json
required
suggestionIds
required
Array of strings <uuid> (Id) [ items <uuid > ]

Responses

Request samples

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

Response samples

Content type
application/json

Example for broken backlinks suggestions status update response

{
  • "suggestions": [
    ],
  • "metadata": {
    }
}

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
Enum: "ahrefs" "google"
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
Enum: "ahrefs" "google"
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
[
  • {
    }
]

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
[
  • {
    }
]