{
"openapi": "3.1.0",
"info": {
"title": "Silktide API",
"version": "1.0.0",
"description": "Build on Silktide with its REST API: add and test websites, read accessibility, content and SEO results, and manage your account from your own code.\n\nGuides and examples: https://developers.silktide.com"
},
"servers": [
{
"url": "https://api.eu.silktide.com",
"description": "EU region. Use the region your account is in."
},
{
"url": "https://api.us.silktide.com",
"description": "US region. Use the region your account is in."
},
{
"url": "https://api.au.silktide.com",
"description": "Australia region. Use the region your account is in."
}
],
"security": [
{
"apiKey": []
}
],
"paths": {
"/v1/balances": {
"get": {
"operationId": "getAccountBalance",
"summary": "Get what the account can still add",
"description": "Returns what the account can still add under its plan: websites, pages, documents and the other allowances. Call it before creating a website to know how many pages and documents you can give it.\n\nA value of `-1` means unlimited. Most fields count what is left, not the total: `maxPages` is the most pages a new website could be given now, while `maxPagesLimit` is the account's whole allowance and `maxPagesRestOfAccount` is what its websites already hold.\n\nTo see what one existing website could be given, use [Get what a website can be given](/v1/platform/balances/get-website-balance).",
"tags": [
"Platform: Balances"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/platform/balances/get-account-balance"
},
"parameters": [],
"responses": {
"200": {
"description": "Get what the account can still add",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"newWebsites": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "How many more websites the account can create."
},
"maxPages": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "The most pages a new website could be given now."
},
"maxDocuments": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "The most documents (PDFs) a new website could be given now."
},
"maxAuthentications": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "How many more website logins (authentications) the account can add."
},
"maxSearchEngineKeywords": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "How many more search engine keywords the account can track."
},
"maxUptimeMonitors": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "How many more uptime monitors the account can add."
},
"maxUserFlows": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "How many more user flows the account can add."
},
"maxExperiences": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "How many more experiences the account can add."
},
"maxPagesLimit": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "The account's whole page allowance, across every website."
},
"maxDocumentsLimit": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "The account's whole document (PDF) allowance, across every website."
},
"governanceAiOptimizersLimit": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "How many Governance AI optimizers the account's plan includes. `0` means none."
},
"governanceAiOptimizersUsed": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "How many Governance AI optimizers are in use, including any still held after a website gave one up."
},
"maxPagesRestOfAccount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Pages already allocated to the account's websites."
},
"maxDocumentsRestOfAccount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Documents already allocated to the account's websites."
}
},
"required": [
"newWebsites",
"maxPages",
"maxDocuments",
"maxAuthentications",
"maxSearchEngineKeywords",
"maxUptimeMonitors",
"maxUserFlows",
"maxExperiences",
"maxPagesLimit",
"maxDocumentsLimit",
"governanceAiOptimizersLimit",
"governanceAiOptimizersUsed",
"maxPagesRestOfAccount",
"maxDocumentsRestOfAccount"
],
"additionalProperties": false
},
"example": {
"newWebsites": 95,
"maxPages": 99810,
"maxDocuments": 99830,
"maxAuthentications": 100,
"maxSearchEngineKeywords": 1000,
"maxUptimeMonitors": 95,
"maxUserFlows": 100,
"maxExperiences": 20,
"maxPagesLimit": 100000,
"maxDocumentsLimit": 100000,
"maxPagesRestOfAccount": 190,
"maxDocumentsRestOfAccount": 170,
"governanceAiOptimizersLimit": 3,
"governanceAiOptimizersUsed": 1
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/balances/{websiteId}": {
"get": {
"operationId": "getWebsiteBalance",
"summary": "Get what a website can be given",
"description": "Returns what one existing website can be given: the most pages and documents you can set when you [update it](/v1/governance/websites/update-website), and the account's other allowances.\n\n`maxPages` and `maxDocuments` are never lower than what the website already holds, even when the account is over its allowance, so keeping a website's current allocation always saves. `-1` means unlimited.",
"tags": [
"Platform: Balances"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/platform/balances/get-website-balance"
},
"parameters": [
{
"name": "websiteId",
"in": "path",
"required": true,
"description": "The website.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "Get what a website can be given",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"maxPages": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "The most pages this website can be given. Never less than it holds now."
},
"maxDocuments": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "The most documents (PDFs) this website can be given. Never less than it holds now."
},
"maxAuthentications": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "How many more website logins (authentications) the account can add."
},
"maxSearchEngineKeywords": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "How many more search engine keywords the account can track."
},
"maxUptimeMonitors": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "How many more uptime monitors the account can add."
},
"maxUserFlows": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "How many more user flows the account can add."
},
"maxExperiences": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "How many more experiences the account can add."
},
"maxPagesLimit": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "The account's whole page allowance, across every website."
},
"maxDocumentsLimit": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "The account's whole document (PDF) allowance, across every website."
},
"governanceAiOptimizersLimit": {
"type": "integer",
"minimum": -1,
"maximum": 9007199254740991,
"description": "How many Governance AI optimizers the account's plan includes. `0` means none."
},
"governanceAiOptimizersUsed": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "How many Governance AI optimizers are in use, including any still held after a website gave one up."
},
"maxPagesRestOfAccount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Pages allocated to the account's other websites."
},
"maxDocumentsRestOfAccount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Documents allocated to the account's other websites."
}
},
"required": [
"maxPages",
"maxDocuments",
"maxAuthentications",
"maxSearchEngineKeywords",
"maxUptimeMonitors",
"maxUserFlows",
"maxExperiences",
"maxPagesLimit",
"maxDocumentsLimit",
"governanceAiOptimizersLimit",
"governanceAiOptimizersUsed",
"maxPagesRestOfAccount",
"maxDocumentsRestOfAccount"
],
"additionalProperties": false
},
"example": {
"maxPages": 1000,
"maxDocuments": 500,
"maxAuthentications": 100,
"maxSearchEngineKeywords": 1000,
"maxUptimeMonitors": 95,
"maxUserFlows": 100,
"maxExperiences": 20,
"maxPagesLimit": 100000,
"maxDocumentsLimit": 100000,
"maxPagesRestOfAccount": 180,
"maxDocumentsRestOfAccount": 160,
"governanceAiOptimizersLimit": 3,
"governanceAiOptimizersUsed": 1
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: Nothing with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/roles": {
"get": {
"operationId": "listRoles",
"summary": "List the account's roles",
"description": "Returns the account's roles. Every account starts with two: Everyone\n(`roleId` `1`), which every user is in and which cannot be deleted, and\nAccount administrators (`2`). The roles the account made follow them.\n\n`sort` is not the same as in results queries: write `displayName:desc`, not\n`displayName:d`. Anything after the colon other than `desc` sorts ascending.",
"tags": [
"Platform: Roles"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/platform/roles/list-roles"
},
"parameters": [
{
"name": "search",
"in": "query",
"required": false,
"description": "Only roles whose name or description contains this text, ignoring case.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "A field to sort by, such as `displayName`, then `:desc` for descending: `displayName:desc`. Left out, oldest first.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "At most this many roles.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "perPage",
"in": "query",
"required": false,
"description": "Return a page of this many roles. Left out, every role.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "With `perPage`, the page to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "List the account's roles",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"roles": {
"type": "array",
"items": {
"type": "object",
"properties": {
"roleId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The role's id. Its assignee id is `g:` and this, such as `g:2`."
},
"displayName": {
"type": "string",
"description": "The role's name."
},
"icon": {
"type": "string",
"description": "A [Font Awesome](https://fontawesome.com/icons) icon class, such as `fas fa-globe`. Empty when it has none."
},
"colorScheme": {
"type": "string",
"enum": [
"",
"sky",
"emerald",
"amber",
"rose",
"orange",
"violet",
"indigo",
"cyan",
"fuchsia",
"slate"
],
"description": "The color Silktide shows the role in. Empty when it has none."
},
"description": {
"type": "string",
"description": "What the role is for. Can be empty."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When the role was created."
}
},
"required": [
"roleId",
"displayName",
"icon",
"colorScheme",
"description",
"created"
],
"additionalProperties": false
},
"description": "The roles. Never empty: every account has Everyone."
}
},
"required": [
"roles"
],
"additionalProperties": false
},
"example": {
"roles": [
{
"roleId": 1,
"displayName": "Everyone",
"icon": "fas fa-globe",
"colorScheme": "sky",
"description": "All users in this Account.",
"created": 1790216526
},
{
"roleId": 2,
"displayName": "Account administrators",
"icon": "fas fa-crown",
"colorScheme": "amber",
"description": "People with total control of this account",
"created": 1790216526
},
{
"roleId": 3,
"displayName": "Web editors",
"icon": "fas fa-pen",
"colorScheme": "violet",
"description": "Fix issues on the public websites",
"created": 1791431526
}
]
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
},
"post": {
"operationId": "createRole",
"summary": "Create a role",
"description": "Creates a role, with no permissions and no members. Give it both in Silktide.\n\nOnly `displayName` is required. Older documentation said `description` was\nrequired too; it is not.\n\nThe API cannot change or delete a role once it is made, so check the name\nbefore you send it. A name longer than 80 characters is not refused: it is\ncut short.",
"tags": [
"Platform: Roles"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/platform/roles/create-role"
},
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"role": {
"type": "object",
"properties": {
"displayName": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "The role's name. Spaces at either end are removed, and a longer name is cut to 80 characters."
},
"description": {
"description": "What the role is for. Defaults to empty.",
"type": "string",
"maxLength": 200
},
"icon": {
"description": "A [Font Awesome](https://fontawesome.com/icons) icon class, such as `fas fa-users`. Defaults to none.",
"type": "string",
"maxLength": 80
},
"colorScheme": {
"description": "The color Silktide shows the role in. Defaults to none, and so does a value not listed here.",
"type": "string",
"enum": [
"sky",
"emerald",
"amber",
"rose",
"orange",
"violet",
"indigo",
"cyan",
"fuchsia",
"slate"
]
}
},
"required": [
"displayName"
],
"description": "The new role."
}
},
"required": [
"role"
]
},
"example": {
"role": {
"displayName": "Web editors",
"description": "Fix issues on the public websites",
"icon": "fas fa-pen",
"colorScheme": "violet"
}
}
}
}
},
"responses": {
"200": {
"description": "Create a role",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"role": {
"type": "object",
"properties": {
"roleId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The role's id. Its assignee id is `g:` and this, such as `g:2`."
},
"displayName": {
"type": "string",
"description": "The role's name."
},
"icon": {
"type": "string",
"description": "A [Font Awesome](https://fontawesome.com/icons) icon class, such as `fas fa-globe`. Empty when it has none."
},
"colorScheme": {
"type": "string",
"enum": [
"",
"sky",
"emerald",
"amber",
"rose",
"orange",
"violet",
"indigo",
"cyan",
"fuchsia",
"slate"
],
"description": "The color Silktide shows the role in. Empty when it has none."
},
"description": {
"type": "string",
"description": "What the role is for. Can be empty."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When the role was created."
}
},
"required": [
"roleId",
"displayName",
"icon",
"colorScheme",
"description",
"created"
],
"additionalProperties": false,
"description": "The role."
}
},
"required": [
"role"
],
"additionalProperties": false
},
"example": {
"role": {
"roleId": 3,
"displayName": "Web editors",
"icon": "fas fa-pen",
"colorScheme": "violet",
"description": "Fix issues on the public websites",
"created": 1791431526
}
}
}
}
},
"400": {
"description": "`OutOfBounds`: `role.displayName` is missing or empty.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot admin users and groups.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "Can admin users and groups",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/assignees": {
"get": {
"operationId": "listAssignees",
"summary": "List the account's roles and users as assignees",
"description": "Returns everyone and every role in the account that can be given something,\nsuch as a report to receive or a check to fix, keyed by assignee id. Use these\nids wherever an operation asks for `assigneeIds`.\n\nThe answer is an object, not a list: read it by key, or take its values. Roles\ncome first, Everyone leading, then users, each in name order.\n\nRoles and users have different fields. Both have `assigneeId`, `assigneeType`\nand `displayName`; read the rest by `assigneeType`. Roles are still called\ngroups here (`group`, `groupId`, ids starting `g:`): that is the name roles\nhad before.\n\nOlder documentation listed eight assignee types. This list only ever holds\n`group` and `user`.",
"tags": [
"Platform: Assignees"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/platform/assignees/list-assignees"
},
"parameters": [],
"responses": {
"200": {
"description": "List the account's roles and users as assignees",
"content": {
"application/json": {
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"assigneeId": {
"type": "string",
"pattern": "^[gu]:",
"description": "The assignee's id, the same as its key: `g:` and a role id, or `u:` and a user id."
},
"assigneeType": {
"type": "string",
"enum": [
"group",
"user"
],
"description": "`group` for a role, `user` for a person."
},
"displayName": {
"type": "string",
"description": "The name to show: a role's name, or the name a person chose to be shown by."
},
"groupId": {
"description": "The role's id, its `roleId`. Roles only.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"name": {
"description": "The role's name again, as older integrations read it. Roles only.",
"type": "string"
},
"description": {
"description": "What the role is for. Can be empty. Roles only.",
"type": "string"
},
"icon": {
"description": "A Font Awesome icon class, such as `fas fa-globe`. Can be empty. Roles only.",
"type": "string"
},
"colorScheme": {
"description": "The color Silktide shows the role in. Empty when it has none. Roles only.",
"type": "string",
"enum": [
"",
"sky",
"emerald",
"amber",
"rose",
"orange",
"violet",
"indigo",
"cyan",
"fuchsia",
"slate"
]
},
"userId": {
"description": "The user's id: their region, a hyphen and a number, such as `eu-12`. Users only.",
"type": "string"
},
"fullName": {
"description": "The person's full name. Users only.",
"type": "string"
},
"email": {
"description": "Their email address. Users only.",
"type": "string"
},
"position": {
"description": "Their job title. Empty when they have not given one. Users only.",
"type": "string"
},
"thumbnailUrl": {
"description": "A URL of their picture. Empty when they have none. Users only.",
"type": "string"
}
},
"required": [
"assigneeId",
"assigneeType",
"displayName"
],
"additionalProperties": false
},
"description": "Every role, then every user, in the account, keyed by assignee id."
},
"example": {
"g:1": {
"groupId": 1,
"displayName": "Everyone",
"description": "All users in this Account.",
"icon": "fas fa-globe",
"colorScheme": "sky",
"assigneeId": "g:1",
"assigneeType": "group",
"name": "Everyone"
},
"g:2": {
"groupId": 2,
"displayName": "Account administrators",
"description": "People with total control of this account",
"icon": "fas fa-crown",
"colorScheme": "amber",
"assigneeId": "g:2",
"assigneeType": "group",
"name": "Account administrators"
},
"u:eu-12": {
"userId": "eu-12",
"fullName": "Jordan Rivera",
"displayName": "Jordan",
"email": "jordan.rivera@example.com",
"position": "Web editor",
"thumbnailUrl": "https://example.com/people/jordan.png",
"assigneeId": "u:eu-12",
"assigneeType": "user"
},
"u:eu-15": {
"userId": "eu-15",
"fullName": "Sam Okafor",
"displayName": "Sam Okafor",
"email": "sam.okafor@example.com",
"position": "",
"thumbnailUrl": "",
"assigneeId": "u:eu-15",
"assigneeType": "user"
}
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/tags": {
"get": {
"operationId": "listTags",
"summary": "List the account's tags",
"description": "Returns every tag in the account, sorted by label, with how many things each\none is on.\n\nThe list holds every type of tag together: tags for websites and sections\n(`section`), for documents (`document`) and for tasks (`task`). Older\ndocumentation said only `section` existed. Filter by `entityType` when you\nwant one kind, for example the tags you can put on a website with `tagIds` in\n[Update a website](/v1/governance/websites/update-website).",
"tags": [
"Platform: Tags"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/platform/tags/list-tags"
},
"parameters": [],
"responses": {
"200": {
"description": "List the account's tags",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tagId": {
"type": "string",
"minLength": 1,
"maxLength": 32,
"description": "The tag's id. Use it in `tagIds`, and in the path of Update a tag and Delete a tag."
},
"entityType": {
"type": "string",
"enum": [
"section",
"document",
"task"
],
"description": "What the tag is for: `section` for websites and their sections, `document` for documents, `task` for tasks. Each type has its own tags."
},
"label": {
"type": "string",
"description": "The tag's name, as people see it."
},
"color": {
"type": "string",
"description": "Its color, as a hex code such as `#ED4B4B`."
},
"tagGroup": {
"type": "string",
"description": "The group it is shown in, such as `Region`. Empty when it has none."
},
"numUses": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "How many things the tag is on now: sections, documents or tasks, by its `entityType`."
}
},
"required": [
"tagId",
"entityType",
"label",
"color",
"tagGroup",
"numUses"
],
"additionalProperties": false
},
"description": "Every tag in the account, of every type, by label. Empty when there are none."
}
},
"required": [
"tags"
],
"additionalProperties": false
},
"example": {
"tags": [
{
"tagId": "competitor",
"label": "Competitor",
"color": "#ED4B4B",
"entityType": "section",
"tagGroup": "",
"numUses": 2
},
{
"tagId": "pre-production",
"label": "Pre-production",
"color": "#4256D6",
"entityType": "section",
"tagGroup": "",
"numUses": 0
},
{
"tagId": "seo",
"label": "SEO",
"color": "#3CA87C",
"entityType": "task",
"tagGroup": "Discipline",
"numUses": 5
}
]
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
},
"post": {
"operationId": "createTag",
"summary": "Create one or more tags",
"description": "Creates tags. Send one as `tag` and get it back as `tag`, or send a list as\n`tags` and get a list back. Older documentation only showed `tags`.\n\nA label must be unique among tags of the same `entityType`, so \"Competitor\"\ncan be both a website tag and a task label. A `tagId` must be unique across\nthe whole account. To put website tags on a website, send their ids as\n`tagIds` to [Update a website](/v1/governance/websites/update-website).\n\nA mistake fails with status `400` and type `InvalidRequest`, and\n`properties.field` names the field: a `tagId` or label already in use, a\nmissing `entityType`, or a `color` that is not a hex code such as `#4256D6`.\nWhen you send `tags`, Silktide checks them all, against the account and\nagainst each other, before it creates any. If one is refused,\n`properties.index` says which, counting from `0`, and none are created.",
"tags": [
"Platform: Tags"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/platform/tags/create-tag"
},
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tag": {
"description": "One tag to create. Send this or `tags`.",
"type": "object",
"properties": {
"tagId": {
"description": "An id of your own, unique in the account. Left out, Silktide makes one from the label, such as `pre-production`. Up to 32 letters, digits, hyphens or underscores; keep to lowercase, as it goes in URLs.",
"type": "string",
"minLength": 1,
"maxLength": 32
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 127,
"description": "The tag's name, as people see it."
},
"entityType": {
"type": "string",
"enum": [
"section",
"document",
"task"
],
"description": "What the tag is for: `section` for websites and their sections, `document` for documents, `task` for tasks. Each type has its own tags."
},
"color": {
"description": "Its color, as a hex code such as `#4256D6`. Left out, Silktide picks one.",
"type": "string",
"maxLength": 32
},
"tagGroup": {
"type": "string",
"maxLength": 64,
"description": "A group to show it in, such as `Region`. Tags with the same group are shown together. Empty for none."
}
},
"required": [
"label",
"entityType"
]
},
"tags": {
"description": "Several tags to create, in order. Send this or `tag`; when both are sent, only `tag` is created.",
"type": "array",
"items": {
"type": "object",
"properties": {
"tagId": {
"description": "An id of your own, unique in the account. Left out, Silktide makes one from the label, such as `pre-production`. Up to 32 letters, digits, hyphens or underscores; keep to lowercase, as it goes in URLs.",
"type": "string",
"minLength": 1,
"maxLength": 32
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 127,
"description": "The tag's name, as people see it."
},
"entityType": {
"type": "string",
"enum": [
"section",
"document",
"task"
],
"description": "What the tag is for: `section` for websites and their sections, `document` for documents, `task` for tasks. Each type has its own tags."
},
"color": {
"description": "Its color, as a hex code such as `#4256D6`. Left out, Silktide picks one.",
"type": "string",
"maxLength": 32
},
"tagGroup": {
"type": "string",
"maxLength": 64,
"description": "A group to show it in, such as `Region`. Tags with the same group are shown together. Empty for none."
}
},
"required": [
"label",
"entityType"
]
}
}
}
},
"example": {
"tag": {
"label": "Pre-production",
"entityType": "section"
}
}
}
}
},
"responses": {
"200": {
"description": "Create one or more tags",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tag": {
"description": "The tag, when you sent `tag`.",
"type": "object",
"properties": {
"tagId": {
"type": "string",
"minLength": 1,
"maxLength": 32,
"description": "The tag's id. Use it in `tagIds`, and in the path of Update a tag and Delete a tag."
},
"entityType": {
"type": "string",
"enum": [
"section",
"document",
"task"
],
"description": "What the tag is for: `section` for websites and their sections, `document` for documents, `task` for tasks. Each type has its own tags."
},
"label": {
"type": "string",
"description": "The tag's name, as people see it."
},
"color": {
"type": "string",
"description": "Its color, as a hex code such as `#ED4B4B`."
},
"tagGroup": {
"type": "string",
"description": "The group it is shown in, such as `Region`. Empty when it has none."
}
},
"required": [
"tagId",
"entityType",
"label",
"color",
"tagGroup"
],
"additionalProperties": false
},
"tags": {
"description": "The tags, in the order sent, when you sent `tags`. Empty when `tags` was empty or neither was sent.",
"type": "array",
"items": {
"type": "object",
"properties": {
"tagId": {
"type": "string",
"minLength": 1,
"maxLength": 32,
"description": "The tag's id. Use it in `tagIds`, and in the path of Update a tag and Delete a tag."
},
"entityType": {
"type": "string",
"enum": [
"section",
"document",
"task"
],
"description": "What the tag is for: `section` for websites and their sections, `document` for documents, `task` for tasks. Each type has its own tags."
},
"label": {
"type": "string",
"description": "The tag's name, as people see it."
},
"color": {
"type": "string",
"description": "Its color, as a hex code such as `#ED4B4B`."
},
"tagGroup": {
"type": "string",
"description": "The group it is shown in, such as `Region`. Empty when it has none."
}
},
"required": [
"tagId",
"entityType",
"label",
"color",
"tagGroup"
],
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"example": {
"tag": {
"tagId": "pre-production",
"entityType": "section",
"label": "Pre-production",
"color": "#D08736",
"tagGroup": ""
}
}
}
}
},
"400": {
"description": "`InvalidRequest`: A field is missing or not valid: `entityType` missing or not one of its values, `label` empty or longer than 127 characters, `tagId` not up to 32 letters, digits, hyphens or underscores, `color` not a hex code, or `tagGroup` longer than 64 characters. Also sent when the `tagId` is already in use, a tag of the same `entityType` already has that label, two tags in `tags` clash, or `tag` is not an object. `properties.field` names the field, and for `tags` `properties.index` names the item, counting from `0`. Nothing is created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot admin the account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "Can admin this account",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/tags/{tagId}": {
"put": {
"operationId": "updateTag",
"summary": "Update a tag",
"description": "Changes a tag's label, color or group. Wherever the tag is used, it shows the\nchange at once.\n\nSend the changes inside a `tag` object. A body without one fails with status\n`400`. `tagId` and `entityType` are ignored if you send them: a tag keeps its\nid and type for good, so a renamed tag keeps its old id.\n\nLike [Create a tag](/v1/platform/tags/create-tag), it refuses a label that\nanother tag of the same type already has. Only the fields you change are\nchecked, so a tag saved before a rule existed can be resaved as it is.",
"tags": [
"Platform: Tags"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/platform/tags/update-tag"
},
"parameters": [
{
"name": "tagId",
"in": "path",
"required": true,
"description": "The tag.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 32
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tag": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 127,
"description": "The tag's name, as people see it."
},
"color": {
"type": "string",
"maxLength": 32,
"description": "Its color, as a hex code such as `#4256D6`, or empty for none."
},
"tagGroup": {
"type": "string",
"maxLength": 64,
"description": "A group to show it in, such as `Region`. Tags with the same group are shown together. Empty for none."
}
},
"description": "What to change. Leave out what should keep its value. `tagId` and `entityType` cannot change."
}
},
"required": [
"tag"
]
},
"example": {
"tag": {
"label": "Staging",
"tagGroup": "Environment"
}
}
}
}
},
"responses": {
"200": {
"description": "Update a tag",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tag": {
"type": "object",
"properties": {
"tagId": {
"type": "string",
"minLength": 1,
"maxLength": 32,
"description": "The tag's id. Use it in `tagIds`, and in the path of Update a tag and Delete a tag."
},
"entityType": {
"type": "string",
"enum": [
"section",
"document",
"task"
],
"description": "What the tag is for: `section` for websites and their sections, `document` for documents, `task` for tasks. Each type has its own tags."
},
"label": {
"type": "string",
"description": "The tag's name, as people see it."
},
"color": {
"type": "string",
"description": "Its color, as a hex code such as `#ED4B4B`."
},
"tagGroup": {
"type": "string",
"description": "The group it is shown in, such as `Region`. Empty when it has none."
}
},
"required": [
"tagId",
"entityType",
"label",
"color",
"tagGroup"
],
"additionalProperties": false,
"description": "The tag, as it is now."
}
},
"required": [
"tag"
],
"additionalProperties": false
},
"example": {
"tag": {
"tagId": "pre-production",
"entityType": "section",
"label": "Staging",
"color": "#D08736",
"tagGroup": "Environment"
}
}
}
}
},
"400": {
"description": "`InvalidRequest`: The body has no `tag` object, or a changed field is not valid: `label` empty, longer than 127 characters or already used by another tag of the same `entityType`, `color` not a hex code, or `tagGroup` longer than 64 characters. `properties.field` names the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot admin the account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No tag with that id exists in the account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "Can admin this account",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
},
"delete": {
"operationId": "deleteTag",
"summary": "Delete a tag and remove it everywhere",
"description": "Deletes a tag at once and takes it off everything it was on. It cannot be\nundone.\n\nThe response is an empty `201`. A tag's id is free to use again once it is\ndeleted.",
"tags": [
"Platform: Tags"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/platform/tags/delete-tag"
},
"parameters": [
{
"name": "tagId",
"in": "path",
"required": true,
"description": "The tag.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 32
}
}
],
"responses": {
"201": {
"description": "Delete a tag and remove it everywhere"
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot admin the account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No tag with that id exists in the account. Deleting a tag twice returns this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "Can admin this account",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results": {
"post": {
"operationId": "getSeveralResults",
"summary": "Get several results in one request",
"description": "Runs several [results](/v1/concepts/results) queries in one request, such as\na website's [scores](/v1/governance/scores/get-scores), the\n[trend of one score](/v1/governance/scores/get-score-trend), its\n[checks](/v1/governance/checks/get-checks) and\n[one check in detail](/v1/governance/checks/get-check). The answer is the\nsame as calling each one on its own.\n\n## Where each argument goes\n\nThe website goes at the top level, once: `websiteId` and `sectionId` (or\n`view`, for Analytics) apply to every query. Everything else a query takes,\nincluding `period`, goes in that query's `options`. A `period` at the top\nlevel is ignored, and so is a `websiteId` inside `options`.\n\nUse the argument names on each query's own page. Older documentation sent\n`score` to the score trend; the name is `scoreId`, and without it that entry\nfails.\n\n## One failure does not stop the rest\n\nThe request answers `200` even when some of its queries fail. A query that\nfails, because an option is missing or wrong, the query name is unknown, or no\nwebsite was sent, has an `error` in place of `result`, and the others still\nanswer. Check each entry for `error` before you read its `result`. Its\n`status` is what the query would have answered on its own; some mistakes in\nyour request, such as a missing option, come back as `500` there.\n\n`selector` is the name you sent, such as `score-trend`, not the path that a\nsingle query returns.\n\nA query for one edition of Silktide, such as the\n[Silktide 4 scores](/v1/governance/scores/get-scores), fails with\n`EditionNotAvailable` when the account does not have that edition. The others\nstill answer. See [Scores](/v1/concepts/scores).\n\nTwo mistakes fail the whole request: a website the API key cannot see\n(`404`), and a `results` that is missing, empty or not an object (`400`). An\nentry in `results` that is not an object, such as a bare query name, fails on\nits own with `InvalidRequest`.",
"tags": [
"Platform: Results"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/platform/results/get-several-results"
},
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"websiteId": {
"description": "The website every query is about. Governance queries need it.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"sectionId": {
"description": "A section of the website, for every query. Defaults to `0`, the whole website.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"view": {
"description": "For Analytics queries, the analytics view to read, or `all`. Send this or `websiteId`.",
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
},
"results": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"result": {
"type": "string",
"description": "The query: the part of its path after `/v1/results/`, such as `scores` or `score-trend`."
},
"options": {
"description": "Every other argument the query takes, such as `scoreId` or `period`, by the names on its own page. Left out, none.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
},
"required": [
"result"
]
},
"description": "The queries to run, each under a key of your choosing. The answer uses the same keys."
}
},
"required": [
"results"
],
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
}
},
"example": {
"websiteId": 2,
"sectionId": 0,
"results": {
"overall-trend": {
"result": "score-trend",
"options": {
"scoreId": "overall",
"period": "last-90-days"
}
},
"accessibility-trend": {
"result": "score-trend",
"options": {
"scoreId": "wcag-22-aa",
"period": "last-90-days"
}
},
"no-score": {
"result": "score-trend"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Get several results in one request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"result": {
"description": "The query's answer, the same as the `result` its own page describes. Absent when it failed.",
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
}
}
]
},
"selector": {
"description": "The query's id, as you sent it in `result`, such as `score-trend`. Absent when it failed.",
"type": "string"
},
"duration": {
"description": "Seconds Silktide took to answer it. Absent when it failed.",
"type": "number",
"minimum": 0
},
"error": {
"description": "Why the query failed, in place of `result`. Present only when it failed.",
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "What went wrong, such as `InvalidArgument` (a missing or bad option), `NotFound` (no query by that name), `InvalidRequest` (an entry that is not an object), `EditionNotAvailable` (a query for the edition of Silktide the account does not have), `InvalidContext` (no website) or `SelectorNotSpecified` (no `result`)."
},
"message": {
"type": "string",
"description": "A readable explanation. It can change; never match on it."
},
"properties": {
"description": "Details of the error, when it has any. An empty array when it has none. Absent for `SelectorNotSpecified`.",
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema2"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
]
},
"status": {
"description": "The HTTP status this failure would have had on its own. Absent for `SelectorNotSpecified`.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"type",
"message"
],
"additionalProperties": false
}
},
"additionalProperties": false
},
"description": "Each query's answer or failure, under the key you gave it."
}
},
"required": [
"results"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
},
"__schema1": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
}
]
},
"__schema2": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema2"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema2"
}
}
]
}
}
},
"example": {
"results": {
"overall-trend": {
"result": {
"scores": [
{
"time": 1790216531,
"score": 71.2
},
{
"time": 1790821331,
"score": 74.5
}
]
},
"selector": "score-trend",
"duration": 0.004
},
"accessibility-trend": {
"result": {
"scores": [
{
"time": 1790216531,
"score": 58.9
},
{
"time": 1790821331,
"score": 63
}
]
},
"selector": "score-trend",
"duration": 0.003
},
"no-score": {
"error": {
"type": "InvalidArgument",
"message": "An unspecified error occurred",
"properties": [],
"status": 500
}
}
}
}
}
}
},
"400": {
"description": "`InvalidRequest`: `results` is missing, empty or not an object.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No website or section with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/websites": {
"get": {
"operationId": "listWebsites",
"summary": "List websites and their sections",
"description": "Returns every website the API key's user can see, one entry per section. Each\nwebsite has a section `0`, which is the whole website, and any sections made\nwithin it have ids of their own. A `subsiteId` names one of them, as\n`{websiteId}-{sectionId}`.\n\nUse the `websiteId` with the other Websites operations, and the `subsiteId`\nwith results queries that take a section.\n\n`tags` is only sent when you ask for it with `includeTags=1`, and even then it\nis left out, rather than sent empty, for a section with no tags. Treat a\nmissing `tags` as none.",
"tags": [
"Governance: Websites"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/websites/list-websites"
},
"parameters": [
{
"name": "searchText",
"in": "query",
"required": false,
"description": "Only sections whose name or home page contains this.",
"schema": {
"type": "string"
}
},
{
"name": "tagIds",
"in": "query",
"required": false,
"description": "Only sections with at least one of these tags. Send as `tagIds[]=…`.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"name": "includeTags",
"in": "query",
"required": false,
"description": "`1` to include each section's tags. Any value other than `0` or empty counts as `1`.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
},
{
"name": "orderBy",
"in": "query",
"required": false,
"description": "The order. Defaults to `recentlyViewed`.",
"schema": {
"type": "string",
"enum": [
"name",
"recentlyViewed",
"recentlyCreated",
"recentlyTested",
"leastRecentlyTested"
]
}
}
],
"responses": {
"200": {
"description": "List websites and their sections",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"websites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"subsiteId": {
"type": "string",
"pattern": "^\\d+-\\d+$",
"description": "The website and section together, as `{websiteId}-{sectionId}`."
},
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The section within the website. `0` is the whole website."
},
"name": {
"type": "string",
"description": "The section's name. For section `0`, the website's name."
},
"homeUrl": {
"type": "string",
"description": "The section's home page. Can be empty."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When the section was created."
},
"websiteName": {
"type": "string",
"description": "The website's name."
},
"websiteStatus": {
"type": "string",
"enum": [
"installing",
"setup",
"live"
],
"description": "`installing` while Silktide creates it, `setup` while it is being configured before it goes live, `live` once it is tested."
},
"numPages": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Pages Silktide has found in the section."
},
"numDocuments": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Documents (PDFs) Silktide has found in the section."
},
"thumbnailUrl": {
"type": "string",
"description": "A small screenshot of the section. Empty until one exists."
},
"lastViewed": {
"description": "When the API key's user last viewed the section. `0` if never. Only when `orderBy` is `recentlyViewed`, the default; absent with any other order.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"tags": {
"description": "The section's tags. Only with `includeTags`, and absent when the section has none.",
"type": "array",
"items": {
"type": "object",
"properties": {
"tagId": {
"type": "string",
"description": "The tag's id."
},
"entityType": {
"type": "string",
"description": "What the tag is on. `section` for a website or section."
},
"entityId": {
"type": "string",
"description": "The `subsiteId` of the section it is on."
},
"label": {
"type": "string",
"description": "The tag's name."
},
"color": {
"type": "string",
"description": "Its color, as a hex code such as `#EBA52C`."
},
"tagGroup": {
"type": "string",
"description": "The group it belongs to. Empty when it has none."
}
},
"required": [
"tagId",
"entityType",
"entityId",
"label",
"color",
"tagGroup"
],
"additionalProperties": false
}
}
},
"required": [
"subsiteId",
"websiteId",
"sectionId",
"name",
"homeUrl",
"created",
"websiteName",
"websiteStatus",
"numPages",
"numDocuments",
"thumbnailUrl"
],
"additionalProperties": false
},
"description": "One entry per section the API key's user can see. Section `0` of each website is the whole website."
}
},
"required": [
"websites"
],
"additionalProperties": false
},
"example": {
"websites": [
{
"subsiteId": "2-0",
"websiteId": 2,
"sectionId": 0,
"name": "Example",
"homeUrl": "https://example.com/",
"created": 1790216529,
"websiteName": "Example",
"websiteStatus": "live",
"numPages": 812,
"numDocuments": 40,
"thumbnailUrl": "https://example-bucket.s3.amazonaws.com/websites/2/screenshots/desktop-thumb.webp",
"tags": [
{
"tagId": "marketing",
"entityType": "section",
"entityId": "2-0",
"label": "Marketing",
"color": "#EBA52C",
"tagGroup": ""
}
]
},
{
"subsiteId": "2-1",
"websiteId": 2,
"sectionId": 1,
"name": "Blog",
"homeUrl": "https://example.com/blog/",
"created": 1790216600,
"websiteName": "Example",
"websiteStatus": "live",
"numPages": 120,
"numDocuments": 0,
"thumbnailUrl": ""
}
]
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
},
"post": {
"operationId": "createWebsite",
"summary": "Create a website",
"description": "Creates a website and, unless you say otherwise, starts testing it straight\naway. The response is the new website, as\n[Get a website](/v1/governance/websites/get-website) returns it.\n\nThe pages and documents you give it come out of the account's balance, so\ncheck [Get the account's balance](/v1/platform/balances/get-account-balance)\nfirst. Always send `maxPages` and `maxDocuments`: left out, Silktide picks an\nallocation for you.\n\nTo configure a website before its first test, send `runNow: false` and\n`isReady: false`. It stays in `setup` until you\n[test it](/v1/governance/websites/test-website).\n\n`metaValues` goes inside `website`. Older documentation showed it beside\n`website`, where it is ignored.\n\nA missing `name` or `homeUrl` currently returns `500` rather than a `400`\nnaming the field.",
"tags": [
"Governance: Websites"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/websites/create-website"
},
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"website": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Its name. Plain text: no markup or control characters."
},
"homeUrl": {
"type": "string",
"description": "Its home page, as a full URL. Silktide tests everything under it."
},
"maxPages": {
"description": "The most pages to test. Must fit in the account's balance. Always send it.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"maxDocuments": {
"description": "The most documents (PDFs) to test. Must fit in the account's balance. Always send it.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"runNow": {
"description": "Start its first test now. Defaults to `true`.",
"type": "boolean"
},
"isReady": {
"description": "With `runNow: false`, `false` leaves it in `setup` so you can finish configuring it first. Defaults to `true`.",
"type": "boolean"
},
"metaValues": {
"description": "Metadata for the whole website, by metadata property name. Names the account has no property for are ignored.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"name",
"homeUrl"
],
"description": "The website."
},
"schedule": {
"description": "When to retest it. Replaces the whole schedule: any key left out takes its default.",
"type": "object",
"properties": {
"scheduleInterval": {
"description": "The unit to retest in. Defaults to empty, which is no schedule.",
"type": "string",
"enum": [
"",
"second",
"minute",
"hour",
"day",
"week",
"month",
"year"
]
},
"schedulePeriod": {
"description": "How many intervals apart tests are. Defaults to `1`.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"scheduleFromDate": {
"description": "When the schedule counts from. Defaults to now.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"schedulePreset": {
"description": "A named schedule, used instead of the interval and period: `five-daily`, `weekly`, `monthly`, or `none` for no schedule.",
"type": "string",
"enum": [
"",
"none",
"five-daily",
"weekly",
"monthly"
]
},
"isActive": {
"description": "Whether scheduled tests run. Defaults to `true`.",
"type": "boolean"
}
}
},
"options": {
"description": "Settings to change. Ones left out keep their value.",
"type": "object",
"properties": {
"website.allowFragmentPaths": {
"description": "Experimental. Crawl paths with fragments, such as hashbangs.",
"type": "boolean"
},
"website.allowedHttpCodes": {
"description": "HTTP codes to accept besides 2xx and 3xx, which are always accepted.",
"type": "array",
"items": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"website.authType": {
"description": "How Silktide signs in to pages that need it.",
"type": "string"
},
"website.benchmarkId": {
"description": "The Silktide Benchmark to grade against. Empty for none.",
"type": "string"
},
"website.benchmarkPercentile": {
"description": "The percentile to read from the benchmark.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.brokenLinkMaxRedirects": {
"description": "How many redirects a link may take before it counts as broken.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.brokenLinkPropulsionFallback": {
"description": "Confirm broken links in a real browser. Slower but more reliable.",
"type": "boolean"
},
"website.brokenLinkTimeout": {
"description": "Seconds to wait before a link counts as broken.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.clickSelector": {
"description": "A CSS selector Silktide clicks on each page before testing it.",
"type": "string"
},
"website.disableAnalytics": {
"description": "Block the website's analytics scripts while testing, so tests do not count as visits.",
"type": "boolean"
},
"website.disableFirstTimeVisit": {
"description": "Skip the built-in first-visit user flow, which tests pages before cookie banners are dismissed.",
"type": "boolean"
},
"website.disableLinkDiscovery": {
"description": "Test only the URLs you give, and follow no links.",
"type": "boolean"
},
"website.disableScrollDown": {
"description": "Do not scroll each page to the bottom and back while testing.",
"type": "boolean"
},
"website.disableStealth": {
"description": "Let websites detect that Silktide's browser is automated.",
"type": "boolean"
},
"website.enableAnimation": {
"description": "Let pages animate. Silktide stops animation by default.",
"type": "boolean"
},
"website.exclude3rdPartyPluginIssues": {
"description": "Ignore issues inside common third-party plugins, such as embedded maps.",
"type": "boolean"
},
"website.excludeQueryParams": {
"description": "Query parameters to remove from URLs, so pages that differ only by them count once.",
"type": "array",
"items": {
"type": "string"
}
},
"website.ignoreAutomaticSitemaps": {
"description": "Do not use the sitemaps Silktide finds on its own.",
"type": "boolean"
},
"website.inspectorCss": {
"description": "CSS added to pages when they are shown in the Inspector.",
"type": "string"
},
"website.languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Language codes, such as `en-US`, that every page is in. Always present."
},
"website.maxConnections": {
"description": "How many pages Silktide may load at once.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.normalizeUrlPath": {
"description": "Lowercase URL paths, for websites that mix case.",
"type": "boolean"
},
"website.optionalLanguages": {
"description": "Language codes a page might be in. Silktide detects them per page, which slows testing.",
"type": "array",
"items": {
"type": "string"
}
},
"website.pageWait": {
"description": "Seconds to wait after a page loads before testing it.",
"type": "number"
},
"website.proxyHost": {
"description": "A proxy server to test through.",
"type": "string"
},
"website.proxyPort": {
"description": "The proxy server's port.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.proxyPreset": {
"description": "One of Silktide's proxies: `eu-dublin`, `us-ohio` or `au-sydney`. Empty for the region's own location.",
"type": "string"
},
"website.proxyUsername": {
"description": "The proxy server's username.",
"type": "string"
},
"website.readabilityFormula": {
"description": "The readability formula, such as `smog`.",
"type": "string"
},
"website.readabilityThreshold": {
"description": "The readability score pages should stay within.",
"type": "number"
},
"website.reportLanguage": {
"description": "The language AI reports about the website are written in. Empty for the account's language.",
"type": "string"
},
"website.timeout": {
"description": "Seconds to wait for a page to load before giving up.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.trustPageDeclaredLanguage": {
"description": "Believe the language a page declares rather than detecting it.",
"type": "boolean"
},
"website.userAgentSuffix": {
"description": "Text added to the end of Silktide's browser user agent.",
"type": "string"
},
"website.username": {
"description": "The username Silktide signs in to pages with.",
"type": "string"
},
"website.aiEnabled": {
"description": "Whether Silktide's AI may work on this website.",
"type": "boolean"
},
"website.password": {
"description": "The password Silktide signs in to pages with. Write-only: reads say only whether one is set. Leave it out to keep the saved one; an empty string removes it.",
"type": "string"
},
"website.proxyPassword": {
"description": "The proxy server's password. Write-only, like `website.password`.",
"type": "string"
}
}
},
"tagIds": {
"description": "The tags for the whole website (section `0`). Replaces its tags; `[]` removes them all.",
"type": "array",
"items": {
"type": "string"
}
},
"governanceAiOptimizer": {
"description": "Whether to give it one of the account's Governance AI optimizers. Left out, it takes a free one unless it cannot use AI.",
"type": "boolean"
}
},
"required": [
"website"
]
},
"example": {
"website": {
"name": "Fake University",
"homeUrl": "https://fake-university.example/",
"maxPages": 100,
"maxDocuments": 100,
"metaValues": {
"author": "Joe Bloggs"
}
},
"schedule": {
"schedulePreset": "weekly"
},
"options": {
"website.benchmarkId": "fortune-500-usa",
"website.benchmarkPercentile": 90
},
"tagIds": [
"pre-production"
]
}
}
}
},
"responses": {
"200": {
"description": "Create a website",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"website": {
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"name": {
"type": "string",
"description": "Its name."
},
"homeUrl": {
"type": "string",
"description": "Its home page."
},
"status": {
"type": "string",
"enum": [
"installing",
"setup",
"live"
],
"description": "`installing` while Silktide creates it, `setup` before it goes live, `live` once it is tested."
},
"maxPages": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The most pages Silktide will test."
},
"maxDocuments": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The most documents (PDFs) Silktide will test."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it was created."
},
"lastTested": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When its last test finished. `0` if it has never been tested."
},
"propertyId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The Analytics property linked to the website. `0` when it has none."
}
},
"required": [
"websiteId",
"name",
"homeUrl",
"status",
"maxPages",
"maxDocuments",
"created",
"lastTested",
"propertyId"
],
"additionalProperties": false,
"description": "The website."
},
"permissions": {
"type": "object",
"properties": {
"components": {
"type": "array",
"items": {
"type": "object",
"properties": {
"permissionId": {
"type": "string",
"description": "The permission, such as `Website-WebsiteRead`."
},
"componentType": {
"type": "string",
"description": "What can be given it. `assignees` for users and roles."
},
"label": {
"type": "string",
"description": "Its name."
},
"description": {
"description": "What it allows. Null for some permissions.",
"type": [
"string",
"null"
]
},
"inheritedPermissionIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Permissions that include this one: anyone with those has this too."
},
"models": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
},
"description": "Reserved. Empty for website permissions."
}
},
"required": [
"permissionId",
"componentType",
"label",
"description",
"inheritedPermissionIds",
"models"
],
"additionalProperties": false
},
"description": "The permissions a website has."
},
"componentValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who was given each permission on this website directly, as assignee ids (`u:` users, `g:` roles)."
},
"fixedValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who has each permission from elsewhere, such as account-wide roles. Changed elsewhere, not here."
}
},
"required": [
"components",
"componentValues",
"fixedValues"
],
"additionalProperties": false,
"description": "Who may do what with the website."
},
"schedule": {
"type": "object",
"properties": {
"scheduleInterval": {
"type": "string",
"enum": [
"",
"second",
"minute",
"hour",
"day",
"week",
"month",
"year"
],
"description": "The unit it is retested in. Empty when it is not retested on a schedule."
},
"schedulePeriod": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "How many `scheduleInterval`s apart tests are."
},
"scheduleFromDate": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When the schedule counts from."
},
"schedulePreset": {
"type": "string",
"description": "A named schedule (`none`, `five-daily`, `weekly` or `monthly`), or empty when the interval and period were set directly."
},
"isActive": {
"type": "boolean",
"description": "Whether scheduled tests run."
}
},
"required": [
"scheduleInterval",
"schedulePeriod",
"scheduleFromDate",
"schedulePreset",
"isActive"
],
"additionalProperties": false,
"description": "When it is retested."
},
"options": {
"type": "object",
"properties": {
"website.allowFragmentPaths": {
"description": "Experimental. Crawl paths with fragments, such as hashbangs.",
"type": "boolean"
},
"website.allowedHttpCodes": {
"description": "HTTP codes to accept besides 2xx and 3xx, which are always accepted.",
"type": "array",
"items": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"website.authType": {
"description": "How Silktide signs in to pages that need it.",
"type": "string"
},
"website.benchmarkId": {
"description": "The Silktide Benchmark to grade against. Empty for none.",
"type": "string"
},
"website.benchmarkPercentile": {
"description": "The percentile to read from the benchmark.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.brokenLinkMaxRedirects": {
"description": "How many redirects a link may take before it counts as broken.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.brokenLinkPropulsionFallback": {
"description": "Confirm broken links in a real browser. Slower but more reliable.",
"type": "boolean"
},
"website.brokenLinkTimeout": {
"description": "Seconds to wait before a link counts as broken.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.clickSelector": {
"description": "A CSS selector Silktide clicks on each page before testing it.",
"type": "string"
},
"website.disableAnalytics": {
"description": "Block the website's analytics scripts while testing, so tests do not count as visits.",
"type": "boolean"
},
"website.disableFirstTimeVisit": {
"description": "Skip the built-in first-visit user flow, which tests pages before cookie banners are dismissed.",
"type": "boolean"
},
"website.disableLinkDiscovery": {
"description": "Test only the URLs you give, and follow no links.",
"type": "boolean"
},
"website.disableScrollDown": {
"description": "Do not scroll each page to the bottom and back while testing.",
"type": "boolean"
},
"website.disableStealth": {
"description": "Let websites detect that Silktide's browser is automated.",
"type": "boolean"
},
"website.enableAnimation": {
"description": "Let pages animate. Silktide stops animation by default.",
"type": "boolean"
},
"website.exclude3rdPartyPluginIssues": {
"description": "Ignore issues inside common third-party plugins, such as embedded maps.",
"type": "boolean"
},
"website.excludeQueryParams": {
"description": "Query parameters to remove from URLs, so pages that differ only by them count once.",
"type": "array",
"items": {
"type": "string"
}
},
"website.ignoreAutomaticSitemaps": {
"description": "Do not use the sitemaps Silktide finds on its own.",
"type": "boolean"
},
"website.inspectorCss": {
"description": "CSS added to pages when they are shown in the Inspector.",
"type": "string"
},
"website.languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Language codes, such as `en-US`, that every page is in. Always present."
},
"website.maxConnections": {
"description": "How many pages Silktide may load at once.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.normalizeUrlPath": {
"description": "Lowercase URL paths, for websites that mix case.",
"type": "boolean"
},
"website.optionalLanguages": {
"description": "Language codes a page might be in. Silktide detects them per page, which slows testing.",
"type": "array",
"items": {
"type": "string"
}
},
"website.pageWait": {
"description": "Seconds to wait after a page loads before testing it.",
"type": "number"
},
"website.proxyHost": {
"description": "A proxy server to test through.",
"type": "string"
},
"website.proxyPort": {
"description": "The proxy server's port.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.proxyPreset": {
"description": "One of Silktide's proxies: `eu-dublin`, `us-ohio` or `au-sydney`. Empty for the region's own location.",
"type": "string"
},
"website.proxyUsername": {
"description": "The proxy server's username.",
"type": "string"
},
"website.readabilityFormula": {
"description": "The readability formula, such as `smog`.",
"type": "string"
},
"website.readabilityThreshold": {
"description": "The readability score pages should stay within.",
"type": "number"
},
"website.reportLanguage": {
"description": "The language AI reports about the website are written in. Empty for the account's language.",
"type": "string"
},
"website.timeout": {
"description": "Seconds to wait for a page to load before giving up.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.trustPageDeclaredLanguage": {
"description": "Believe the language a page declares rather than detecting it.",
"type": "boolean"
},
"website.userAgentSuffix": {
"description": "Text added to the end of Silktide's browser user agent.",
"type": "string"
},
"website.username": {
"description": "The username Silktide signs in to pages with.",
"type": "string"
},
"website.aiEnabled": {
"description": "Whether Silktide's AI may work on this website.",
"type": "boolean"
},
"website.passwordSet": {
"type": "boolean",
"description": "Whether a sign-in password is saved. Always present. Read-only: sending it changes nothing."
},
"website.proxyPasswordSet": {
"type": "boolean",
"description": "Whether a proxy password is saved. Always present. Read-only, like `website.passwordSet`."
}
},
"required": [
"website.languages",
"website.passwordSet",
"website.proxyPasswordSet"
],
"additionalProperties": false,
"description": "Its settings, by name."
},
"tagIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "The ids of the tags on the whole website (section `0`)."
},
"governanceAiOptimizer": {
"type": "boolean",
"description": "Whether the website holds one of the account's Governance AI optimizers."
},
"governanceAiOptimizerAvailable": {
"type": "boolean",
"description": "Whether it could be given one now, counting one its own recent reports still hold."
},
"reportLanguage": {
"type": "string",
"description": "The language its AI reports are written in: its own setting, or the account's when unset."
}
},
"required": [
"website",
"permissions",
"schedule",
"options",
"tagIds",
"governanceAiOptimizer",
"governanceAiOptimizerAvailable",
"reportLanguage"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
}
},
"example": {
"website": {
"websiteId": 6,
"name": "Fake University",
"homeUrl": "https://fake-university.example/",
"status": "live",
"maxPages": 100,
"maxDocuments": 100,
"created": 1793736881,
"lastTested": 0,
"propertyId": 0
},
"permissions": {
"components": [],
"componentValues": {},
"fixedValues": {}
},
"schedule": {
"scheduleInterval": "week",
"schedulePeriod": 1,
"scheduleFromDate": 1793736881,
"schedulePreset": "weekly",
"isActive": true
},
"options": {
"website.languages": [
"en-US"
],
"website.benchmarkId": "fortune-500-usa",
"website.benchmarkPercentile": 90,
"website.passwordSet": false,
"website.proxyPasswordSet": false
},
"tagIds": [
"pre-production"
],
"governanceAiOptimizer": true,
"governanceAiOptimizerAvailable": true,
"reportLanguage": "en-US"
}
}
}
},
"400": {
"description": "`InvalidRequest`: The name contains markup or control characters, `website.reportLanguage` is not a language Silktide writes reports in, or `tagIds` adds an id that is not one of the account's `section` tags. `properties.field` names it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The account cannot add another website, or `maxPages` or `maxDocuments` is more than its balance has left.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "`Runtime`: `name` or `homeUrl` is missing.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "paid"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/websites/{websiteId}": {
"get": {
"operationId": "getWebsite",
"summary": "Get a website's settings",
"description": "Returns one website: its details, who may do what with it, when it is\nretested, and its settings. Updating a website returns the same body.\n\nThe API key's user must be able to admin the website. A user who can only see\nit gets `403 AccessDenied`; a website they cannot see at all, or that does\nnot exist, gets `404 ModelNotFound`.\n\n`options` holds each setting that has been set or has a default. Settings can\nbe added over time, so ignore any you do not recognize. `website.languages`\nis always present.\n\n`websiteId` must be a whole number. Anything else currently returns `500`\nrather than `404`.",
"tags": [
"Governance: Websites"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/websites/get-website"
},
"parameters": [
{
"name": "websiteId",
"in": "path",
"required": true,
"description": "The website.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "Get a website's settings",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"website": {
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"name": {
"type": "string",
"description": "Its name."
},
"homeUrl": {
"type": "string",
"description": "Its home page."
},
"status": {
"type": "string",
"enum": [
"installing",
"setup",
"live"
],
"description": "`installing` while Silktide creates it, `setup` before it goes live, `live` once it is tested."
},
"maxPages": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The most pages Silktide will test."
},
"maxDocuments": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The most documents (PDFs) Silktide will test."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it was created."
},
"lastTested": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When its last test finished. `0` if it has never been tested."
},
"propertyId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The Analytics property linked to the website. `0` when it has none."
}
},
"required": [
"websiteId",
"name",
"homeUrl",
"status",
"maxPages",
"maxDocuments",
"created",
"lastTested",
"propertyId"
],
"additionalProperties": false,
"description": "The website."
},
"permissions": {
"type": "object",
"properties": {
"components": {
"type": "array",
"items": {
"type": "object",
"properties": {
"permissionId": {
"type": "string",
"description": "The permission, such as `Website-WebsiteRead`."
},
"componentType": {
"type": "string",
"description": "What can be given it. `assignees` for users and roles."
},
"label": {
"type": "string",
"description": "Its name."
},
"description": {
"description": "What it allows. Null for some permissions.",
"type": [
"string",
"null"
]
},
"inheritedPermissionIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Permissions that include this one: anyone with those has this too."
},
"models": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
},
"description": "Reserved. Empty for website permissions."
}
},
"required": [
"permissionId",
"componentType",
"label",
"description",
"inheritedPermissionIds",
"models"
],
"additionalProperties": false
},
"description": "The permissions a website has."
},
"componentValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who was given each permission on this website directly, as assignee ids (`u:` users, `g:` roles)."
},
"fixedValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who has each permission from elsewhere, such as account-wide roles. Changed elsewhere, not here."
}
},
"required": [
"components",
"componentValues",
"fixedValues"
],
"additionalProperties": false,
"description": "Who may do what with the website."
},
"schedule": {
"type": "object",
"properties": {
"scheduleInterval": {
"type": "string",
"enum": [
"",
"second",
"minute",
"hour",
"day",
"week",
"month",
"year"
],
"description": "The unit it is retested in. Empty when it is not retested on a schedule."
},
"schedulePeriod": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "How many `scheduleInterval`s apart tests are."
},
"scheduleFromDate": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When the schedule counts from."
},
"schedulePreset": {
"type": "string",
"description": "A named schedule (`none`, `five-daily`, `weekly` or `monthly`), or empty when the interval and period were set directly."
},
"isActive": {
"type": "boolean",
"description": "Whether scheduled tests run."
}
},
"required": [
"scheduleInterval",
"schedulePeriod",
"scheduleFromDate",
"schedulePreset",
"isActive"
],
"additionalProperties": false,
"description": "When it is retested."
},
"options": {
"type": "object",
"properties": {
"website.allowFragmentPaths": {
"description": "Experimental. Crawl paths with fragments, such as hashbangs.",
"type": "boolean"
},
"website.allowedHttpCodes": {
"description": "HTTP codes to accept besides 2xx and 3xx, which are always accepted.",
"type": "array",
"items": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"website.authType": {
"description": "How Silktide signs in to pages that need it.",
"type": "string"
},
"website.benchmarkId": {
"description": "The Silktide Benchmark to grade against. Empty for none.",
"type": "string"
},
"website.benchmarkPercentile": {
"description": "The percentile to read from the benchmark.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.brokenLinkMaxRedirects": {
"description": "How many redirects a link may take before it counts as broken.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.brokenLinkPropulsionFallback": {
"description": "Confirm broken links in a real browser. Slower but more reliable.",
"type": "boolean"
},
"website.brokenLinkTimeout": {
"description": "Seconds to wait before a link counts as broken.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.clickSelector": {
"description": "A CSS selector Silktide clicks on each page before testing it.",
"type": "string"
},
"website.disableAnalytics": {
"description": "Block the website's analytics scripts while testing, so tests do not count as visits.",
"type": "boolean"
},
"website.disableFirstTimeVisit": {
"description": "Skip the built-in first-visit user flow, which tests pages before cookie banners are dismissed.",
"type": "boolean"
},
"website.disableLinkDiscovery": {
"description": "Test only the URLs you give, and follow no links.",
"type": "boolean"
},
"website.disableScrollDown": {
"description": "Do not scroll each page to the bottom and back while testing.",
"type": "boolean"
},
"website.disableStealth": {
"description": "Let websites detect that Silktide's browser is automated.",
"type": "boolean"
},
"website.enableAnimation": {
"description": "Let pages animate. Silktide stops animation by default.",
"type": "boolean"
},
"website.exclude3rdPartyPluginIssues": {
"description": "Ignore issues inside common third-party plugins, such as embedded maps.",
"type": "boolean"
},
"website.excludeQueryParams": {
"description": "Query parameters to remove from URLs, so pages that differ only by them count once.",
"type": "array",
"items": {
"type": "string"
}
},
"website.ignoreAutomaticSitemaps": {
"description": "Do not use the sitemaps Silktide finds on its own.",
"type": "boolean"
},
"website.inspectorCss": {
"description": "CSS added to pages when they are shown in the Inspector.",
"type": "string"
},
"website.languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Language codes, such as `en-US`, that every page is in. Always present."
},
"website.maxConnections": {
"description": "How many pages Silktide may load at once.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.normalizeUrlPath": {
"description": "Lowercase URL paths, for websites that mix case.",
"type": "boolean"
},
"website.optionalLanguages": {
"description": "Language codes a page might be in. Silktide detects them per page, which slows testing.",
"type": "array",
"items": {
"type": "string"
}
},
"website.pageWait": {
"description": "Seconds to wait after a page loads before testing it.",
"type": "number"
},
"website.proxyHost": {
"description": "A proxy server to test through.",
"type": "string"
},
"website.proxyPort": {
"description": "The proxy server's port.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.proxyPreset": {
"description": "One of Silktide's proxies: `eu-dublin`, `us-ohio` or `au-sydney`. Empty for the region's own location.",
"type": "string"
},
"website.proxyUsername": {
"description": "The proxy server's username.",
"type": "string"
},
"website.readabilityFormula": {
"description": "The readability formula, such as `smog`.",
"type": "string"
},
"website.readabilityThreshold": {
"description": "The readability score pages should stay within.",
"type": "number"
},
"website.reportLanguage": {
"description": "The language AI reports about the website are written in. Empty for the account's language.",
"type": "string"
},
"website.timeout": {
"description": "Seconds to wait for a page to load before giving up.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.trustPageDeclaredLanguage": {
"description": "Believe the language a page declares rather than detecting it.",
"type": "boolean"
},
"website.userAgentSuffix": {
"description": "Text added to the end of Silktide's browser user agent.",
"type": "string"
},
"website.username": {
"description": "The username Silktide signs in to pages with.",
"type": "string"
},
"website.aiEnabled": {
"description": "Whether Silktide's AI may work on this website.",
"type": "boolean"
},
"website.passwordSet": {
"type": "boolean",
"description": "Whether a sign-in password is saved. Always present. Read-only: sending it changes nothing."
},
"website.proxyPasswordSet": {
"type": "boolean",
"description": "Whether a proxy password is saved. Always present. Read-only, like `website.passwordSet`."
}
},
"required": [
"website.languages",
"website.passwordSet",
"website.proxyPasswordSet"
],
"additionalProperties": false,
"description": "Its settings, by name."
},
"tagIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "The ids of the tags on the whole website (section `0`)."
},
"governanceAiOptimizer": {
"type": "boolean",
"description": "Whether the website holds one of the account's Governance AI optimizers."
},
"governanceAiOptimizerAvailable": {
"type": "boolean",
"description": "Whether it could be given one now, counting one its own recent reports still hold."
},
"reportLanguage": {
"type": "string",
"description": "The language its AI reports are written in: its own setting, or the account's when unset."
}
},
"required": [
"website",
"permissions",
"schedule",
"options",
"tagIds",
"governanceAiOptimizer",
"governanceAiOptimizerAvailable",
"reportLanguage"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
}
},
"example": {
"website": {
"websiteId": 2,
"name": "Example",
"homeUrl": "https://example.com/",
"status": "live",
"maxPages": 1000,
"maxDocuments": 500,
"created": 1790216529,
"lastTested": 1790302929,
"propertyId": 0
},
"permissions": {
"components": [
{
"permissionId": "Website-WebsiteRead",
"componentType": "assignees",
"label": "Can see website",
"description": "Can see this website, and any sections within this website.",
"inheritedPermissionIds": [
"Website-WebsiteContribute",
"Website-WebsiteTest",
"Website-WebsiteReadAll"
],
"models": []
}
],
"componentValues": {
"Website-WebsiteRead": [
"u:eu-12"
]
},
"fixedValues": {
"Website-WebsiteRead": [
"g:2"
]
}
},
"schedule": {
"scheduleInterval": "day",
"schedulePeriod": 5,
"scheduleFromDate": 1790216529,
"schedulePreset": "",
"isActive": true
},
"options": {
"website.languages": [
"en-US"
],
"website.optionalLanguages": [],
"website.maxConnections": 6,
"website.timeout": 30,
"website.pageWait": 0,
"website.excludeQueryParams": [
"utm_source",
"utm_medium"
],
"website.disableAnalytics": true,
"website.enableAnimation": false,
"website.reportLanguage": "",
"website.passwordSet": false,
"website.proxyPasswordSet": false
},
"tagIds": [
"marketing"
],
"governanceAiOptimizer": false,
"governanceAiOptimizerAvailable": true,
"reportLanguage": "en-US"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot admin this website.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: Nothing with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "Can admin this website",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
},
"put": {
"operationId": "updateWebsite",
"summary": "Update a website",
"description": "Changes a website. Send only what you want to change; the response is the\nwhole website, as [Get a website](/v1/governance/websites/get-website)\nreturns it.\n\nTwo parts replace rather than merge:\n\n- `schedule` replaces the whole schedule. A key you leave out takes its\n default (no interval, a period of `1`, starting now, active), so send every\n key you care about.\n- `tagIds` replaces the website's tags. Send `[]` to remove them all; leave it\n out to keep them. Each id you add must be one of the account's `section`\n tags, so [create a tag](/v1/platform/tags/create-tag) first; any other id\n is refused with `400` and the request changes nothing.\n\n`options` merges: a setting you leave out keeps its value.\n\nA larger `maxPages` or `maxDocuments` must be within what\n[Get a website's balance](/v1/platform/balances/get-website-balance) says the\nwebsite can be given. Lowering them, or changing anything else, always works,\neven on an account that is over its balance.\n\nIf you leave out `governanceAiOptimizer` and the website can no longer use AI\nafter the update (for example `website.aiEnabled: false`), it gives back its\nGovernance AI optimizer.",
"tags": [
"Governance: Websites"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/websites/update-website"
},
"parameters": [
{
"name": "websiteId",
"in": "path",
"required": true,
"description": "The website.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"website": {
"description": "Details to change. Ones left out keep their value.",
"type": "object",
"properties": {
"name": {
"description": "Its name. Plain text: no markup or control characters.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"homeUrl": {
"description": "Its home page, as a full URL.",
"type": "string"
},
"maxPages": {
"description": "The most pages to test. An increase must fit in the account's balance.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"maxDocuments": {
"description": "The most documents (PDFs) to test. An increase must fit in the account's balance.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
}
},
"schedule": {
"description": "When to retest it. Replaces the whole schedule: any key left out takes its default.",
"type": "object",
"properties": {
"scheduleInterval": {
"description": "The unit to retest in. Defaults to empty, which is no schedule.",
"type": "string",
"enum": [
"",
"second",
"minute",
"hour",
"day",
"week",
"month",
"year"
]
},
"schedulePeriod": {
"description": "How many intervals apart tests are. Defaults to `1`.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"scheduleFromDate": {
"description": "When the schedule counts from. Defaults to now.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"schedulePreset": {
"description": "A named schedule, used instead of the interval and period: `five-daily`, `weekly`, `monthly`, or `none` for no schedule.",
"type": "string",
"enum": [
"",
"none",
"five-daily",
"weekly",
"monthly"
]
},
"isActive": {
"description": "Whether scheduled tests run. Defaults to `true`.",
"type": "boolean"
}
}
},
"options": {
"description": "Settings to change. Ones left out keep their value.",
"type": "object",
"properties": {
"website.allowFragmentPaths": {
"description": "Experimental. Crawl paths with fragments, such as hashbangs.",
"type": "boolean"
},
"website.allowedHttpCodes": {
"description": "HTTP codes to accept besides 2xx and 3xx, which are always accepted.",
"type": "array",
"items": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"website.authType": {
"description": "How Silktide signs in to pages that need it.",
"type": "string"
},
"website.benchmarkId": {
"description": "The Silktide Benchmark to grade against. Empty for none.",
"type": "string"
},
"website.benchmarkPercentile": {
"description": "The percentile to read from the benchmark.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.brokenLinkMaxRedirects": {
"description": "How many redirects a link may take before it counts as broken.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.brokenLinkPropulsionFallback": {
"description": "Confirm broken links in a real browser. Slower but more reliable.",
"type": "boolean"
},
"website.brokenLinkTimeout": {
"description": "Seconds to wait before a link counts as broken.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.clickSelector": {
"description": "A CSS selector Silktide clicks on each page before testing it.",
"type": "string"
},
"website.disableAnalytics": {
"description": "Block the website's analytics scripts while testing, so tests do not count as visits.",
"type": "boolean"
},
"website.disableFirstTimeVisit": {
"description": "Skip the built-in first-visit user flow, which tests pages before cookie banners are dismissed.",
"type": "boolean"
},
"website.disableLinkDiscovery": {
"description": "Test only the URLs you give, and follow no links.",
"type": "boolean"
},
"website.disableScrollDown": {
"description": "Do not scroll each page to the bottom and back while testing.",
"type": "boolean"
},
"website.disableStealth": {
"description": "Let websites detect that Silktide's browser is automated.",
"type": "boolean"
},
"website.enableAnimation": {
"description": "Let pages animate. Silktide stops animation by default.",
"type": "boolean"
},
"website.exclude3rdPartyPluginIssues": {
"description": "Ignore issues inside common third-party plugins, such as embedded maps.",
"type": "boolean"
},
"website.excludeQueryParams": {
"description": "Query parameters to remove from URLs, so pages that differ only by them count once.",
"type": "array",
"items": {
"type": "string"
}
},
"website.ignoreAutomaticSitemaps": {
"description": "Do not use the sitemaps Silktide finds on its own.",
"type": "boolean"
},
"website.inspectorCss": {
"description": "CSS added to pages when they are shown in the Inspector.",
"type": "string"
},
"website.languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Language codes, such as `en-US`, that every page is in. Always present."
},
"website.maxConnections": {
"description": "How many pages Silktide may load at once.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.normalizeUrlPath": {
"description": "Lowercase URL paths, for websites that mix case.",
"type": "boolean"
},
"website.optionalLanguages": {
"description": "Language codes a page might be in. Silktide detects them per page, which slows testing.",
"type": "array",
"items": {
"type": "string"
}
},
"website.pageWait": {
"description": "Seconds to wait after a page loads before testing it.",
"type": "number"
},
"website.proxyHost": {
"description": "A proxy server to test through.",
"type": "string"
},
"website.proxyPort": {
"description": "The proxy server's port.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.proxyPreset": {
"description": "One of Silktide's proxies: `eu-dublin`, `us-ohio` or `au-sydney`. Empty for the region's own location.",
"type": "string"
},
"website.proxyUsername": {
"description": "The proxy server's username.",
"type": "string"
},
"website.readabilityFormula": {
"description": "The readability formula, such as `smog`.",
"type": "string"
},
"website.readabilityThreshold": {
"description": "The readability score pages should stay within.",
"type": "number"
},
"website.reportLanguage": {
"description": "The language AI reports about the website are written in. Empty for the account's language.",
"type": "string"
},
"website.timeout": {
"description": "Seconds to wait for a page to load before giving up.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.trustPageDeclaredLanguage": {
"description": "Believe the language a page declares rather than detecting it.",
"type": "boolean"
},
"website.userAgentSuffix": {
"description": "Text added to the end of Silktide's browser user agent.",
"type": "string"
},
"website.username": {
"description": "The username Silktide signs in to pages with.",
"type": "string"
},
"website.aiEnabled": {
"description": "Whether Silktide's AI may work on this website.",
"type": "boolean"
},
"website.password": {
"description": "The password Silktide signs in to pages with. Write-only: reads say only whether one is set. Leave it out to keep the saved one; an empty string removes it.",
"type": "string"
},
"website.proxyPassword": {
"description": "The proxy server's password. Write-only, like `website.password`.",
"type": "string"
}
}
},
"tagIds": {
"description": "The tags for the whole website (section `0`). Replaces its tags; `[]` removes them all.",
"type": "array",
"items": {
"type": "string"
}
},
"governanceAiOptimizer": {
"description": "`true` to give the website one of the account's Governance AI optimizers, `false` to give its back.",
"type": "boolean"
}
}
},
"example": {
"website": {
"name": "Example (main site)"
},
"schedule": {
"scheduleInterval": "month",
"schedulePeriod": 1
},
"tagIds": [
"competitor"
]
}
}
}
},
"responses": {
"200": {
"description": "Update a website",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"website": {
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"name": {
"type": "string",
"description": "Its name."
},
"homeUrl": {
"type": "string",
"description": "Its home page."
},
"status": {
"type": "string",
"enum": [
"installing",
"setup",
"live"
],
"description": "`installing` while Silktide creates it, `setup` before it goes live, `live` once it is tested."
},
"maxPages": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The most pages Silktide will test."
},
"maxDocuments": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The most documents (PDFs) Silktide will test."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it was created."
},
"lastTested": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When its last test finished. `0` if it has never been tested."
},
"propertyId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The Analytics property linked to the website. `0` when it has none."
}
},
"required": [
"websiteId",
"name",
"homeUrl",
"status",
"maxPages",
"maxDocuments",
"created",
"lastTested",
"propertyId"
],
"additionalProperties": false,
"description": "The website."
},
"permissions": {
"type": "object",
"properties": {
"components": {
"type": "array",
"items": {
"type": "object",
"properties": {
"permissionId": {
"type": "string",
"description": "The permission, such as `Website-WebsiteRead`."
},
"componentType": {
"type": "string",
"description": "What can be given it. `assignees` for users and roles."
},
"label": {
"type": "string",
"description": "Its name."
},
"description": {
"description": "What it allows. Null for some permissions.",
"type": [
"string",
"null"
]
},
"inheritedPermissionIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Permissions that include this one: anyone with those has this too."
},
"models": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
},
"description": "Reserved. Empty for website permissions."
}
},
"required": [
"permissionId",
"componentType",
"label",
"description",
"inheritedPermissionIds",
"models"
],
"additionalProperties": false
},
"description": "The permissions a website has."
},
"componentValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who was given each permission on this website directly, as assignee ids (`u:` users, `g:` roles)."
},
"fixedValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who has each permission from elsewhere, such as account-wide roles. Changed elsewhere, not here."
}
},
"required": [
"components",
"componentValues",
"fixedValues"
],
"additionalProperties": false,
"description": "Who may do what with the website."
},
"schedule": {
"type": "object",
"properties": {
"scheduleInterval": {
"type": "string",
"enum": [
"",
"second",
"minute",
"hour",
"day",
"week",
"month",
"year"
],
"description": "The unit it is retested in. Empty when it is not retested on a schedule."
},
"schedulePeriod": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "How many `scheduleInterval`s apart tests are."
},
"scheduleFromDate": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When the schedule counts from."
},
"schedulePreset": {
"type": "string",
"description": "A named schedule (`none`, `five-daily`, `weekly` or `monthly`), or empty when the interval and period were set directly."
},
"isActive": {
"type": "boolean",
"description": "Whether scheduled tests run."
}
},
"required": [
"scheduleInterval",
"schedulePeriod",
"scheduleFromDate",
"schedulePreset",
"isActive"
],
"additionalProperties": false,
"description": "When it is retested."
},
"options": {
"type": "object",
"properties": {
"website.allowFragmentPaths": {
"description": "Experimental. Crawl paths with fragments, such as hashbangs.",
"type": "boolean"
},
"website.allowedHttpCodes": {
"description": "HTTP codes to accept besides 2xx and 3xx, which are always accepted.",
"type": "array",
"items": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"website.authType": {
"description": "How Silktide signs in to pages that need it.",
"type": "string"
},
"website.benchmarkId": {
"description": "The Silktide Benchmark to grade against. Empty for none.",
"type": "string"
},
"website.benchmarkPercentile": {
"description": "The percentile to read from the benchmark.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.brokenLinkMaxRedirects": {
"description": "How many redirects a link may take before it counts as broken.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.brokenLinkPropulsionFallback": {
"description": "Confirm broken links in a real browser. Slower but more reliable.",
"type": "boolean"
},
"website.brokenLinkTimeout": {
"description": "Seconds to wait before a link counts as broken.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.clickSelector": {
"description": "A CSS selector Silktide clicks on each page before testing it.",
"type": "string"
},
"website.disableAnalytics": {
"description": "Block the website's analytics scripts while testing, so tests do not count as visits.",
"type": "boolean"
},
"website.disableFirstTimeVisit": {
"description": "Skip the built-in first-visit user flow, which tests pages before cookie banners are dismissed.",
"type": "boolean"
},
"website.disableLinkDiscovery": {
"description": "Test only the URLs you give, and follow no links.",
"type": "boolean"
},
"website.disableScrollDown": {
"description": "Do not scroll each page to the bottom and back while testing.",
"type": "boolean"
},
"website.disableStealth": {
"description": "Let websites detect that Silktide's browser is automated.",
"type": "boolean"
},
"website.enableAnimation": {
"description": "Let pages animate. Silktide stops animation by default.",
"type": "boolean"
},
"website.exclude3rdPartyPluginIssues": {
"description": "Ignore issues inside common third-party plugins, such as embedded maps.",
"type": "boolean"
},
"website.excludeQueryParams": {
"description": "Query parameters to remove from URLs, so pages that differ only by them count once.",
"type": "array",
"items": {
"type": "string"
}
},
"website.ignoreAutomaticSitemaps": {
"description": "Do not use the sitemaps Silktide finds on its own.",
"type": "boolean"
},
"website.inspectorCss": {
"description": "CSS added to pages when they are shown in the Inspector.",
"type": "string"
},
"website.languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Language codes, such as `en-US`, that every page is in. Always present."
},
"website.maxConnections": {
"description": "How many pages Silktide may load at once.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.normalizeUrlPath": {
"description": "Lowercase URL paths, for websites that mix case.",
"type": "boolean"
},
"website.optionalLanguages": {
"description": "Language codes a page might be in. Silktide detects them per page, which slows testing.",
"type": "array",
"items": {
"type": "string"
}
},
"website.pageWait": {
"description": "Seconds to wait after a page loads before testing it.",
"type": "number"
},
"website.proxyHost": {
"description": "A proxy server to test through.",
"type": "string"
},
"website.proxyPort": {
"description": "The proxy server's port.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.proxyPreset": {
"description": "One of Silktide's proxies: `eu-dublin`, `us-ohio` or `au-sydney`. Empty for the region's own location.",
"type": "string"
},
"website.proxyUsername": {
"description": "The proxy server's username.",
"type": "string"
},
"website.readabilityFormula": {
"description": "The readability formula, such as `smog`.",
"type": "string"
},
"website.readabilityThreshold": {
"description": "The readability score pages should stay within.",
"type": "number"
},
"website.reportLanguage": {
"description": "The language AI reports about the website are written in. Empty for the account's language.",
"type": "string"
},
"website.timeout": {
"description": "Seconds to wait for a page to load before giving up.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"website.trustPageDeclaredLanguage": {
"description": "Believe the language a page declares rather than detecting it.",
"type": "boolean"
},
"website.userAgentSuffix": {
"description": "Text added to the end of Silktide's browser user agent.",
"type": "string"
},
"website.username": {
"description": "The username Silktide signs in to pages with.",
"type": "string"
},
"website.aiEnabled": {
"description": "Whether Silktide's AI may work on this website.",
"type": "boolean"
},
"website.passwordSet": {
"type": "boolean",
"description": "Whether a sign-in password is saved. Always present. Read-only: sending it changes nothing."
},
"website.proxyPasswordSet": {
"type": "boolean",
"description": "Whether a proxy password is saved. Always present. Read-only, like `website.passwordSet`."
}
},
"required": [
"website.languages",
"website.passwordSet",
"website.proxyPasswordSet"
],
"additionalProperties": false,
"description": "Its settings, by name."
},
"tagIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "The ids of the tags on the whole website (section `0`)."
},
"governanceAiOptimizer": {
"type": "boolean",
"description": "Whether the website holds one of the account's Governance AI optimizers."
},
"governanceAiOptimizerAvailable": {
"type": "boolean",
"description": "Whether it could be given one now, counting one its own recent reports still hold."
},
"reportLanguage": {
"type": "string",
"description": "The language its AI reports are written in: its own setting, or the account's when unset."
}
},
"required": [
"website",
"permissions",
"schedule",
"options",
"tagIds",
"governanceAiOptimizer",
"governanceAiOptimizerAvailable",
"reportLanguage"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
}
},
"example": {
"website": {
"websiteId": 2,
"name": "Example (main site)",
"homeUrl": "https://example.com/",
"status": "live",
"maxPages": 1000,
"maxDocuments": 500,
"created": 1790216529,
"lastTested": 1790302929,
"propertyId": 0
},
"permissions": {
"components": [],
"componentValues": {},
"fixedValues": {}
},
"schedule": {
"scheduleInterval": "month",
"schedulePeriod": 1,
"scheduleFromDate": 1793736900,
"schedulePreset": "",
"isActive": true
},
"options": {
"website.languages": [
"en-US"
],
"website.passwordSet": false,
"website.proxyPasswordSet": false
},
"tagIds": [
"competitor"
],
"governanceAiOptimizer": false,
"governanceAiOptimizerAvailable": true,
"reportLanguage": "en-US"
}
}
}
},
"400": {
"description": "`InvalidRequest`: The name contains markup or control characters, `website.reportLanguage` is not a language Silktide writes reports in, or `tagIds` adds an id that is not one of the account's `section` tags. `properties.field` names it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot admin this website. `InsufficientBalance`: A larger `maxPages` or `maxDocuments` is more than the website can be given. `properties.featureId` names the balance.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: Nothing with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "Can admin this website",
"feature": null,
"cost": "paid"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
},
"delete": {
"operationId": "deleteWebsite",
"summary": "Delete a website and everything in it",
"description": "Deletes a website at once, with its sections, results and history. It cannot\nbe undone.\n\nThe response is an empty `201`. The pages and documents the website held go\nback to the account's balance. Deleting it again returns `404`.",
"tags": [
"Governance: Websites"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/websites/delete-website"
},
"parameters": [
{
"name": "websiteId",
"in": "path",
"required": true,
"description": "The website.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"201": {
"description": "Delete a website and everything in it"
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot admin this website.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: Nothing with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "Can admin this website",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/websites/{websiteId}/test": {
"post": {
"operationId": "testWebsite",
"summary": "Test a website now",
"description": "Starts a test. With no body, Silktide retests the whole website, finding new\npages as it goes. With `urls`, it tests only those pages and does not look\nfor others.\n\nThe response is an empty `201` once the test is queued, not when it\nfinishes.\n\nURLs outside the website's rules are skipped without an error. If none of\nthem fit, nothing is tested, and the response is still `201`.\n\nA website runs at most three website or section tests at once; tests of\nspecific URLs do not count towards that. A fourth gets `403 AccessDenied`\nuntil one finishes.",
"tags": [
"Governance: Websites"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/websites/test-website"
},
"parameters": [
{
"name": "websiteId",
"in": "path",
"required": true,
"description": "The website.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"urls": {
"description": "Test only these pages, as full URLs, instead of the whole website. Pages it does not have yet are added if they fit its rules and its balance.",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {}
}
}
},
"responses": {
"201": {
"description": "Test a website now"
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot test this website, the account has no tests left, or the website already has too many tests running.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: Nothing with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "Can test this website",
"feature": null,
"cost": "paid"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/websites/stats": {
"get": {
"operationId": "getWebsiteStats",
"summary": "Get headline statistics for every website",
"description": "Returns the headline statistics of every live website in one call: scores,\nissue counts, page counts and the technology Silktide found. Websites still\nin `setup` are left out.\n\n`websites` and each `sections` are objects keyed by id, not arrays, and stay\nobjects (`{}`) when empty. Section `0`, the whole website, is not in\n`sections`: its statistics are the website's own `stats`.\n\nWebsites do not all have the same statistics, so read them by id and expect\nsome to be missing. A statistic with no value yet is\n`null`.\n\nThis call returns everything at once, which is slow for an account with many\nwebsites. To read one website, or a statistic over time, use the results\nqueries instead.",
"tags": [
"Governance: Websites"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/websites/get-website-stats"
},
"parameters": [],
"responses": {
"200": {
"description": "Get headline statistics for every website",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"websites": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The website's name."
},
"homeUrl": {
"type": "string",
"description": "Its home page."
},
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"stats": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"label": {
"type": "string",
"description": "The statistic's name, in the API user's language."
},
"value": {
"description": "Its value. Usually a number; a name for technology statistics; null when there is none yet.",
"type": [
"number",
"string",
"null"
]
}
},
"required": [
"label",
"value"
],
"additionalProperties": false
},
"description": "Headline statistics by id, such as `overall.score` or `website.pages`."
},
"sections": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The section's name."
},
"homeUrl": {
"type": "string",
"description": "Its home page. Can be empty."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The section."
},
"stats": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"label": {
"type": "string",
"description": "The statistic's name, in the API user's language."
},
"value": {
"description": "Its value. Usually a number; a name for technology statistics; null when there is none yet.",
"type": [
"number",
"string",
"null"
]
}
},
"required": [
"label",
"value"
],
"additionalProperties": false
},
"description": "Headline statistics by id, such as `overall.score` or `website.pages`."
}
},
"required": [
"name",
"homeUrl",
"sectionId",
"stats"
],
"additionalProperties": false
},
"description": "Its sections other than section `0`, by section id. `{}` when it has none."
}
},
"required": [
"name",
"homeUrl",
"websiteId",
"stats",
"sections"
],
"additionalProperties": false
},
"description": "Each live website the API key's user can see, by website id."
}
},
"required": [
"websites"
],
"additionalProperties": false
},
"example": {
"websites": {
"2": {
"name": "Example",
"homeUrl": "https://example.com/",
"websiteId": 2,
"stats": {
"overall.score": {
"label": "Overall score",
"value": 73.6
},
"wcag-22-aa.score": {
"label": "WCAG 2.2 AA score",
"value": 88.2
},
"website.pages": {
"label": "Pages tested",
"value": 812
},
"technology.cms": {
"label": "Most used CMS",
"value": "WordPress"
}
},
"sections": {
"3": {
"name": "Blog",
"homeUrl": "https://example.com/blog/",
"sectionId": 3,
"stats": {
"overall.score": {
"label": "Overall score",
"value": 70.1
}
}
}
}
}
}
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/contents": {
"get": {
"operationId": "getContents",
"summary": "List the pages and documents Silktide tested",
"description": "Lists every page and document Silktide tested on a website or one of its\nsections, a page of rows at a time. See [Content](/v1/concepts/content) for\nwhat counts as each.\n\nThe list is more than the pages a visitor would browse to. It includes error\npages (look at `httpCode`), documents linked from the website but hosted on\nanother domain, and the pages user flows reached, which have a `flowId` above\n`0`. The same URL can appear once crawled and once more for each flow step\nthat visited it.\n\nLeave out `websiteId` to list the content of every website the API key's user\ncan see, together.\n\nThis query takes `page` and `rowsPerPage` (see\n[Pagination](/v1/concepts/pagination)) but none of the table arguments:\n`columns`, `sort` and `search` are ignored. The rows come in no useful order;\nsort by `defaultOrder` to list them the way Silktide does.\n\nA `page` or `rowsPerPage` that is not a whole number of at least `1` is an\n`InvalidRequest` error whose `properties.field` names the argument. It comes\nwith status `200`, like every results error, so check for `error` before\nreading `result`.",
"tags": [
"Governance: Content"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/content/get-contents"
},
"parameters": [
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "The website. Left out, every website the API key's user can see.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`. Must be at least `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "`InvalidRequest`: `page` is not a whole number of at least `1`. The error's own `status` is `400` and `properties.field` is `page`. The body is an error despite the status. `InvalidRequest`: `rowsPerPage` is not a whole number of at least `1`. The error's own `status` is `400` and `properties.field` is `rowsPerPage`. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No website or section with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/websites/{websiteId}/sections/{sectionId}/meta": {
"get": {
"operationId": "getSectionMetadata",
"summary": "Get a section's metadata, and the properties it can have",
"description": "Returns a section's metadata values, and every metadata property the\naccount defines, so you can show the empty ones too. Section `0` is the\nwhole website. See [Metadata](/v1/governance/metadata) for what properties\nare.\n\n`values` names only the properties that have been given a value. When none\nhave, it is an empty array (`[]`) rather than an empty object, so check for\nboth before you read it by name.\n\n`isRequired`, `min`, `max`, `choices` and `allowOther` describe what a value\nis meant to be, for your own forms. Silktide does not enforce them; see\n[Set a section's metadata](/v1/governance/metadata/set-section-metadata).",
"tags": [
"Governance: Metadata"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/metadata/get-section-metadata"
},
"parameters": [
{
"name": "websiteId",
"in": "path",
"required": true,
"description": "The website.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "path",
"required": true,
"description": "The section. `0` is the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "Get a section's metadata, and the properties it can have",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"values": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"description": "The value, typed by its property: a string for `string` and `url`, a number for `int` and `float`, a boolean for `bool`.",
"type": [
"string",
"number",
"boolean"
]
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "The section's values, by property name. Only properties that have been given a value are here. An empty array (`[]`), not an object, when none have."
},
"properties": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The property's name: the key of its value in `values`."
},
"label": {
"type": "string",
"description": "Its name as people see it."
},
"propertyType": {
"type": "string",
"enum": [
"string",
"int",
"float",
"bool",
"url"
],
"description": "The type of value it holds."
},
"isRequired": {
"type": "boolean",
"description": "Whether every section is meant to have a value for it."
},
"min": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
],
"description": "The smallest value (`int`, `float`) or shortest length (`string`, `url`) it is meant to take. Null for no limit."
},
"max": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
],
"description": "The largest value or longest length it is meant to take. Null for no limit."
},
"choices": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The values to pick from. Null when it has no list."
},
"allowOther": {
"type": "boolean",
"description": "With `choices`, whether a value not in the list is meant to be allowed."
}
},
"required": [
"name",
"label",
"propertyType",
"isRequired",
"min",
"max",
"choices",
"allowOther"
],
"additionalProperties": false
},
"description": "Every metadata property the account defines for sections, in the account's order."
}
},
"required": [
"values",
"properties"
],
"additionalProperties": false
},
"example": {
"values": {
"region": "US",
"author": "Jane Doe",
"year": 2023
},
"properties": [
{
"name": "region",
"label": "Region",
"propertyType": "string",
"isRequired": true,
"min": null,
"max": null,
"choices": [
"UK",
"US",
"Europe",
"AU"
],
"allowOther": false
},
{
"name": "author",
"label": "Author",
"propertyType": "string",
"isRequired": false,
"min": null,
"max": null,
"choices": [
"John Smith",
"Jane Doe",
"Joe Bloggs"
],
"allowOther": true
},
{
"name": "year",
"label": "Year created",
"propertyType": "int",
"isRequired": false,
"min": 1995,
"max": 3000,
"choices": null,
"allowOther": false
}
]
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot see this section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No website or section with those ids exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "Can see section",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
},
"post": {
"operationId": "setSectionMetadata",
"summary": "Set some of a section's metadata",
"description": "Sets some of a section's metadata values and returns all of them, as\n[Get a section's metadata](/v1/governance/metadata/get-section-metadata)\ndoes. Section `0` is the whole website. Send only the values you want to\nchange; the rest keep theirs.\n\nSetting metadata needs \"Can admin this website\", like the website's other\nsettings. Reading it needs only \"Can see section\".\n\nEach value is checked against its property before anything is saved:\n\n- An `int` takes a whole number, and a `float` any number. Either may be\n sent as a number or as a string such as `\"2023\"`. `min` and `max` are the\n smallest and largest allowed.\n- A `bool` takes `true` or `false`, or `\"true\"`, `\"false\"`, `1` or `0`.\n- A `url` takes an `http` or `https` address.\n- A `string` takes text, at least `min` and at most `max` characters long.\n- When a property has `choices` and `allowOther` is `false`, the value must\n be one of them.\n- No value may be longer than 1,024 characters.\n\nSend `null` or `\"\"` to empty a value, unless the property `isRequired`. An\nemptied `int` reads back as `0`, and an emptied `bool` as `false`.\n\nA value equal to the one already stored is always accepted, even if it no\nlonger fits its property, so you can send every value back unchanged.\n\nIf any value is refused, nothing is saved. The answer is `400`\n`InvalidRequest`; its message says what is wrong and `properties.field`\nnames the property:\n\n```json\n{\n \"error\": {\n \"type\": \"InvalidRequest\",\n \"message\": \"Year created must be at least 1995.\",\n \"properties\": { \"field\": \"year\" }\n }\n}\n```",
"tags": [
"Governance: Metadata"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/metadata/set-section-metadata"
},
"parameters": [
{
"name": "websiteId",
"in": "path",
"required": true,
"description": "The website.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "path",
"required": true,
"description": "The section. `0` is the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"values": {
"description": "The values to set, by property name. Properties left out keep their value, and `null` or `\"\"` empties one. Each value is checked against its property. Left out, nothing changes.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
}
}
},
"example": {
"values": {
"region": "US",
"author": "Jane Doe",
"year": 2023
}
}
}
}
},
"responses": {
"200": {
"description": "Set some of a section's metadata",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"values": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"description": "The value, typed by its property: a string for `string` and `url`, a number for `int` and `float`, a boolean for `bool`.",
"type": [
"string",
"number",
"boolean"
]
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "The section's values, by property name. Only properties that have been given a value are here. An empty array (`[]`), not an object, when none have."
},
"properties": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The property's name: the key of its value in `values`."
},
"label": {
"type": "string",
"description": "Its name as people see it."
},
"propertyType": {
"type": "string",
"enum": [
"string",
"int",
"float",
"bool",
"url"
],
"description": "The type of value it holds."
},
"isRequired": {
"type": "boolean",
"description": "Whether every section is meant to have a value for it."
},
"min": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
],
"description": "The smallest value (`int`, `float`) or shortest length (`string`, `url`) it is meant to take. Null for no limit."
},
"max": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
],
"description": "The largest value or longest length it is meant to take. Null for no limit."
},
"choices": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The values to pick from. Null when it has no list."
},
"allowOther": {
"type": "boolean",
"description": "With `choices`, whether a value not in the list is meant to be allowed."
}
},
"required": [
"name",
"label",
"propertyType",
"isRequired",
"min",
"max",
"choices",
"allowOther"
],
"additionalProperties": false
},
"description": "Every metadata property the account defines for sections, in the account's order."
}
},
"required": [
"values",
"properties"
],
"additionalProperties": false
},
"example": {
"values": {
"region": "US",
"author": "Jane Doe",
"year": 2023
},
"properties": [
{
"name": "region",
"label": "Region",
"propertyType": "string",
"isRequired": true,
"min": null,
"max": null,
"choices": [
"UK",
"US",
"Europe",
"AU"
],
"allowOther": false
},
{
"name": "author",
"label": "Author",
"propertyType": "string",
"isRequired": false,
"min": null,
"max": null,
"choices": [
"John Smith",
"Jane Doe",
"Joe Bloggs"
],
"allowOther": true
},
{
"name": "year",
"label": "Year created",
"propertyType": "int",
"isRequired": false,
"min": 1995,
"max": 3000,
"choices": null,
"allowOther": false
}
]
}
}
}
},
"400": {
"description": "`InvalidRequest`: A value does not fit its property, names no property the account has, or `values` is not an object. `properties.field` names the property, and nothing is saved.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot admin this website.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No website or section with those ids exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "Can admin this website",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/flows": {
"get": {
"operationId": "getFlows",
"summary": "List a website's user flows, how reliably each runs, and the pages it reached",
"description": "Lists a website's user flows: each one's last run, how often its runs\nsucceeded over 30 and 90 days, and the page each of its steps reached.\n\nOnly live flows that have run at least once are listed. A draft, or a new\nflow that has not run yet, is left out.\n\n`pages` holds one page per step, from the flow's last run, and is not in step\norder: sort it by `stepNo`. A step that failed has `isFailedStep: true`. The\nsame pages also appear, with these `flowId`s, in\n[Get contents](/v1/governance/content/get-contents).\n\nUser flows belong to the whole website, so this query takes no `sectionId`:\none sent is ignored. Older documentation said it could be read for a section.\n\n`websiteId` is required. Without it the answer is an `InvalidRequest` error\nwhose `properties.field` is `websiteId`, with status `200`; check for `error`\nbefore reading `result`.",
"tags": [
"Governance: User flows"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/user-flows/get-flows"
},
"parameters": [
{
"name": "websiteId",
"in": "query",
"required": true,
"description": "The website.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "`InvalidRequest`: No `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `websiteId`. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No website or section with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/inspector/html-fragment-test": {
"post": {
"operationId": "testHtmlFragment",
"summary": "Test a piece of HTML for spelling, grammar and accessibility issues",
"description": "Tests a piece of HTML, such as `Our wines
` or a whole draft page,\nthere and then, and answers with what each check found. Use it to check\ncontent before you publish it. Nothing is saved, and no website is needed.\n\nOnly some checks can run on HTML alone: Silktide's own spelling, grammar,\nreadability and accessibility checks, the ones certain enough to report an\nerror. A fragment has no styles, scripts, headers or other files, so checks\nthat need them, such as color contrast or broken links, are left out, and so\nare checks from your policies. The list depends on the account, so read it\nfrom the answer rather than assuming it.\n\nA fragment is tested as a page on its own, so a short one fails page-level\nchecks such as a missing `` or page language. Ignore the checks that\ndo not apply to what you sent.\n\nSend `options` with `website.languages`. Without it, spelling and grammar\nare checked in US English.\n\nWhen the account has AI spell check turned on, the spelling check asks an AI\nmodel about each word no dictionary recognizes. That costs Silktide money,\nnot the account's balance, and makes a call take several seconds; words it\nhas seen before are answered from what it learned then.\n\nA missing or empty `html` fails with status `400` and an `InvalidRequest`\nerror whose `properties.field` is `html`.",
"tags": [
"Governance: Testing"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/testing/test-html-fragment"
},
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"html": {
"type": "string",
"minLength": 1,
"description": "The HTML to test: a whole page or part of one."
},
"url": {
"description": "The address to treat the HTML as coming from, for resolving relative links and images. Defaults to `https://example.com/`.",
"type": "string"
},
"options": {
"description": "Website settings to test with, by name, as on Update a website. Send `website.languages`, such as `[\"en-GB\"]`: it is the only way the spelling, grammar and readability checks know the language. Defaults to US English.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
},
"required": [
"html"
],
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
}
},
"example": {
"html": "<p>Our wines are <img src=\"barrel.png\"> aged in oak barels.</p>",
"options": {
"website.languages": [
"en-US"
]
}
}
}
}
},
"responses": {
"200": {
"description": "Test a piece of HTML for spelling, grammar and accessibility issues",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"checks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"checkId": {
"type": "string",
"description": "The check's id, such as `spelling`."
},
"name": {
"type": "string",
"description": "The check's short name, in the API user's language."
},
"standard": {
"type": "string",
"description": "The standard it tests against, such as `WCAG 2.0 A 1.1.1`. Can be empty."
},
"score": {
"anyOf": [
{
"type": "number",
"minimum": 0,
"maximum": 100
},
{
"type": "null"
}
],
"description": "Its score for the HTML out of 100, to two decimal places. Null when it could not test it."
},
"numIssues": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "How many issues it found."
},
"testStatus": {
"type": "string",
"description": "`tested` when the check ran. Anything else says why it could not, such as `not-enough-text` or `no-checkable-languages`."
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pointId": {
"type": "string",
"description": "The issue's id."
},
"selectors": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"text",
"css"
],
"description": "`text` to highlight some text, `css` to highlight the elements a CSS selector matches."
},
"match": {
"type": "string",
"description": "The text to find, or the CSS selector."
},
"cssSelector": {
"description": "With `type: text`, the element to look for the text in. Can be empty.",
"type": "string"
},
"caseSensitive": {
"description": "With `type: text`, whether the text must match case.",
"type": "boolean"
}
},
"required": [
"type",
"match"
],
"additionalProperties": false
}
},
{
"type": "null"
}
],
"description": "Where in the HTML the issue is. Null when it is about the HTML as a whole, such as a missing `<title>`."
},
"descriptionId": {
"description": "Which explanation of the issue applies, when its check has more than one.",
"type": "string"
},
"firstSeen": {
"type": "null",
"description": "When the issue was first seen. Always null here: a fragment has no history."
},
"newnessKeys": {
"type": "null",
"description": "Always null here."
},
"html": {
"description": "The HTML of the element at fault.",
"type": "string"
},
"htmlHash": {
"description": "A hash of `html`.",
"type": "string"
},
"text": {
"description": "The text at fault.",
"type": "string"
},
"isVisible": {
"description": "Whether the element is visible when the page loads.",
"type": "boolean"
},
"isSightVisible": {
"description": "Whether a sighted reader sees it, as opposed to text only for screen readers.",
"type": "boolean"
},
"classification": {
"description": "How the check grades the issue. For spelling: `10-error`, `15-language` (a word in another language), `20-potential` or `30-case`. For images: `10-visible` or `20-invisible`.",
"type": "string"
},
"word": {
"description": "Spelling: the word not recognized.",
"type": "string"
},
"suggestions": {
"description": "Spelling: words it may have meant. Can be empty.",
"type": "array",
"items": {
"type": "string"
}
},
"correction": {
"description": "Spelling: the word as HTML with the letters to delete in `<del>`, such as `ha<del>z</del>`. Empty when the fix needs more than deleting letters.",
"type": "string"
},
"detectedLanguage": {
"description": "Spelling: the language the word seems to be in, when it can tell.",
"type": [
"string",
"null"
]
},
"languages": {
"description": "Spelling: the languages the word was checked in.",
"type": "array",
"items": {
"type": "string"
}
},
"insideContext": {
"description": "Spelling: where the word is when it is not plain text, such as `alt`, `title`, `meta` or `screen-reader`. Empty otherwise.",
"type": "string"
},
"spellingSource": {
"description": "Spelling: what flagged the word: `hunspell` (a dictionary), `global` (Silktide's word list), `account` (the account's dictionary) or `ai` (an AI model).",
"type": "string"
},
"before": {
"description": "The text just before the issue.",
"type": "string"
},
"after": {
"description": "The text just after the issue.",
"type": "string"
},
"typo": {
"description": "Grammar: the text at fault.",
"type": "string"
},
"replacements": {
"description": "Grammar: what to replace `typo` with.",
"type": "array",
"items": {
"type": "string"
}
},
"description": {
"description": "Grammar: what is wrong, in a sentence.",
"type": "string"
},
"ruleDescription": {
"description": "Grammar: the rule that found it.",
"type": "string"
},
"grammarRuleId": {
"description": "Grammar: the rule's id.",
"type": "string"
},
"language": {
"description": "Grammar: the language of the text.",
"type": "string"
},
"src": {
"description": "Media: the URL of the image, audio or video, resolved against `url`.",
"type": "string"
},
"srcHash": {
"description": "Media: a hash of `src`.",
"type": "string"
},
"srcType": {
"description": "Media: the kind of source, such as `image`.",
"type": "string"
},
"mediaType": {
"description": "Media: `image`, `audio` or `video`.",
"type": "string"
},
"width": {
"description": "The element's width in CSS pixels. Null when unknown, as it usually is for a fragment.",
"type": [
"number",
"null"
]
},
"height": {
"description": "The element's height in CSS pixels. Null when unknown.",
"type": [
"number",
"null"
]
},
"linkUrl": {
"description": "Links: the link's URL, resolved against `url`.",
"type": "string"
},
"linkUrlHash": {
"description": "Links: a hash of `linkUrl`.",
"type": "string"
},
"linkText": {
"description": "Links: the link's accessible name.",
"type": "string"
}
},
"required": [
"pointId",
"selectors",
"firstSeen",
"newnessKeys"
],
"additionalProperties": false
},
"description": "Each issue it found. Empty when it found none."
}
},
"required": [
"checkId",
"name",
"standard",
"score",
"numIssues",
"testStatus",
"points"
],
"additionalProperties": false
},
"description": "Each check that can test a fragment of HTML, and what it found."
}
},
"required": [
"checks"
],
"additionalProperties": false
},
"example": {
"checks": [
{
"checkId": "missing-alt",
"name": "Missing alt text",
"standard": "WCAG 2.0 A 1.1.1",
"score": 66.67,
"numIssues": 1,
"testStatus": "tested",
"points": [
{
"pointId": "055b0fba2ac90a62cca156afc9f47d21",
"selectors": [
{
"match": "html>p>img",
"type": "css"
}
],
"firstSeen": null,
"newnessKeys": null,
"html": "<img src=\"barrel.png\">",
"isSightVisible": true,
"classification": "10-visible",
"src": "https://example.com/barrel.png",
"srcHash": "98bd9120b407057c1b84d7fdada63291",
"srcType": "image",
"mediaType": "image",
"before": "",
"after": "",
"width": null,
"height": null
}
]
},
{
"checkId": "readability",
"name": "Readability",
"standard": "",
"score": null,
"numIssues": 0,
"testStatus": "not-enough-text",
"points": []
},
{
"checkId": "spelling",
"name": "Spelling",
"standard": "",
"score": 39.44,
"numIssues": 1,
"testStatus": "tested",
"points": [
{
"pointId": "c5f2e207cbb58d9d26147ae6f7e94485",
"selectors": [
{
"match": "barels",
"caseSensitive": true,
"cssSelector": "html>p",
"type": "text"
}
],
"firstSeen": null,
"newnessKeys": null,
"word": "barels",
"suggestions": [
"barrels"
],
"correction": "",
"detectedLanguage": "en-US",
"classification": "10-error",
"before": " aged in oak ",
"after": ".",
"insideContext": "",
"languages": [
"en-US"
],
"isSightVisible": true,
"spellingSource": "ai"
}
]
}
]
}
}
}
},
"400": {
"description": "`InvalidRequest`: `html` is missing or empty, `url` is not text, or `options` is not an object. `properties.field` names which.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "paid"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/scores": {
"get": {
"operationId": "getScores",
"summary": "Get a website's Silktide 4 scores",
"description": "Returns every Silktide 4 score of a website or one of its sections, each as\nits latest value in the period. With no `period`, that is the latest score\nthere is.\n\nThis is for accounts that have Silktide 4. An account that has only\nSilktide 5 gets an `EditionNotAvailable` error; it reads\n[Get a website's Silktide 5 scores](/v1/governance/scores/get-module-scores)\ninstead. [Scores](/v1/concepts/scores) explains which to use.\n\nScores are out of 100 and keep one decimal place. Older documentation said\nthey were whole numbers; read them as numbers either way. A score Silktide\ncannot work out for this website, such as PDF accessibility on a website with\nno PDFs, is `null`.\n\nWebsites do not all have the same scores, so read them by id. Use an id with\n[Get how a Silktide 4 score changed](/v1/governance/scores/get-score-trend)\nto see how it changed.",
"tags": [
"Governance: Scores"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/scores/get-scores"
},
"parameters": [
{
"name": "websiteId",
"in": "query",
"required": true,
"description": "The website.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "A section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`InvalidContext`: No `websiteId` was sent. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values. The body is an error despite the status. `EditionNotAvailable`: The account does not have Silktide 4. Its `status` is `403`, and `instead` names `/v1/results/module-scores`. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No website or section with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free",
"edition": "silktide-4"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/score-trend": {
"get": {
"operationId": "getScoreTrend",
"summary": "Get how a Silktide 4 score changed over time",
"description": "Returns every measurement of one Silktide 4 score in the period, oldest\nfirst, for a website or one of its sections. Take score ids from\n[Get a website's Silktide 4 scores](/v1/governance/scores/get-scores).\n\nThis is for accounts that have Silktide 4. An account that has only\nSilktide 5 gets an `EditionNotAvailable` error; it reads\n[Get how a Silktide 5 score changed](/v1/governance/scores/get-module-score-trend)\ninstead. [Scores](/v1/concepts/scores) explains which to use.\n\nAn unknown `scoreId` is not an error: the answer is an empty list.\n\nUnlike Get Silktide 4 scores, this can return a score below `0`, Silktide's\nmarker for a score it could not work out at that time. Treat any negative\nscore, like `null`, as no score.\n\nA missing `scoreId` is an error, but it comes back with status `200` and an\n`error` body. Check for `error` before reading `result`.",
"tags": [
"Governance: Scores"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/scores/get-score-trend"
},
"parameters": [
{
"name": "scoreId",
"in": "query",
"required": true,
"description": "The score, by the id Get Silktide 4 scores uses, such as `overall`.",
"schema": {
"type": "string"
}
},
{
"name": "websiteId",
"in": "query",
"required": true,
"description": "The website.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "A section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`InvalidContext`: No `websiteId` was sent. The body is an error despite the status. `InvalidArgument`: `scoreId` is missing, or `period` is not one of its values. The body is an error despite the status. `EditionNotAvailable`: The account does not have Silktide 4. Its `status` is `403`, and `instead` names `/v1/results/module-score-trend`. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No website or section with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free",
"edition": "silktide-4"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/module-scores": {
"get": {
"operationId": "getModuleScores",
"summary": "Get a website's Silktide 5 scores",
"description": "Returns a website's scores as Silktide 5 works them out: one for each module,\nand its WCAG conformance at each version and level. Each is its latest value\nin the period. With no `period`, that is the latest score there is.\n\nThis is for accounts that have Silktide 5. An account that has only\nSilktide 4 gets an `EditionNotAvailable` error; it reads\n[Get a website's scores](/v1/governance/scores/get-scores) instead. The two\neditions score websites differently, so their numbers are not comparable.\n[Scores](/v1/concepts/scores) explains which to use.\n\nEvery id is always in the answer, so you can read the ones you need without\nchecking. A score with no value in the period, such as one for a website\nSilktide has not tested yet, is `null`.\n\nUse an id with\n[Get how a Silktide 5 score changed](/v1/governance/scores/get-module-score-trend)\nto see how it changed.",
"tags": [
"Governance: Scores"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/scores/get-module-scores"
},
"parameters": [
{
"name": "websiteId",
"in": "query",
"required": true,
"description": "The website.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "A section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`InvalidContext`: No `websiteId` was sent. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values. The body is an error despite the status. `EditionNotAvailable`: The account does not have Silktide 5. Its `status` is `403`, and `instead` names `/v1/results/scores`. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No website or section with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free",
"edition": "silktide-5"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.1.0"
}
},
"/v1/results/module-score-trend": {
"get": {
"operationId": "getModuleScoreTrend",
"summary": "Get how a Silktide 5 score changed over time",
"description": "Returns every measurement of one Silktide 5 score in the period, oldest\nfirst, for a website or one of its sections. Take score ids from\n[Get a website's Silktide 5 scores](/v1/governance/scores/get-module-scores).\n\nThis is for accounts that have Silktide 5. An account that has only\nSilktide 4 gets an `EditionNotAvailable` error; it reads\n[Get how a score changed](/v1/governance/scores/get-score-trend) instead.\n[Scores](/v1/concepts/scores) explains which to use.\n\nUnlike the Silktide 4 trend, a `scoreId` that is missing or not one of the\nvalues is refused, and the error lists the values. Scores here are never\nbelow `0`.",
"tags": [
"Governance: Scores"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/scores/get-module-score-trend"
},
"parameters": [
{
"name": "scoreId",
"in": "query",
"required": true,
"description": "The score, by the id Get Silktide 5 scores uses, such as `accessibility`.",
"schema": {
"type": "string",
"enum": [
"accessibility",
"compliance",
"content",
"user-experience",
"wcag-20-a",
"wcag-20-aa",
"wcag-20-aaa",
"wcag-21-a",
"wcag-21-aa",
"wcag-21-aaa",
"wcag-22-a",
"wcag-22-aa",
"wcag-22-aaa"
]
}
},
{
"name": "websiteId",
"in": "query",
"required": true,
"description": "The website.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "A section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`InvalidContext`: No `websiteId` was sent. The body is an error despite the status. `InvalidRequest`: `scoreId` is missing or is not one of its values. Its `status` is `400`, and `properties.scoreIds` lists the values. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values. The body is an error despite the status. `EditionNotAvailable`: The account does not have Silktide 5. Its `status` is `403`, and `instead` names `/v1/results/score-trend`. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No website or section with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free",
"edition": "silktide-5"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.1.0"
}
},
"/v1/results/checks": {
"get": {
"operationId": "getChecks",
"summary": "List a website's checks and how each is doing",
"description": "Returns every check a website or one of its sections is tested with, and\nwhere each stands now: open or done, how many issues, its score.\n\nFilter by `confidence` to see only what is certain (`error`) or only what\nneeds a person to look (`review`). `checkType` is the older filter and still\nworks; `confidence` wins when both are sent.\n\nUse a check's id with [Get check](/v1/governance/checks/get-check) for its\nhistory.",
"tags": [
"Governance: Checks"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/checks/get-checks"
},
"parameters": [
{
"name": "websiteId",
"in": "query",
"required": true,
"description": "The website.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "A section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "confidence",
"in": "query",
"required": false,
"description": "Only checks of these confidences, comma-separated: `error`, `warning`, `review`.",
"schema": {
"type": "string"
}
},
{
"name": "checkType",
"in": "query",
"required": false,
"description": "Only checks of these older types, comma-separated: `auto` or `assist`. Ignored when `confidence` is sent.",
"schema": {
"type": "string"
}
},
{
"name": "isPolicy",
"in": "query",
"required": false,
"description": "`1` for only checks from policies, `0` for only Silktide's own. Left out, both.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`InvalidContext`: No `websiteId` was sent. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No website or section with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/check": {
"get": {
"operationId": "getCheck",
"summary": "Get one check and its history",
"description": "Returns one check on a website or section: where it stands now, the same as\nin [Get checks](/v1/governance/checks/get-checks), and every past\nmeasurement of its score and issue count.\n\nThe last entry in `history` is the latest measurement again, timed at the\nmoment you asked, so a chart drawn from it runs up to now. Ignore it if you\nonly want real measurements.\n\n`history` always covers the check's whole history; this query takes no\n`period`.\n\nA `checkId` the website is not tested with is an error, but it comes back\nwith status `200` and an `error` body of type `ModelNotFound`. Check for\n`error` before reading `result`.",
"tags": [
"Governance: Checks"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/checks/get-check"
},
"parameters": [
{
"name": "checkId",
"in": "query",
"required": true,
"description": "The check, by the id Get checks returns.",
"schema": {
"type": "string"
}
},
{
"name": "websiteId",
"in": "query",
"required": true,
"description": "The website.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "A section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "`InvalidContext`: No `websiteId` was sent. The body is an error despite the status. `InvalidArgument`: `checkId` is missing. The body is an error despite the status. `ModelNotFound`: The website or section is not tested with that check. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No website or section with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/reports": {
"get": {
"operationId": "listReports",
"summary": "List reports",
"description": "Returns every report the API key's user can see, with no paging. It lists live reports (dashboards) and snapshots together; tell them apart by `isLive`.\n\nSnapshots a [report schedule](/v1/governance/report-schedules) made are here too, with that schedule's `reportScheduleId`.\n\n`context` is `[]`, not `{}`, when a report has no context of its own. Its shape for each `contextTypeId` is in [Context](/v1/concepts/context). `creatorAssigneeId` is an [assignee](/v1/platform/assignees) id.\n\nTo read what a report shows, use [Get a report's results](/v1/governance/reports/get-report-results).",
"tags": [
"Governance: Reports"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/reports/list-reports"
},
"parameters": [],
"responses": {
"200": {
"description": "List reports",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reports": {
"type": "array",
"items": {
"type": "object",
"properties": {
"reportId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The report."
},
"reportTemplateId": {
"type": "string",
"minLength": 1,
"maxLength": 16,
"description": "The report template it is made from."
},
"reportScheduleId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The report schedule that made it. `0` when it was not made by a schedule."
},
"contextTypeId": {
"type": "string",
"enum": [
"website",
"websites",
"account",
"property"
],
"description": "What kind of thing it covers, copied from its template: `website`, `websites`, `account` or `property`."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Its name."
},
"thumbnailUrl": {
"type": "string",
"description": "A small screenshot of it. Empty until one is made, a few minutes after a snapshot is created."
},
"startTime": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "For a snapshot, the start of the dates it covers. `0` for a live report."
},
"endTime": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "For a snapshot, the end of the dates it covers. `0` for a live report."
},
"durationInterval": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
],
"description": "The unit of how far back it looks."
},
"durationPeriod": {
"type": "integer",
"minimum": 0,
"maximum": 90,
"description": "How many `durationInterval`s back it looks. `week` and `4` cover the last four weeks."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it was created."
},
"creatorAssigneeId": {
"type": "string",
"description": "The assignee who created it: a user (`u:`), an API key (`a:`), or `system` for those Silktide made itself."
},
"context": {
"anyOf": [
{
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "One of its sections. `0` for the whole website."
}
},
"required": [
"websiteId",
"sectionId"
],
"additionalProperties": false,
"description": "One website or section, for the `website` type."
},
{
"type": "object",
"properties": {
"criteria": {
"type": "object",
"properties": {
"tagIds": {
"description": "Websites and sections with these tags.",
"type": "array",
"items": {
"type": "string"
}
},
"tagOperator": {
"description": "`or` (the default) for any of the tags, `and` for all of them.",
"type": "string",
"enum": [
"or",
"and"
]
},
"subsiteIds": {
"description": "These websites and sections, by subsite id. When both are set, these win over `tagIds`.",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"description": "Which websites. With none, every website the user can see."
}
},
"required": [
"criteria"
],
"additionalProperties": false,
"description": "Several websites, for the `websites` type."
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "What it covers, in the shape its `contextTypeId` takes: `{\"websiteId\": 3, \"sectionId\": 0}` for one website, `{\"criteria\": {...}}` for several. `[]` when it has none."
},
"isLive": {
"type": "boolean",
"description": "`true` for a live report (a dashboard), which is built afresh each time it is read. `false` for a snapshot, built once when it is created."
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The version of the format it is stored in, which Silktide uses to upgrade older reports. Nothing to act on."
}
},
"required": [
"reportId",
"reportTemplateId",
"reportScheduleId",
"contextTypeId",
"name",
"thumbnailUrl",
"startTime",
"endTime",
"durationInterval",
"durationPeriod",
"created",
"creatorAssigneeId",
"context",
"isLive",
"version"
],
"additionalProperties": false
},
"description": "Every report the API key's user can see, live reports and snapshots alike."
}
},
"required": [
"reports"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
}
},
"example": {
"reports": [
{
"reportId": 1,
"reportTemplateId": "websites",
"reportScheduleId": 0,
"contextTypeId": "websites",
"name": "Websites dashboard",
"thumbnailUrl": "",
"startTime": 0,
"endTime": 0,
"durationInterval": "day",
"durationPeriod": 90,
"created": 1790402302,
"creatorAssigneeId": "system",
"context": [],
"isLive": true,
"version": 3
},
{
"reportId": 6,
"reportTemplateId": "spelling",
"reportScheduleId": 0,
"contextTypeId": "website",
"name": "Spelling report for Wine Barrel",
"thumbnailUrl": "https://example-bucket.s3.amazonaws.com/reports/6/thumb.webp",
"startTime": 1791643553,
"endTime": 1794235553,
"durationInterval": "day",
"durationPeriod": 30,
"created": 1794235553,
"creatorAssigneeId": "u:eu-12",
"context": {
"websiteId": 3,
"sectionId": 0
},
"isLive": false,
"version": 3
}
]
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`EditionNotAvailable`: The account does not have Silktide 4. Reports, report schedules and report templates are Silktide 4's, so an account with only Silktide 5 cannot use them.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"edition": "silktide-4",
"permission": null,
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
},
"post": {
"operationId": "createReport",
"summary": "Create a live report or a snapshot",
"description": "Creates a report from a [report template](/v1/governance/report-templates), and builds it. The response is the new report, as [Get a report](/v1/governance/reports/get-report) returns it, with status `200`.\n\n`isLive` decides what you get, and defaults to `false`:\n\n- **A snapshot** (`false`) is built now, over the dates `durationInterval` and `durationPeriod` count back from now, and never changes. Its `startTime` and `endTime` record those dates. The request takes as long as building it.\n- **A live report** (`true`) is a dashboard: it is built afresh, over the same length of time back from then, every time you [read its results](/v1/governance/reports/get-report-results).\n\n`reportTemplateId` is required; [List report templates](/v1/governance/report-templates/list-report-templates) has them. `context` must be in the shape the template's `contextTypeId` takes (see [Context](/v1/concepts/context)). Ids may be numbers or strings of digits; they are stored as numbers. Silktide does not check it when you create the report: a context that does not fit is saved, and the report then shows no results for it.\n\nIts creator is the API key, an `a:` [assignee](/v1/platform/assignees) in `creatorAssigneeId`, and a live report is always built with its creator's permissions. Silktide names the report when you leave `name` out, such as \"Broken links dashboard\" or \"Spelling report for Wine Barrel\".",
"tags": [
"Governance: Reports"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/reports/create-report"
},
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"report": {
"type": "object",
"properties": {
"reportTemplateId": {
"type": "string",
"minLength": 1,
"maxLength": 16,
"description": "The report template to build it from. Required."
},
"name": {
"description": "Its name. Left out or empty, Silktide names it from the template and what it covers.",
"type": "string"
},
"isLive": {
"description": "`true` for a live report (a dashboard), `false` for a snapshot. Defaults to `false`.",
"type": "boolean"
},
"durationInterval": {
"description": "The unit of how far back it looks. Defaults to `day`.",
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
]
},
"durationPeriod": {
"description": "How many `durationInterval`s back it looks, up to `90`. Defaults to `30`.",
"type": "integer",
"minimum": 1,
"maximum": 90
},
"context": {
"description": "What it covers, in the shape the template's `contextTypeId` takes. Left out, it has none: a `websites` report then covers every website, and a `website` report shows no results.",
"anyOf": [
{
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "One of its sections. `0` for the whole website."
}
},
"required": [
"websiteId",
"sectionId"
],
"description": "One website or section, for the `website` type."
},
{
"type": "object",
"properties": {
"criteria": {
"type": "object",
"properties": {
"tagIds": {
"description": "Websites and sections with these tags.",
"type": "array",
"items": {
"type": "string"
}
},
"tagOperator": {
"description": "`or` (the default) for any of the tags, `and` for all of them.",
"type": "string",
"enum": [
"or",
"and"
]
},
"subsiteIds": {
"description": "These websites and sections, by subsite id. When both are set, these win over `tagIds`.",
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "Which websites. With none, every website the user can see."
}
},
"required": [
"criteria"
],
"description": "Several websites, for the `websites` type."
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
]
}
},
"required": [
"reportTemplateId"
],
"description": "The report."
}
},
"required": [
"report"
],
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
}
},
"example": {
"report": {
"reportTemplateId": "broken-links",
"isLive": true,
"durationInterval": "week",
"durationPeriod": 4,
"context": {
"websiteId": 3,
"sectionId": 0
}
}
}
}
}
},
"responses": {
"200": {
"description": "Create a live report or a snapshot",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"report": {
"type": "object",
"properties": {
"reportId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The report."
},
"reportTemplateId": {
"type": "string",
"minLength": 1,
"maxLength": 16,
"description": "The report template it is made from."
},
"reportScheduleId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The report schedule that made it. `0` when it was not made by a schedule."
},
"contextTypeId": {
"type": "string",
"enum": [
"website",
"websites",
"account",
"property"
],
"description": "What kind of thing it covers, copied from its template: `website`, `websites`, `account` or `property`."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Its name."
},
"thumbnailUrl": {
"type": "string",
"description": "A small screenshot of it. Empty until one is made, a few minutes after a snapshot is created."
},
"startTime": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "For a snapshot, the start of the dates it covers. `0` for a live report."
},
"endTime": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "For a snapshot, the end of the dates it covers. `0` for a live report."
},
"durationInterval": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
],
"description": "The unit of how far back it looks."
},
"durationPeriod": {
"type": "integer",
"minimum": 0,
"maximum": 90,
"description": "How many `durationInterval`s back it looks. `week` and `4` cover the last four weeks."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it was created."
},
"creatorAssigneeId": {
"type": "string",
"description": "The assignee who created it: a user (`u:`), an API key (`a:`), or `system` for those Silktide made itself."
},
"context": {
"anyOf": [
{
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "One of its sections. `0` for the whole website."
}
},
"required": [
"websiteId",
"sectionId"
],
"additionalProperties": false,
"description": "One website or section, for the `website` type."
},
{
"type": "object",
"properties": {
"criteria": {
"type": "object",
"properties": {
"tagIds": {
"description": "Websites and sections with these tags.",
"type": "array",
"items": {
"type": "string"
}
},
"tagOperator": {
"description": "`or` (the default) for any of the tags, `and` for all of them.",
"type": "string",
"enum": [
"or",
"and"
]
},
"subsiteIds": {
"description": "These websites and sections, by subsite id. When both are set, these win over `tagIds`.",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"description": "Which websites. With none, every website the user can see."
}
},
"required": [
"criteria"
],
"additionalProperties": false,
"description": "Several websites, for the `websites` type."
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "What it covers, in the shape its `contextTypeId` takes: `{\"websiteId\": 3, \"sectionId\": 0}` for one website, `{\"criteria\": {...}}` for several. `[]` when it has none."
},
"isLive": {
"type": "boolean",
"description": "`true` for a live report (a dashboard), which is built afresh each time it is read. `false` for a snapshot, built once when it is created."
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The version of the format it is stored in, which Silktide uses to upgrade older reports. Nothing to act on."
}
},
"required": [
"reportId",
"reportTemplateId",
"reportScheduleId",
"contextTypeId",
"name",
"thumbnailUrl",
"startTime",
"endTime",
"durationInterval",
"durationPeriod",
"created",
"creatorAssigneeId",
"context",
"isLive",
"version"
],
"additionalProperties": false,
"description": "The new report."
},
"permissions": {
"type": "object",
"properties": {
"components": {
"type": "array",
"items": {
"type": "object",
"properties": {
"permissionId": {
"type": "string",
"description": "The permission, such as `Report-ReportRead`."
},
"componentType": {
"type": "string",
"description": "What can be given it. `assignees` for users and roles."
},
"label": {
"type": "string",
"description": "Its name, such as `Can see this dashboard / snapshot`."
},
"description": {
"description": "What it allows. Null for these permissions.",
"type": [
"string",
"null"
]
},
"inheritedPermissionIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Permissions that include this one: anyone with those has this too."
},
"models": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
},
"description": "Reserved. Empty for these permissions."
}
},
"required": [
"permissionId",
"componentType",
"label",
"description",
"inheritedPermissionIds",
"models"
],
"additionalProperties": false
},
"description": "The permissions a report has: one to see it, one to admin it."
},
"componentValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who was given each permission on this report directly, as assignee ids (`u:` users, `g:` roles)."
},
"fixedValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who has each permission from elsewhere, such as account-wide roles. Changed elsewhere, not here."
}
},
"required": [
"components",
"componentValues",
"fixedValues"
],
"additionalProperties": false,
"description": "Who may see and admin the report."
}
},
"required": [
"report",
"permissions"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
},
"__schema1": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
}
]
}
}
},
"example": {
"report": {
"reportId": 5,
"reportTemplateId": "broken-links",
"reportScheduleId": 0,
"contextTypeId": "website",
"name": "Broken links dashboard",
"thumbnailUrl": "",
"startTime": 0,
"endTime": 0,
"durationInterval": "week",
"durationPeriod": 4,
"created": 1794235546,
"creatorAssigneeId": "a:3",
"context": {
"websiteId": 3,
"sectionId": 0
},
"isLive": true,
"version": 3
},
"permissions": {
"components": [
{
"permissionId": "Report-ReportRead",
"componentType": "assignees",
"label": "Can see this dashboard / snapshot",
"description": null,
"inheritedPermissionIds": [
"Report-ReportAdmin",
"Report-ReportReadAll"
],
"models": []
},
{
"permissionId": "Report-ReportAdmin",
"componentType": "assignees",
"label": "Can admin this dashboard / snapshot",
"description": null,
"inheritedPermissionIds": [
"Report-ReportAdminAll"
],
"models": []
}
],
"componentValues": {
"Report-ReportRead": [],
"Report-ReportAdmin": []
},
"fixedValues": {
"Report-ReportRead": [],
"Report-ReportAdmin": [],
"Report-ReportReadAll": [
"g:2",
"u:eu-12"
],
"Report-ReportAdminAll": [
"g:2",
"u:eu-12"
]
}
}
}
}
}
},
"400": {
"description": "`InvalidRequest`: `report` is not an object; `reportTemplateId` is missing or names no report template the API key's user can see; `name` contains `<`, `>` or control characters; `durationPeriod` is not a whole number from 1 to 90; `durationInterval` is not one of its values; or `isLive` is not true or false. `properties.field` names the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`EditionNotAvailable`: The account does not have Silktide 4. Reports, report schedules and report templates are Silktide 4's, so an account with only Silktide 5 cannot use them. `AccessDenied`: The API key's user cannot create dashboards and snapshots.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"edition": "silktide-4",
"permission": "Can create new dashboards and snapshots",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/reports/{reportId}": {
"get": {
"operationId": "getReport",
"summary": "Get a report",
"description": "Returns one report, as [List reports](/v1/governance/reports/list-reports) lists it. To read what the report shows, use [Get a report's results](/v1/governance/reports/get-report-results).\n\nAny user who can see the report can get it. When the API key's user can also admin it, the answer includes `permissions`: who may see and admin the report. For anyone else, `permissions` is left out.\n\n`POST /v1/reports/{reportId}` answers exactly the same. It takes a JSON body and ignores it.",
"tags": [
"Governance: Reports"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/reports/get-report"
},
"parameters": [
{
"name": "reportId",
"in": "path",
"required": true,
"description": "The report.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "Get a report",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"report": {
"type": "object",
"properties": {
"reportId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The report."
},
"reportTemplateId": {
"type": "string",
"minLength": 1,
"maxLength": 16,
"description": "The report template it is made from."
},
"reportScheduleId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The report schedule that made it. `0` when it was not made by a schedule."
},
"contextTypeId": {
"type": "string",
"enum": [
"website",
"websites",
"account",
"property"
],
"description": "What kind of thing it covers, copied from its template: `website`, `websites`, `account` or `property`."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Its name."
},
"thumbnailUrl": {
"type": "string",
"description": "A small screenshot of it. Empty until one is made, a few minutes after a snapshot is created."
},
"startTime": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "For a snapshot, the start of the dates it covers. `0` for a live report."
},
"endTime": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "For a snapshot, the end of the dates it covers. `0` for a live report."
},
"durationInterval": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
],
"description": "The unit of how far back it looks."
},
"durationPeriod": {
"type": "integer",
"minimum": 0,
"maximum": 90,
"description": "How many `durationInterval`s back it looks. `week` and `4` cover the last four weeks."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it was created."
},
"creatorAssigneeId": {
"type": "string",
"description": "The assignee who created it: a user (`u:`), an API key (`a:`), or `system` for those Silktide made itself."
},
"context": {
"anyOf": [
{
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "One of its sections. `0` for the whole website."
}
},
"required": [
"websiteId",
"sectionId"
],
"additionalProperties": false,
"description": "One website or section, for the `website` type."
},
{
"type": "object",
"properties": {
"criteria": {
"type": "object",
"properties": {
"tagIds": {
"description": "Websites and sections with these tags.",
"type": "array",
"items": {
"type": "string"
}
},
"tagOperator": {
"description": "`or` (the default) for any of the tags, `and` for all of them.",
"type": "string",
"enum": [
"or",
"and"
]
},
"subsiteIds": {
"description": "These websites and sections, by subsite id. When both are set, these win over `tagIds`.",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"description": "Which websites. With none, every website the user can see."
}
},
"required": [
"criteria"
],
"additionalProperties": false,
"description": "Several websites, for the `websites` type."
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "What it covers, in the shape its `contextTypeId` takes: `{\"websiteId\": 3, \"sectionId\": 0}` for one website, `{\"criteria\": {...}}` for several. `[]` when it has none."
},
"isLive": {
"type": "boolean",
"description": "`true` for a live report (a dashboard), which is built afresh each time it is read. `false` for a snapshot, built once when it is created."
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The version of the format it is stored in, which Silktide uses to upgrade older reports. Nothing to act on."
}
},
"required": [
"reportId",
"reportTemplateId",
"reportScheduleId",
"contextTypeId",
"name",
"thumbnailUrl",
"startTime",
"endTime",
"durationInterval",
"durationPeriod",
"created",
"creatorAssigneeId",
"context",
"isLive",
"version"
],
"additionalProperties": false,
"description": "The report."
},
"permissions": {
"description": "Who may see and admin the report. Only when the API key's user can admin it.",
"type": "object",
"properties": {
"components": {
"type": "array",
"items": {
"type": "object",
"properties": {
"permissionId": {
"type": "string",
"description": "The permission, such as `Report-ReportRead`."
},
"componentType": {
"type": "string",
"description": "What can be given it. `assignees` for users and roles."
},
"label": {
"type": "string",
"description": "Its name, such as `Can see this dashboard / snapshot`."
},
"description": {
"description": "What it allows. Null for these permissions.",
"type": [
"string",
"null"
]
},
"inheritedPermissionIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Permissions that include this one: anyone with those has this too."
},
"models": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
},
"description": "Reserved. Empty for these permissions."
}
},
"required": [
"permissionId",
"componentType",
"label",
"description",
"inheritedPermissionIds",
"models"
],
"additionalProperties": false
},
"description": "The permissions a report has: one to see it, one to admin it."
},
"componentValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who was given each permission on this report directly, as assignee ids (`u:` users, `g:` roles)."
},
"fixedValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who has each permission from elsewhere, such as account-wide roles. Changed elsewhere, not here."
}
},
"required": [
"components",
"componentValues",
"fixedValues"
],
"additionalProperties": false
}
},
"required": [
"report"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
},
"__schema1": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
}
]
}
}
},
"example": {
"report": {
"reportId": 2,
"reportTemplateId": "accessibility-22",
"reportScheduleId": 0,
"contextTypeId": "website",
"name": "Wine Barrel WCAG 2.2",
"thumbnailUrl": "",
"startTime": 0,
"endTime": 0,
"durationInterval": "week",
"durationPeriod": 2,
"created": 1792953607,
"creatorAssigneeId": "u:eu-12",
"context": {
"websiteId": 3,
"sectionId": 0
},
"isLive": true,
"version": 3
},
"permissions": {
"components": [
{
"permissionId": "Report-ReportRead",
"componentType": "assignees",
"label": "Can see this dashboard / snapshot",
"description": null,
"inheritedPermissionIds": [
"Report-ReportAdmin",
"Report-ReportReadAll"
],
"models": []
},
{
"permissionId": "Report-ReportAdmin",
"componentType": "assignees",
"label": "Can admin this dashboard / snapshot",
"description": null,
"inheritedPermissionIds": [
"Report-ReportAdminAll"
],
"models": []
}
],
"componentValues": {
"Report-ReportRead": [
"u:eu-14"
],
"Report-ReportAdmin": []
},
"fixedValues": {
"Report-ReportRead": [],
"Report-ReportAdmin": [],
"Report-ReportReadAll": [
"g:2",
"u:eu-12"
],
"Report-ReportAdminAll": [
"g:2",
"u:eu-12"
]
}
}
}
}
}
},
"400": {
"description": "`InvalidRequest`: `reportId` is not a whole number. `properties.field` is `reportId`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`EditionNotAvailable`: The account does not have Silktide 4. Reports, report schedules and report templates are Silktide 4's, so an account with only Silktide 5 cannot use them. `AccessDenied`: The report exists, but the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No report with that id exists in the account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"edition": "silktide-4",
"permission": "Can see this dashboard / snapshot",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
},
"put": {
"operationId": "updateReport",
"summary": "Rename a report, or change what a live report covers",
"description": "Changes a report. Send only what you want to change; the response is the whole report, as [Get a report](/v1/governance/reports/get-report) returns it.\n\nWhat you may change depends on the report:\n\n- **A live report**: `name`, `durationInterval`, `durationPeriod` and `context`.\n- **A snapshot**: only `name`. It cannot be rebuilt, so its dates and what it covers stay as they were made.\n\nAnything else you send, including a snapshot's dates or context, and `isLive` or `reportTemplateId` on any report, is ignored without an error. Check the response to see what changed. To cover something else with a snapshot, [create a new one](/v1/governance/reports/create-report).\n\n`context` replaces the whole context, and is not checked: send it in the shape the report's `contextTypeId` takes (see [Context](/v1/concepts/context)). Ids may be numbers or strings of digits; they are stored as numbers.",
"tags": [
"Governance: Reports"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/reports/update-report"
},
"parameters": [
{
"name": "reportId",
"in": "path",
"required": true,
"description": "The report.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"report": {
"description": "What to change. Fields left out keep their value.",
"type": "object",
"properties": {
"name": {
"description": "Its name.",
"type": "string",
"minLength": 1
},
"durationInterval": {
"description": "Live reports only. The unit of how far back it looks.",
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
]
},
"durationPeriod": {
"description": "Live reports only. How many `durationInterval`s back it looks, up to `90`.",
"type": "integer",
"minimum": 1,
"maximum": 90
},
"context": {
"description": "Live reports only. What it covers, in the shape its `contextTypeId` takes. Replaces the whole context.",
"anyOf": [
{
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "One of its sections. `0` for the whole website."
}
},
"required": [
"websiteId",
"sectionId"
],
"description": "One website or section, for the `website` type."
},
{
"type": "object",
"properties": {
"criteria": {
"type": "object",
"properties": {
"tagIds": {
"description": "Websites and sections with these tags.",
"type": "array",
"items": {
"type": "string"
}
},
"tagOperator": {
"description": "`or` (the default) for any of the tags, `and` for all of them.",
"type": "string",
"enum": [
"or",
"and"
]
},
"subsiteIds": {
"description": "These websites and sections, by subsite id. When both are set, these win over `tagIds`.",
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "Which websites. With none, every website the user can see."
}
},
"required": [
"criteria"
],
"description": "Several websites, for the `websites` type."
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
]
}
}
}
},
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
}
},
"example": {
"report": {
"name": "Wine Barrel shop links",
"durationInterval": "day",
"durationPeriod": 90,
"context": {
"websiteId": 3,
"sectionId": 1
}
}
}
}
}
},
"responses": {
"200": {
"description": "Rename a report, or change what a live report covers",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"report": {
"type": "object",
"properties": {
"reportId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The report."
},
"reportTemplateId": {
"type": "string",
"minLength": 1,
"maxLength": 16,
"description": "The report template it is made from."
},
"reportScheduleId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The report schedule that made it. `0` when it was not made by a schedule."
},
"contextTypeId": {
"type": "string",
"enum": [
"website",
"websites",
"account",
"property"
],
"description": "What kind of thing it covers, copied from its template: `website`, `websites`, `account` or `property`."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Its name."
},
"thumbnailUrl": {
"type": "string",
"description": "A small screenshot of it. Empty until one is made, a few minutes after a snapshot is created."
},
"startTime": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "For a snapshot, the start of the dates it covers. `0` for a live report."
},
"endTime": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "For a snapshot, the end of the dates it covers. `0` for a live report."
},
"durationInterval": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
],
"description": "The unit of how far back it looks."
},
"durationPeriod": {
"type": "integer",
"minimum": 0,
"maximum": 90,
"description": "How many `durationInterval`s back it looks. `week` and `4` cover the last four weeks."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it was created."
},
"creatorAssigneeId": {
"type": "string",
"description": "The assignee who created it: a user (`u:`), an API key (`a:`), or `system` for those Silktide made itself."
},
"context": {
"anyOf": [
{
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "One of its sections. `0` for the whole website."
}
},
"required": [
"websiteId",
"sectionId"
],
"additionalProperties": false,
"description": "One website or section, for the `website` type."
},
{
"type": "object",
"properties": {
"criteria": {
"type": "object",
"properties": {
"tagIds": {
"description": "Websites and sections with these tags.",
"type": "array",
"items": {
"type": "string"
}
},
"tagOperator": {
"description": "`or` (the default) for any of the tags, `and` for all of them.",
"type": "string",
"enum": [
"or",
"and"
]
},
"subsiteIds": {
"description": "These websites and sections, by subsite id. When both are set, these win over `tagIds`.",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"description": "Which websites. With none, every website the user can see."
}
},
"required": [
"criteria"
],
"additionalProperties": false,
"description": "Several websites, for the `websites` type."
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "What it covers, in the shape its `contextTypeId` takes: `{\"websiteId\": 3, \"sectionId\": 0}` for one website, `{\"criteria\": {...}}` for several. `[]` when it has none."
},
"isLive": {
"type": "boolean",
"description": "`true` for a live report (a dashboard), which is built afresh each time it is read. `false` for a snapshot, built once when it is created."
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The version of the format it is stored in, which Silktide uses to upgrade older reports. Nothing to act on."
}
},
"required": [
"reportId",
"reportTemplateId",
"reportScheduleId",
"contextTypeId",
"name",
"thumbnailUrl",
"startTime",
"endTime",
"durationInterval",
"durationPeriod",
"created",
"creatorAssigneeId",
"context",
"isLive",
"version"
],
"additionalProperties": false,
"description": "The report, changed."
},
"permissions": {
"type": "object",
"properties": {
"components": {
"type": "array",
"items": {
"type": "object",
"properties": {
"permissionId": {
"type": "string",
"description": "The permission, such as `Report-ReportRead`."
},
"componentType": {
"type": "string",
"description": "What can be given it. `assignees` for users and roles."
},
"label": {
"type": "string",
"description": "Its name, such as `Can see this dashboard / snapshot`."
},
"description": {
"description": "What it allows. Null for these permissions.",
"type": [
"string",
"null"
]
},
"inheritedPermissionIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Permissions that include this one: anyone with those has this too."
},
"models": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
},
"description": "Reserved. Empty for these permissions."
}
},
"required": [
"permissionId",
"componentType",
"label",
"description",
"inheritedPermissionIds",
"models"
],
"additionalProperties": false
},
"description": "The permissions a report has: one to see it, one to admin it."
},
"componentValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who was given each permission on this report directly, as assignee ids (`u:` users, `g:` roles)."
},
"fixedValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who has each permission from elsewhere, such as account-wide roles. Changed elsewhere, not here."
}
},
"required": [
"components",
"componentValues",
"fixedValues"
],
"additionalProperties": false,
"description": "Who may see and admin the report."
}
},
"required": [
"report",
"permissions"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
},
"__schema1": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
}
]
}
}
},
"example": {
"report": {
"reportId": 5,
"reportTemplateId": "broken-links",
"reportScheduleId": 0,
"contextTypeId": "website",
"name": "Wine Barrel shop links",
"thumbnailUrl": "",
"startTime": 0,
"endTime": 0,
"durationInterval": "day",
"durationPeriod": 90,
"created": 1794235546,
"creatorAssigneeId": "a:3",
"context": {
"websiteId": 3,
"sectionId": 1
},
"isLive": true,
"version": 3
},
"permissions": {
"components": [
{
"permissionId": "Report-ReportRead",
"componentType": "assignees",
"label": "Can see this dashboard / snapshot",
"description": null,
"inheritedPermissionIds": [
"Report-ReportAdmin",
"Report-ReportReadAll"
],
"models": []
},
{
"permissionId": "Report-ReportAdmin",
"componentType": "assignees",
"label": "Can admin this dashboard / snapshot",
"description": null,
"inheritedPermissionIds": [
"Report-ReportAdminAll"
],
"models": []
}
],
"componentValues": {
"Report-ReportRead": [],
"Report-ReportAdmin": []
},
"fixedValues": {
"Report-ReportRead": [],
"Report-ReportAdmin": [],
"Report-ReportReadAll": [
"g:2",
"u:eu-12"
],
"Report-ReportAdminAll": [
"g:2",
"u:eu-12"
]
}
}
}
}
}
},
"400": {
"description": "`InvalidRequest`: `reportId` is not a whole number. `properties.field` is `reportId`. `InvalidRequest`: `report` or `permissions` is not an object, or a changed value does not fit: `name` is empty or contains `<`, `>` or control characters, `durationPeriod` is not a whole number from 1 to 90, or `durationInterval` is not one of its values. Values equal to the stored ones are not checked. `properties.field` names the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`EditionNotAvailable`: The account does not have Silktide 4. Reports, report schedules and report templates are Silktide 4's, so an account with only Silktide 5 cannot use them. `AccessDenied`: The API key's user cannot see or admin the report.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No report with that id exists in the account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"edition": "silktide-4",
"permission": "Can admin this dashboard / snapshot",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
},
"delete": {
"operationId": "deleteReport",
"summary": "Delete a report",
"description": "Deletes a report and its results at once. It cannot be undone.\n\nThe response is an empty `201`. Deleting it again returns `404`.\n\nDeleting a snapshot a [report schedule](/v1/governance/report-schedules) made leaves the schedule as it is, and it goes on making new ones.",
"tags": [
"Governance: Reports"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/reports/delete-report"
},
"parameters": [
{
"name": "reportId",
"in": "path",
"required": true,
"description": "The report.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"201": {
"description": "Delete a report"
},
"400": {
"description": "`InvalidRequest`: `reportId` is not a whole number. `properties.field` is `reportId`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`EditionNotAvailable`: The account does not have Silktide 4. Reports, report schedules and report templates are Silktide 4's, so an account with only Silktide 5 cannot use them. `AccessDenied`: The API key's user cannot see or admin the report.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No report with that id exists in the account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"edition": "silktide-4",
"permission": "Can admin this dashboard / snapshot",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/reports/{reportId}/results": {
"get": {
"operationId": "getReportResults",
"summary": "Get what a report shows",
"description": "Returns what a report shows: the template it is built from, the template's widgets, and each widget's results under its `widgetId`. Lay the widgets out with the template's `rows` and each widget's `row`, `column` and `order`.\n\nA live report is built when you ask, over the dates it covers counted back from now, as the user who created it. A snapshot returns what it held when it was made, and never changes.\n\n## Each widget's results\n\nWhat a widget sends depends on its `uiId`. Every widget sends the same title bar, `resultState` and display fields. A `Score` adds the score, a `Table` a page of `rows`, a `Chart` its `series`, and so on. Check `resultState` before you read them: anything other than `ok` means the widget has nothing to show, and says why.\n\nTables and charts also send settings for drawing them on Silktide's own screens, which this page does not list and which can change. For a table's rows in a stable shape, read the same data through [results](/v1/concepts/results) instead.\n\n## A live report for another website\n\n`POST /v1/reports/{reportId}/results` answers the same as `GET`, and takes options as a JSON body. Send `context` to build a live report for something else of the same `contextTypeId` without changing the report:\n\n```json\n{ \"context\": { \"websiteId\": 2, \"sectionId\": 0 } }\n```\n\nThe shapes are in [Context](/v1/concepts/context). A `GET` can send it in the query string instead, as `context[websiteId]=2&context[sectionId]=0`. A context that names nothing the API key's user can see falls back to the whole account, so a website widget then shows a `Message` that no website is selected. A snapshot ignores `context`.\n\n## Errors worth knowing\n\nA live report is built with its creator's permissions. If its creator no longer exists, such as a user who has left the account, it cannot be built, and this answers `403` with `AccessDenied`. A snapshot is unaffected.\n\nA snapshot whose results could not be built when it was made has none to return, and answers `404` with `NotFound`.",
"tags": [
"Governance: Reports"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/reports/get-report-results"
},
"parameters": [
{
"name": "reportId",
"in": "path",
"required": true,
"description": "The report.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "Get what a report shows",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"report": {
"type": "object",
"properties": {
"reportId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The report."
},
"reportTemplateId": {
"type": "string",
"minLength": 1,
"maxLength": 16,
"description": "The report template it is made from."
},
"reportScheduleId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The report schedule that made it. `0` when it was not made by a schedule."
},
"contextTypeId": {
"type": "string",
"enum": [
"website",
"websites",
"account",
"property"
],
"description": "What kind of thing it covers, copied from its template: `website`, `websites`, `account` or `property`."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Its name."
},
"thumbnailUrl": {
"type": "string",
"description": "A small screenshot of it. Empty until one is made, a few minutes after a snapshot is created."
},
"startTime": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "For a snapshot, the start of the dates it covers. `0` for a live report."
},
"endTime": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "For a snapshot, the end of the dates it covers. `0` for a live report."
},
"durationInterval": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
],
"description": "The unit of how far back it looks."
},
"durationPeriod": {
"type": "integer",
"minimum": 0,
"maximum": 90,
"description": "How many `durationInterval`s back it looks. `week` and `4` cover the last four weeks."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it was created."
},
"creatorAssigneeId": {
"type": "string",
"description": "The assignee who created it: a user (`u:`), an API key (`a:`), or `system` for those Silktide made itself."
},
"context": {
"anyOf": [
{
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "One of its sections. `0` for the whole website."
}
},
"required": [
"websiteId",
"sectionId"
],
"additionalProperties": false,
"description": "One website or section, for the `website` type."
},
{
"type": "object",
"properties": {
"criteria": {
"type": "object",
"properties": {
"tagIds": {
"description": "Websites and sections with these tags.",
"type": "array",
"items": {
"type": "string"
}
},
"tagOperator": {
"description": "`or` (the default) for any of the tags, `and` for all of them.",
"type": "string",
"enum": [
"or",
"and"
]
},
"subsiteIds": {
"description": "These websites and sections, by subsite id. When both are set, these win over `tagIds`.",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"description": "Which websites. With none, every website the user can see."
}
},
"required": [
"criteria"
],
"additionalProperties": false,
"description": "Several websites, for the `websites` type."
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "What it covers, in the shape its `contextTypeId` takes: `{\"websiteId\": 3, \"sectionId\": 0}` for one website, `{\"criteria\": {...}}` for several. `[]` when it has none."
},
"isLive": {
"type": "boolean",
"description": "`true` for a live report (a dashboard), which is built afresh each time it is read. `false` for a snapshot, built once when it is created."
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The version of the format it is stored in, which Silktide uses to upgrade older reports. Nothing to act on."
}
},
"required": [
"reportId",
"reportTemplateId",
"reportScheduleId",
"contextTypeId",
"name",
"thumbnailUrl",
"startTime",
"endTime",
"durationInterval",
"durationPeriod",
"created",
"creatorAssigneeId",
"context",
"isLive",
"version"
],
"additionalProperties": false,
"description": "The report, as Get a report returns it."
},
"reportId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The report again."
},
"reportTemplate": {
"type": "object",
"properties": {
"reportTemplateId": {
"type": "string",
"minLength": 1,
"maxLength": 16,
"description": "The template's id, such as `broken-links`."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Its name, as Silktide shows it."
},
"description": {
"type": "string",
"maxLength": 255,
"description": "What it is for, as Silktide shows it. Can be empty."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"columns": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "How many widgets sit side by side in this row."
}
},
"required": [
"columns"
],
"additionalProperties": false
},
"description": "Its layout, one entry per row of widgets, top to bottom."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it was created."
},
"creatorAssigneeId": {
"type": "string",
"description": "The assignee who created it: a user (`u:`), an API key (`a:`), or `system` for those Silktide made itself."
},
"contextTypeId": {
"type": "string",
"enum": [
"website",
"websites",
"account",
"property"
],
"description": "What kind of thing a report made from it covers: `website`, `websites`, `account` or `property`."
},
"context": {
"anyOf": [
{
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "One of its sections. `0` for the whole website."
}
},
"required": [
"websiteId",
"sectionId"
],
"additionalProperties": false,
"description": "One website or section, for the `website` type."
},
{
"type": "object",
"properties": {
"criteria": {
"type": "object",
"properties": {
"tagIds": {
"description": "Websites and sections with these tags.",
"type": "array",
"items": {
"type": "string"
}
},
"tagOperator": {
"description": "`or` (the default) for any of the tags, `and` for all of them.",
"type": "string",
"enum": [
"or",
"and"
]
},
"subsiteIds": {
"description": "These websites and sections, by subsite id. When both are set, these win over `tagIds`.",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"description": "Which websites. With none, every website the user can see."
}
},
"required": [
"criteria"
],
"additionalProperties": false,
"description": "Several websites, for the `websites` type."
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "The context its author built it with in Silktide. Reports made from it do not take it: send each report's own `context`. `[]` when it has none."
},
"isCustom": {
"type": "boolean",
"description": "`true` if someone in the account made it, `false` if it comes with Silktide."
},
"isDisabled": {
"type": "boolean",
"description": "`true` when Silktide has switched it off. Live reports made from it cannot be read until it is switched back on."
}
},
"required": [
"reportTemplateId",
"name",
"description",
"rows",
"created",
"creatorAssigneeId",
"contextTypeId",
"context",
"isCustom",
"isDisabled"
],
"additionalProperties": false,
"description": "The template the results were built from. For a snapshot, as it was when the snapshot was made."
},
"widgets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"widgetId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The widget. Its results are under this id in `results`."
},
"reportTemplateId": {
"type": "string",
"minLength": 1,
"maxLength": 16,
"description": "The template the widget belongs to."
},
"widgetTypeId": {
"type": "string",
"description": "What kind of widget it is, such as `Website/Score/Score`."
},
"row": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The row it is in, from `0`, as in the template's `rows`."
},
"column": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The column it is in within its row, from `0`."
},
"order": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Its place among widgets in the same row and column, from `0`."
},
"options": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema2"
},
"description": "How the widget is set up, such as its `name` and which score it shows. Depends on `widgetTypeId`."
},
"contextTypeId": {
"type": "string",
"description": "The kind of context the widget is locked to. Empty when it uses the report's context."
},
"context": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema3"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "The context the widget is locked to. `[]` when it uses the report's context."
},
"filters": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema4"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "Filters the widget starts with, such as a table's sort. `[]` when it has none."
}
},
"required": [
"widgetId",
"reportTemplateId",
"widgetTypeId",
"row",
"column",
"order",
"options",
"contextTypeId",
"context",
"filters"
],
"additionalProperties": false
},
"description": "The template's widgets, with every option filled in."
},
"results": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"uiId": {
"type": "string",
"description": "How the results are shown, which decides the fields beyond these: `Score`, `Table`, `Chart`, `Heading`, `Message`, `Number`, `Markdown` and others."
},
"resultState": {
"type": "string",
"enum": [
"ok",
"pending",
"impossible",
"empty-dates",
"not-tested-recently",
"no-history"
],
"description": "`ok`, or why there is nothing to show: `pending` (not ready yet, try again), `impossible` (cannot work here, such as no pages), `empty-dates` (nothing in these dates), `not-tested-recently` or `no-history`."
},
"header": {
"type": "object",
"properties": {
"name": {
"description": "The widget's title.",
"type": [
"string",
"null"
]
},
"contextLabels": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"description": "What it names, such as a website's name."
},
"contextLabelTypeId": {
"type": "string",
"description": "What kind of thing it names, such as `allWebsites`."
}
},
"required": [
"label",
"contextLabelTypeId"
],
"additionalProperties": false
},
"description": "Labels for what the widget covers. Empty when the widget hides them."
},
"value": {
"description": "A headline number shown in the title. Null for most widgets.",
"type": [
"number",
"null"
]
},
"decimals": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Decimal places to show `value` with."
}
},
"required": [
"name",
"contextLabels",
"value",
"decimals"
],
"additionalProperties": false,
"description": "The widget's title bar."
},
"footer": {
"type": "object",
"properties": {
"text": {
"description": "Text shown under the widget. Absent when it has none.",
"type": "string"
}
},
"additionalProperties": false,
"description": "The widget's footer."
},
"helpText": {
"description": "Deprecated. A short tip for the widget, usually null.",
"type": [
"string",
"null"
]
},
"helpUrl": {
"description": "Deprecated. A page that explains the widget, usually null.",
"type": [
"string",
"null"
]
},
"canAddToDashboard": {
"description": "Whether Silktide lets the widget be added to a dashboard. Absent for `Message`.",
"type": "boolean"
},
"controls": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema5"
},
"description": "Buttons Silktide shows on the widget. Usually empty."
},
"instruction": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema6"
}
},
{
"type": "null"
}
],
"description": "Where Silktide goes when the widget's title is clicked. Null when nowhere."
},
"buildDuration": {
"type": "number",
"minimum": 0,
"description": "Seconds Silktide took to build the widget's results."
},
"isOutOfDate": {
"type": "boolean",
"description": "`true` when the results were served from a cache and may be behind."
},
"showBackground": {
"type": "boolean",
"description": "Whether Silktide draws the widget on a card."
},
"exportFormats": {
"type": "array",
"items": {
"type": "string"
},
"description": "Formats the widget can be exported in, such as `csv`. Can be empty."
},
"score": {
"description": "`Score`: the score now, out of 100. Null when it cannot be scored.",
"anyOf": [
{
"type": "number",
"minimum": 0,
"maximum": 100
},
{
"type": "null"
}
]
},
"lastScore": {
"description": "`Score`: the score at the start of the report's dates. Null when there was none.",
"anyOf": [
{
"type": "number",
"minimum": 0,
"maximum": 100
},
{
"type": "null"
}
]
},
"approved": {
"description": "`Score`: approved decisions affecting the score. Null when unknown.",
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"ignored": {
"description": "`Score`: ignored decisions affecting the score. Null when unknown.",
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"fixed": {
"description": "`Score`: issues marked as fixed that still count toward the score. Null when unknown.",
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"scoreOverTime": {
"description": "`Score`: the score's history, each as `[timestamp, score, resultState]`. Often empty.",
"type": "array",
"items": {
"$ref": "#/$defs/__schema7"
}
},
"text": {
"description": "`Heading`: the heading.",
"type": [
"string",
"null"
]
},
"level": {
"description": "`Heading`: its level, `1` being the largest.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"title": {
"description": "`Message`: the message's title. (A `Chart` sends its own display title here.)",
"$ref": "#/$defs/__schema8"
},
"description": {
"description": "`Message`: the message, such as why the widget cannot show anything.",
"type": "string"
},
"entityName": {
"description": "`Table`: what each row is, such as `Websites`.",
"type": "string"
},
"key": {
"description": "`Table`: the column that identifies a row, such as `pointId`.",
"type": "string"
},
"columns": {
"description": "`Table`: its columns, each with a `columnId` (the row field it shows) and a `label`.",
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema9"
}
}
},
"rows": {
"description": "`Table`: the rows on this page. Their fields depend on the table.",
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema10"
}
}
},
"page": {
"description": "`Table`: the page of rows returned, from `1`.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"minPage": {
"description": "`Table`: the first page. Always `1`.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"maxPage": {
"description": "`Table`: the last page. `0` when there are no rows.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"numRows": {
"description": "`Table`: how many rows there are across every page.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"rowsPerPage": {
"description": "`Table`: how many rows a page holds.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"series": {
"description": "`Chart`: its lines, each with a `name` and `data` as `[milliseconds, value]` pairs.",
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema11"
}
}
}
},
"required": [
"uiId",
"resultState",
"header",
"footer",
"helpText",
"helpUrl",
"controls",
"instruction",
"buildDuration",
"isOutOfDate",
"showBackground",
"exportFormats"
],
"additionalProperties": {}
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "Each widget's results, by `widgetId`. `[]` when the template has no widgets."
},
"time": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When the results were built: now for a live report, when it was made for a snapshot."
}
},
"required": [
"report",
"reportId",
"reportTemplate",
"widgets",
"results",
"time"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
},
"__schema1": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
}
]
},
"__schema2": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema2"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema2"
}
}
]
},
"__schema3": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema3"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema3"
}
}
]
},
"__schema4": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema4"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema4"
}
}
]
},
"__schema5": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema5"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema5"
}
}
]
},
"__schema6": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema6"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema6"
}
}
]
},
"__schema7": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema7"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema7"
}
}
]
},
"__schema8": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema8"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema8"
}
}
]
},
"__schema9": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema9"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema9"
}
}
]
},
"__schema10": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema10"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema10"
}
}
]
},
"__schema11": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema11"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema11"
}
}
]
}
}
},
"example": {
"report": {
"reportId": 2,
"reportTemplateId": "accessibility-22",
"reportScheduleId": 0,
"contextTypeId": "website",
"name": "Wine Barrel WCAG 2.2",
"thumbnailUrl": "",
"startTime": 0,
"endTime": 0,
"durationInterval": "week",
"durationPeriod": 2,
"created": 1792953607,
"creatorAssigneeId": "u:eu-12",
"context": {
"websiteId": 3,
"sectionId": 0
},
"isLive": true,
"version": 3
},
"reportId": 2,
"reportTemplate": {
"reportTemplateId": "accessibility-22",
"name": "WCAG 2.2 summary",
"description": "Summarize WCAG 2.2 standards for a specific website or section.",
"rows": [
{
"columns": 1
},
{
"columns": 1
}
],
"created": 1704913002,
"creatorAssigneeId": "u:eu-12",
"contextTypeId": "website",
"context": [],
"isCustom": true,
"isDisabled": false
},
"widgets": [
{
"widgetId": 28,
"reportTemplateId": "accessibility-22",
"widgetTypeId": "Website/Presentation/Heading",
"row": 0,
"column": 0,
"order": 0,
"options": {
"name": "Heading",
"text": "Accessibility scores",
"level": "2",
"showBackground": false,
"hideContextLabels": true
},
"contextTypeId": "",
"context": [],
"filters": []
},
{
"widgetId": 29,
"reportTemplateId": "accessibility-22",
"widgetTypeId": "Website/Score/Score",
"row": 1,
"column": 0,
"order": 0,
"options": {
"name": "WCAG 2.2 score",
"categoryId": "wcag-22",
"helpText": null,
"helpUrl": null,
"hideContextLabels": true
},
"contextTypeId": "",
"context": [],
"filters": []
}
],
"results": {
"28": {
"uiId": "Heading",
"resultState": "ok",
"header": {
"name": "Heading",
"contextLabels": [],
"value": null,
"decimals": 0
},
"footer": {},
"helpText": null,
"helpUrl": null,
"canAddToDashboard": true,
"controls": [],
"instruction": null,
"buildDuration": 0.001,
"isOutOfDate": false,
"showBackground": false,
"exportFormats": [],
"text": "Accessibility scores",
"level": 2
},
"29": {
"uiId": "Score",
"resultState": "ok",
"header": {
"name": "WCAG 2.2 score",
"contextLabels": [],
"value": null,
"decimals": 0
},
"footer": {},
"helpText": null,
"helpUrl": null,
"canAddToDashboard": true,
"controls": [],
"instruction": null,
"buildDuration": 0.016,
"isOutOfDate": false,
"showBackground": true,
"exportFormats": [
"csv"
],
"score": 20.2,
"lastScore": null,
"approved": null,
"ignored": null,
"fixed": null,
"scoreOverTime": []
}
},
"time": 1794235487
}
}
}
},
"400": {
"description": "`InvalidRequest`: `reportId` is not a whole number. `properties.field` is `reportId`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`EditionNotAvailable`: The account does not have Silktide 4. Reports, report schedules and report templates are Silktide 4's, so an account with only Silktide 5 cannot use them. `AccessDenied`: The API key's user cannot see the report, or a live report cannot be built: its creator no longer exists, or Silktide has switched its template off.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No report with that id exists in the account. `NotFound`: The report is a snapshot with no results, because they could not be built when it was made.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"edition": "silktide-4",
"permission": "Can see this dashboard / snapshot",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/report-schedules": {
"get": {
"operationId": "listReportSchedules",
"summary": "List report schedules",
"description": "Returns every report schedule the API key's user can see, with no paging.\n\nEach schedule lists the users and roles it emails as `assigneesIds`, but not the other email addresses it sends to. For those, and for who may see and admin a schedule, use [Get a report schedule](/v1/governance/report-schedules/get-report-schedule), which returns the same users and roles as `subscribers.assigneeIds`.\n\n`assigneesIds` and `creatorAssigneeId` are [assignee](/v1/platform/assignees) ids. The snapshots a schedule has made are in [List reports](/v1/governance/reports/list-reports), with its `reportScheduleId`.\n\nA schedule with a non-null `skipped` did not run when it was last due, and says why. It needs nothing from you: it runs again by itself once the reason has gone.",
"tags": [
"Governance: Report schedules"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/report-schedules/list-report-schedules"
},
"parameters": [],
"responses": {
"200": {
"description": "List report schedules",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reportSchedules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"reportScheduleId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The report schedule."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Its name. The snapshots it makes are named from their template, not from this."
},
"reportTemplateId": {
"type": "string",
"minLength": 1,
"maxLength": 16,
"description": "The report template each snapshot is built from."
},
"context": {
"anyOf": [
{
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "One of its sections. `0` for the whole website."
}
},
"required": [
"websiteId",
"sectionId"
],
"additionalProperties": false,
"description": "One website or section, for the `website` type."
},
{
"type": "object",
"properties": {
"criteria": {
"type": "object",
"properties": {
"tagIds": {
"description": "Websites and sections with these tags.",
"type": "array",
"items": {
"type": "string"
}
},
"tagOperator": {
"description": "`or` (the default) for any of the tags, `and` for all of them.",
"type": "string",
"enum": [
"or",
"and"
]
},
"subsiteIds": {
"description": "These websites and sections, by subsite id. When both are set, these win over `tagIds`.",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"description": "Which websites. With none, every website the user can see."
}
},
"required": [
"criteria"
],
"additionalProperties": false,
"description": "Several websites, for the `websites` type."
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "What it covers, in the shape its `contextTypeId` takes: `{\"websiteId\": 3, \"sectionId\": 0}` for one website, `{\"criteria\": {...}}` for several. `[]` when it has none."
},
"emailSubject": {
"type": "string",
"maxLength": 255,
"description": "The subject of the email subscribers get. Empty for the default, the snapshot's name followed by \"is ready\"."
},
"emailMessage": {
"type": "string",
"maxLength": 4096,
"description": "Text at the top of the email subscribers get. Can be empty."
},
"scheduleInterval": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
],
"description": "The unit of how often it runs."
},
"schedulePeriod": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 90,
"description": "How many `scheduleInterval`s apart runs are. `week` and `2` runs every two weeks."
},
"scheduleFromDate": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When the schedule counts from. Each run falls a whole number of periods after it."
},
"durationInterval": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
],
"description": "The unit of how far back each snapshot looks."
},
"durationPeriod": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 90,
"description": "How many `durationInterval`s back each snapshot looks, from when it runs."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it was created."
},
"lastRun": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it last made a snapshot. `0` if never."
},
"nextDue": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it next runs. In the past when a run is waiting to be picked up."
},
"creatorAssigneeId": {
"type": "string",
"description": "The assignee who created it: a user (`u:`), an API key (`a:`), or `system` for those Silktide made itself."
},
"skipped": {
"anyOf": [
{
"type": "object",
"properties": {
"at": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When the run was due."
},
"reason": {
"type": "string",
"description": "Why it was skipped, as a stable id: `no-platform-access` when the account has no active plan."
},
"message": {
"description": "The reason, in the API user's language. Null for a reason without one.",
"type": [
"string",
"null"
]
}
},
"required": [
"at",
"reason",
"message"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Null, or why its last due run made no snapshot and sent no email. It runs again by itself once the reason has gone."
},
"assigneesIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Users and roles emailed when it runs, as assignee ids. Note the spelling: `assigneesIds`, with an s."
}
},
"required": [
"reportScheduleId",
"name",
"reportTemplateId",
"context",
"emailSubject",
"emailMessage",
"scheduleInterval",
"schedulePeriod",
"scheduleFromDate",
"durationInterval",
"durationPeriod",
"created",
"lastRun",
"nextDue",
"creatorAssigneeId",
"skipped",
"assigneesIds"
],
"additionalProperties": false
},
"description": "Every report schedule the API key's user can see."
}
},
"required": [
"reportSchedules"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
}
},
"example": {
"reportSchedules": [
{
"reportScheduleId": 1,
"name": "Broken links report for Wine Barrel",
"reportTemplateId": "broken-links",
"context": {
"websiteId": 3,
"sectionId": 0
},
"emailSubject": "Monthly broken links",
"emailMessage": "Fix these first.",
"scheduleInterval": "month",
"schedulePeriod": 1,
"scheduleFromDate": 1793577600,
"durationInterval": "day",
"durationPeriod": 30,
"created": 1793520000,
"lastRun": 1796169600,
"nextDue": 1798761600,
"creatorAssigneeId": "u:eu-12",
"assigneesIds": [
"u:eu-12",
"g:4"
],
"skipped": null
}
]
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`EditionNotAvailable`: The account does not have Silktide 4. Reports, report schedules and report templates are Silktide 4's, so an account with only Silktide 5 cannot use them.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"edition": "silktide-4",
"permission": null,
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
},
"post": {
"operationId": "createReportSchedule",
"summary": "Create a report schedule",
"description": "Creates a report schedule: on each run it makes a snapshot from a [report template](/v1/governance/report-templates) and emails it to its subscribers. The response is the new schedule, as [Get a report schedule](/v1/governance/report-schedules/get-report-schedule) returns it, with status `200`.\n\nThe first run is due at `scheduleFromDate`, and then every `schedulePeriod` `scheduleInterval`s after it (see [Schedules](/v1/concepts/schedules)). `scheduleFromDate` defaults to now, so a schedule made without one makes its first snapshot and sends its first emails soon after you create it. Set it in the future if you are not ready.\n\nEach snapshot covers the `durationPeriod` `durationInterval`s up to when it runs, and lands in [List reports](/v1/governance/reports/list-reports) with the schedule's `reportScheduleId`.\n\nSubscribers are optional and can be set later. Send them as `subscribers.assigneeIds` and `subscribers.emails`, beside `reportSchedule`, not inside it. (The old documentation listed `assigneesIds` among the schedule's own fields; that is only how [List report schedules](/v1/governance/report-schedules/list-report-schedules) names them.) Silktide does not check `assigneeIds`: an id that names nobody is kept, and nobody gets that email. Email addresses are trimmed, lowercased and deduplicated.\n\n`context` is not checked either: send it in the shape the template's `contextTypeId` takes (see [Context](/v1/concepts/context)), with ids as numbers.\n\nThe schedule runs with its creator's permissions, here the API key's.",
"tags": [
"Governance: Report schedules"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/report-schedules/create-report-schedule"
},
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reportSchedule": {
"type": "object",
"properties": {
"reportTemplateId": {
"type": "string",
"minLength": 1,
"maxLength": 16,
"description": "The report template to build each snapshot from. Required."
},
"name": {
"description": "Its name, in plain text. Left out or empty, Silktide names it from the template and what it covers.",
"type": "string"
},
"context": {
"description": "What each snapshot covers, in the shape the template's `contextTypeId` takes. Left out, it has none.",
"anyOf": [
{
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "One of its sections. `0` for the whole website."
}
},
"required": [
"websiteId",
"sectionId"
],
"description": "One website or section, for the `website` type."
},
{
"type": "object",
"properties": {
"criteria": {
"type": "object",
"properties": {
"tagIds": {
"description": "Websites and sections with these tags.",
"type": "array",
"items": {
"type": "string"
}
},
"tagOperator": {
"description": "`or` (the default) for any of the tags, `and` for all of them.",
"type": "string",
"enum": [
"or",
"and"
]
},
"subsiteIds": {
"description": "These websites and sections, by subsite id. When both are set, these win over `tagIds`.",
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "Which websites. With none, every website the user can see."
}
},
"required": [
"criteria"
],
"description": "Several websites, for the `websites` type."
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
]
},
"scheduleInterval": {
"description": "The unit of how often it runs. Defaults to `week`.",
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
]
},
"schedulePeriod": {
"description": "How many `scheduleInterval`s apart runs are, from `1` to `90`. Defaults to `1`.",
"type": "integer",
"minimum": 1,
"maximum": 90
},
"scheduleFromDate": {
"description": "When the schedule counts from, and when it first runs. Defaults to now.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"durationInterval": {
"description": "The unit of how far back each snapshot looks. Defaults to `day`.",
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
]
},
"durationPeriod": {
"description": "How many `durationInterval`s back each snapshot looks, from `1` to `90`. Defaults to `90`.",
"type": "integer",
"minimum": 1,
"maximum": 90
},
"emailSubject": {
"description": "The email's subject, in plain text. Defaults to the snapshot's name followed by \"is ready\".",
"type": "string",
"maxLength": 255
},
"emailMessage": {
"description": "Text to put at the top of the email, in plain text. Line breaks are kept.",
"type": "string",
"maxLength": 4096
}
},
"required": [
"reportTemplateId"
],
"description": "The report schedule."
},
"subscribers": {
"description": "Who is emailed each snapshot.",
"type": "object",
"properties": {
"assigneeIds": {
"description": "Users and roles to email, as assignee ids. Replaces the list; left out, it is kept.",
"type": "array",
"items": {
"type": "string"
}
},
"emails": {
"description": "Other email addresses to send it to. Replaces the list; left out, it is kept.",
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"required": [
"reportSchedule"
],
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
}
},
"example": {
"reportSchedule": {
"name": "Weekly pre-production website summary",
"reportTemplateId": "websites",
"context": {
"criteria": {
"tagIds": [
"pre-production"
]
}
},
"scheduleInterval": "week",
"schedulePeriod": 1,
"scheduleFromDate": 1796428800,
"durationInterval": "day",
"durationPeriod": 7
},
"subscribers": {
"assigneeIds": [
"u:eu-12",
"u:eu-14"
],
"emails": [
"web-team@example.com"
]
}
}
}
}
},
"responses": {
"200": {
"description": "Create a report schedule",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reportSchedule": {
"type": "object",
"properties": {
"reportScheduleId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The report schedule."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Its name. The snapshots it makes are named from their template, not from this."
},
"reportTemplateId": {
"type": "string",
"minLength": 1,
"maxLength": 16,
"description": "The report template each snapshot is built from."
},
"context": {
"anyOf": [
{
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "One of its sections. `0` for the whole website."
}
},
"required": [
"websiteId",
"sectionId"
],
"additionalProperties": false,
"description": "One website or section, for the `website` type."
},
{
"type": "object",
"properties": {
"criteria": {
"type": "object",
"properties": {
"tagIds": {
"description": "Websites and sections with these tags.",
"type": "array",
"items": {
"type": "string"
}
},
"tagOperator": {
"description": "`or` (the default) for any of the tags, `and` for all of them.",
"type": "string",
"enum": [
"or",
"and"
]
},
"subsiteIds": {
"description": "These websites and sections, by subsite id. When both are set, these win over `tagIds`.",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"description": "Which websites. With none, every website the user can see."
}
},
"required": [
"criteria"
],
"additionalProperties": false,
"description": "Several websites, for the `websites` type."
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "What it covers, in the shape its `contextTypeId` takes: `{\"websiteId\": 3, \"sectionId\": 0}` for one website, `{\"criteria\": {...}}` for several. `[]` when it has none."
},
"emailSubject": {
"type": "string",
"maxLength": 255,
"description": "The subject of the email subscribers get. Empty for the default, the snapshot's name followed by \"is ready\"."
},
"emailMessage": {
"type": "string",
"maxLength": 4096,
"description": "Text at the top of the email subscribers get. Can be empty."
},
"scheduleInterval": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
],
"description": "The unit of how often it runs."
},
"schedulePeriod": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 90,
"description": "How many `scheduleInterval`s apart runs are. `week` and `2` runs every two weeks."
},
"scheduleFromDate": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When the schedule counts from. Each run falls a whole number of periods after it."
},
"durationInterval": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
],
"description": "The unit of how far back each snapshot looks."
},
"durationPeriod": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 90,
"description": "How many `durationInterval`s back each snapshot looks, from when it runs."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it was created."
},
"lastRun": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it last made a snapshot. `0` if never."
},
"nextDue": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it next runs. In the past when a run is waiting to be picked up."
},
"creatorAssigneeId": {
"type": "string",
"description": "The assignee who created it: a user (`u:`), an API key (`a:`), or `system` for those Silktide made itself."
},
"skipped": {
"anyOf": [
{
"type": "object",
"properties": {
"at": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When the run was due."
},
"reason": {
"type": "string",
"description": "Why it was skipped, as a stable id: `no-platform-access` when the account has no active plan."
},
"message": {
"description": "The reason, in the API user's language. Null for a reason without one.",
"type": [
"string",
"null"
]
}
},
"required": [
"at",
"reason",
"message"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Null, or why its last due run made no snapshot and sent no email. It runs again by itself once the reason has gone."
}
},
"required": [
"reportScheduleId",
"name",
"reportTemplateId",
"context",
"emailSubject",
"emailMessage",
"scheduleInterval",
"schedulePeriod",
"scheduleFromDate",
"durationInterval",
"durationPeriod",
"created",
"lastRun",
"nextDue",
"creatorAssigneeId",
"skipped"
],
"additionalProperties": false,
"description": "The report schedule."
},
"permissions": {
"type": "object",
"properties": {
"components": {
"type": "array",
"items": {
"type": "object",
"properties": {
"permissionId": {
"type": "string",
"description": "The permission, such as `Report-ReportRead`."
},
"componentType": {
"type": "string",
"description": "What can be given it. `assignees` for users and roles."
},
"label": {
"type": "string",
"description": "Its name, such as `Can see this dashboard / snapshot`."
},
"description": {
"description": "What it allows. Null for these permissions.",
"type": [
"string",
"null"
]
},
"inheritedPermissionIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Permissions that include this one: anyone with those has this too."
},
"models": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
},
"description": "Reserved. Empty for these permissions."
}
},
"required": [
"permissionId",
"componentType",
"label",
"description",
"inheritedPermissionIds",
"models"
],
"additionalProperties": false
},
"description": "The permissions a report schedule has: one to see it, one to admin it."
},
"componentValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who was given each permission on this report schedule directly, as assignee ids (`u:` users, `g:` roles)."
},
"fixedValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who has each permission from elsewhere, such as account-wide roles. Changed elsewhere, not here."
}
},
"required": [
"components",
"componentValues",
"fixedValues"
],
"additionalProperties": false,
"description": "Who may see and admin the report schedule."
},
"subscribers": {
"type": "object",
"properties": {
"assigneeIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Users and roles emailed when it runs, as assignee ids (`u:` users, `g:` roles)."
},
"emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "Other email addresses it is sent to, lowercased."
}
},
"required": [
"assigneeIds",
"emails"
],
"additionalProperties": false,
"description": "Who is emailed each snapshot."
}
},
"required": [
"reportSchedule",
"permissions",
"subscribers"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
},
"__schema1": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
}
]
}
}
},
"example": {
"reportSchedule": {
"reportScheduleId": 2,
"name": "Weekly pre-production website summary",
"reportTemplateId": "websites",
"context": {
"criteria": {
"tagIds": [
"pre-production"
]
}
},
"emailSubject": "",
"emailMessage": "",
"scheduleInterval": "week",
"schedulePeriod": 1,
"scheduleFromDate": 1796428800,
"durationInterval": "day",
"durationPeriod": 7,
"created": 1796380000,
"lastRun": 0,
"nextDue": 1796428800,
"creatorAssigneeId": "a:3",
"skipped": null
},
"permissions": {
"components": [
{
"permissionId": "Report-ReportScheduleRead",
"componentType": "assignees",
"label": "Can see this report schedule",
"description": null,
"inheritedPermissionIds": [
"Report-ReportScheduleAdmin",
"Report-ReportScheduleReadAll"
],
"models": []
},
{
"permissionId": "Report-ReportScheduleAdmin",
"componentType": "assignees",
"label": "Can admin this report schedule",
"description": null,
"inheritedPermissionIds": [
"Report-ReportScheduleAdminAll"
],
"models": []
}
],
"componentValues": {
"Report-ReportScheduleRead": [],
"Report-ReportScheduleAdmin": []
},
"fixedValues": {
"Report-ReportScheduleRead": [],
"Report-ReportScheduleAdmin": [],
"Report-ReportScheduleReadAll": [
"g:2",
"u:eu-12"
],
"Report-ReportScheduleAdminAll": [
"g:2",
"u:eu-12"
]
}
},
"subscribers": {
"assigneeIds": [
"u:eu-12",
"u:eu-14"
],
"emails": [
"web-team@example.com"
]
}
}
}
}
},
"400": {
"description": "`InvalidRequest`: `reportSchedule`, `permissions` or `subscribers` is not an object; `reportTemplateId` is missing or names no report template the API key's user can see; `name`, `emailSubject` or `emailMessage` contains `<`, `>` or control characters; `schedulePeriod` is not a whole number from 1 to 90; `durationPeriod` is not a whole number from 1 to 90; an interval is not one of its values; `subscribers.assigneeIds` or `subscribers.emails` is not a list of strings; or a subscriber is not a user or role in the account, or not an email address. `properties.field` names the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`EditionNotAvailable`: The account does not have Silktide 4. Reports, report schedules and report templates are Silktide 4's, so an account with only Silktide 5 cannot use them. `AccessDenied`: The API key's user cannot create report schedules.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"edition": "silktide-4",
"permission": "Can create new report schedules",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/report-schedules/{reportScheduleId}": {
"get": {
"operationId": "getReportSchedule",
"summary": "Get a report schedule and who it emails",
"description": "Returns one report schedule and who it emails.\n\nSubscribers come in two lists. `subscribers.assigneeIds` are users and roles in the account, as [assignee](/v1/platform/assignees) ids. `subscribers.emails` are any other addresses, which need no Silktide user. Each email links to the new snapshot through a share link, so it opens for people outside the account too.\n\nAny user who can see the schedule can get it. When the API key's user can also admin it, the answer includes `permissions`: who may see and admin the schedule. For anyone else, `permissions` is left out.",
"tags": [
"Governance: Report schedules"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/report-schedules/get-report-schedule"
},
"parameters": [
{
"name": "reportScheduleId",
"in": "path",
"required": true,
"description": "The report schedule.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "Get a report schedule and who it emails",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reportSchedule": {
"type": "object",
"properties": {
"reportScheduleId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The report schedule."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Its name. The snapshots it makes are named from their template, not from this."
},
"reportTemplateId": {
"type": "string",
"minLength": 1,
"maxLength": 16,
"description": "The report template each snapshot is built from."
},
"context": {
"anyOf": [
{
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "One of its sections. `0` for the whole website."
}
},
"required": [
"websiteId",
"sectionId"
],
"additionalProperties": false,
"description": "One website or section, for the `website` type."
},
{
"type": "object",
"properties": {
"criteria": {
"type": "object",
"properties": {
"tagIds": {
"description": "Websites and sections with these tags.",
"type": "array",
"items": {
"type": "string"
}
},
"tagOperator": {
"description": "`or` (the default) for any of the tags, `and` for all of them.",
"type": "string",
"enum": [
"or",
"and"
]
},
"subsiteIds": {
"description": "These websites and sections, by subsite id. When both are set, these win over `tagIds`.",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"description": "Which websites. With none, every website the user can see."
}
},
"required": [
"criteria"
],
"additionalProperties": false,
"description": "Several websites, for the `websites` type."
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "What it covers, in the shape its `contextTypeId` takes: `{\"websiteId\": 3, \"sectionId\": 0}` for one website, `{\"criteria\": {...}}` for several. `[]` when it has none."
},
"emailSubject": {
"type": "string",
"maxLength": 255,
"description": "The subject of the email subscribers get. Empty for the default, the snapshot's name followed by \"is ready\"."
},
"emailMessage": {
"type": "string",
"maxLength": 4096,
"description": "Text at the top of the email subscribers get. Can be empty."
},
"scheduleInterval": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
],
"description": "The unit of how often it runs."
},
"schedulePeriod": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 90,
"description": "How many `scheduleInterval`s apart runs are. `week` and `2` runs every two weeks."
},
"scheduleFromDate": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When the schedule counts from. Each run falls a whole number of periods after it."
},
"durationInterval": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
],
"description": "The unit of how far back each snapshot looks."
},
"durationPeriod": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 90,
"description": "How many `durationInterval`s back each snapshot looks, from when it runs."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it was created."
},
"lastRun": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it last made a snapshot. `0` if never."
},
"nextDue": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it next runs. In the past when a run is waiting to be picked up."
},
"creatorAssigneeId": {
"type": "string",
"description": "The assignee who created it: a user (`u:`), an API key (`a:`), or `system` for those Silktide made itself."
},
"skipped": {
"anyOf": [
{
"type": "object",
"properties": {
"at": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When the run was due."
},
"reason": {
"type": "string",
"description": "Why it was skipped, as a stable id: `no-platform-access` when the account has no active plan."
},
"message": {
"description": "The reason, in the API user's language. Null for a reason without one.",
"type": [
"string",
"null"
]
}
},
"required": [
"at",
"reason",
"message"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Null, or why its last due run made no snapshot and sent no email. It runs again by itself once the reason has gone."
}
},
"required": [
"reportScheduleId",
"name",
"reportTemplateId",
"context",
"emailSubject",
"emailMessage",
"scheduleInterval",
"schedulePeriod",
"scheduleFromDate",
"durationInterval",
"durationPeriod",
"created",
"lastRun",
"nextDue",
"creatorAssigneeId",
"skipped"
],
"additionalProperties": false,
"description": "The report schedule."
},
"permissions": {
"description": "Who may see and admin the schedule. Only when the API key's user can admin it.",
"type": "object",
"properties": {
"components": {
"type": "array",
"items": {
"type": "object",
"properties": {
"permissionId": {
"type": "string",
"description": "The permission, such as `Report-ReportRead`."
},
"componentType": {
"type": "string",
"description": "What can be given it. `assignees` for users and roles."
},
"label": {
"type": "string",
"description": "Its name, such as `Can see this dashboard / snapshot`."
},
"description": {
"description": "What it allows. Null for these permissions.",
"type": [
"string",
"null"
]
},
"inheritedPermissionIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Permissions that include this one: anyone with those has this too."
},
"models": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
},
"description": "Reserved. Empty for these permissions."
}
},
"required": [
"permissionId",
"componentType",
"label",
"description",
"inheritedPermissionIds",
"models"
],
"additionalProperties": false
},
"description": "The permissions a report schedule has: one to see it, one to admin it."
},
"componentValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who was given each permission on this report schedule directly, as assignee ids (`u:` users, `g:` roles)."
},
"fixedValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who has each permission from elsewhere, such as account-wide roles. Changed elsewhere, not here."
}
},
"required": [
"components",
"componentValues",
"fixedValues"
],
"additionalProperties": false
},
"subscribers": {
"type": "object",
"properties": {
"assigneeIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Users and roles emailed when it runs, as assignee ids (`u:` users, `g:` roles)."
},
"emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "Other email addresses it is sent to, lowercased."
}
},
"required": [
"assigneeIds",
"emails"
],
"additionalProperties": false,
"description": "Who is emailed each snapshot."
}
},
"required": [
"reportSchedule",
"subscribers"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
},
"__schema1": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
}
]
}
}
},
"example": {
"reportSchedule": {
"reportScheduleId": 2,
"name": "Weekly pre-production website summary",
"reportTemplateId": "websites",
"context": {
"criteria": {
"tagIds": [
"pre-production"
]
}
},
"emailSubject": "",
"emailMessage": "",
"scheduleInterval": "week",
"schedulePeriod": 1,
"scheduleFromDate": 1793664000,
"durationInterval": "day",
"durationPeriod": 7,
"created": 1793600000,
"lastRun": 1795478400,
"nextDue": 1796083200,
"creatorAssigneeId": "u:eu-12",
"skipped": null
},
"permissions": {
"components": [
{
"permissionId": "Report-ReportScheduleRead",
"componentType": "assignees",
"label": "Can see this report schedule",
"description": null,
"inheritedPermissionIds": [
"Report-ReportScheduleAdmin",
"Report-ReportScheduleReadAll"
],
"models": []
},
{
"permissionId": "Report-ReportScheduleAdmin",
"componentType": "assignees",
"label": "Can admin this report schedule",
"description": null,
"inheritedPermissionIds": [
"Report-ReportScheduleAdminAll"
],
"models": []
}
],
"componentValues": {
"Report-ReportScheduleRead": [],
"Report-ReportScheduleAdmin": []
},
"fixedValues": {
"Report-ReportScheduleRead": [],
"Report-ReportScheduleAdmin": [],
"Report-ReportScheduleReadAll": [
"g:2",
"u:eu-12"
],
"Report-ReportScheduleAdminAll": [
"g:2",
"u:eu-12"
]
}
},
"subscribers": {
"assigneeIds": [
"u:eu-12",
"u:eu-14"
],
"emails": [
"web-team@example.com"
]
}
}
}
}
},
"400": {
"description": "`InvalidRequest`: `reportScheduleId` is not a whole number. `properties.field` is `reportScheduleId`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`EditionNotAvailable`: The account does not have Silktide 4. Reports, report schedules and report templates are Silktide 4's, so an account with only Silktide 5 cannot use them. `AccessDenied`: The report schedule exists, but the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No report schedule with that id exists in the account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"edition": "silktide-4",
"permission": "Can see this report schedule",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
},
"put": {
"operationId": "updateReportSchedule",
"summary": "Update a report schedule or who it emails",
"description": "Changes a report schedule, who it emails, or both. Send only what you want to change; the response is the whole schedule, as [Get a report schedule](/v1/governance/report-schedules/get-report-schedule) returns it. Snapshots it has already made are not changed.\n\nEach of `subscribers.assigneeIds` and `subscribers.emails` replaces its whole list when you send it, and is kept when you leave it out. Send `[]` to email nobody. As when [creating a schedule](/v1/governance/report-schedules/create-report-schedule), they go beside `reportSchedule`, not inside it, and `assigneeIds` are kept without being checked.\n\nEvery update works out `nextDue` again: the first slot of the schedule after its last run, or its first slot if it has never run. That slot can be in the past, and then the schedule runs straight away.\n\nSilktide does not check a new `reportTemplateId` or `context`. A template that does not exist is saved, and the schedule then fails each time it runs, so [list the templates](/v1/governance/report-templates/list-report-templates) first, and keep `context` in the shape the template's `contextTypeId` takes. The schedule's `name` stays as it was unless you send one.",
"tags": [
"Governance: Report schedules"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/report-schedules/update-report-schedule"
},
"parameters": [
{
"name": "reportScheduleId",
"in": "path",
"required": true,
"description": "The report schedule.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reportSchedule": {
"description": "What to change. Fields left out keep their value.",
"type": "object",
"properties": {
"name": {
"description": "Its name, in plain text.",
"type": "string"
},
"reportTemplateId": {
"description": "The report template to build snapshots from. Not checked: it must exist.",
"type": "string",
"minLength": 1,
"maxLength": 16
},
"context": {
"description": "What each snapshot covers, in the shape the template's `contextTypeId` takes. Replaces the whole context.",
"anyOf": [
{
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "One of its sections. `0` for the whole website."
}
},
"required": [
"websiteId",
"sectionId"
],
"description": "One website or section, for the `website` type."
},
{
"type": "object",
"properties": {
"criteria": {
"type": "object",
"properties": {
"tagIds": {
"description": "Websites and sections with these tags.",
"type": "array",
"items": {
"type": "string"
}
},
"tagOperator": {
"description": "`or` (the default) for any of the tags, `and` for all of them.",
"type": "string",
"enum": [
"or",
"and"
]
},
"subsiteIds": {
"description": "These websites and sections, by subsite id. When both are set, these win over `tagIds`.",
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "Which websites. With none, every website the user can see."
}
},
"required": [
"criteria"
],
"description": "Several websites, for the `websites` type."
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
]
},
"scheduleInterval": {
"description": "The unit of how often it runs.",
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
]
},
"schedulePeriod": {
"description": "How many `scheduleInterval`s apart runs are, from `1` to `90`.",
"type": "integer",
"minimum": 1,
"maximum": 90
},
"scheduleFromDate": {
"description": "When the schedule counts from.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"durationInterval": {
"description": "The unit of how far back each snapshot looks.",
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
]
},
"durationPeriod": {
"description": "How many `durationInterval`s back each snapshot looks, from `1` to `90`.",
"type": "integer",
"minimum": 1,
"maximum": 90
},
"emailSubject": {
"description": "The email's subject, in plain text. Empty for the default.",
"type": "string",
"maxLength": 255
},
"emailMessage": {
"description": "Text to put at the top of the email, in plain text. Line breaks are kept.",
"type": "string",
"maxLength": 4096
}
}
},
"subscribers": {
"description": "Who is emailed each snapshot.",
"type": "object",
"properties": {
"assigneeIds": {
"description": "Users and roles to email, as assignee ids. Replaces the list; left out, it is kept.",
"type": "array",
"items": {
"type": "string"
}
},
"emails": {
"description": "Other email addresses to send it to. Replaces the list; left out, it is kept.",
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
}
},
"example": {
"reportSchedule": {
"schedulePeriod": 2,
"durationPeriod": 14
},
"subscribers": {
"assigneeIds": [
"u:eu-12",
"u:eu-14",
"u:eu-17"
]
}
}
}
}
},
"responses": {
"200": {
"description": "Update a report schedule or who it emails",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reportSchedule": {
"type": "object",
"properties": {
"reportScheduleId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The report schedule."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Its name. The snapshots it makes are named from their template, not from this."
},
"reportTemplateId": {
"type": "string",
"minLength": 1,
"maxLength": 16,
"description": "The report template each snapshot is built from."
},
"context": {
"anyOf": [
{
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "One of its sections. `0` for the whole website."
}
},
"required": [
"websiteId",
"sectionId"
],
"additionalProperties": false,
"description": "One website or section, for the `website` type."
},
{
"type": "object",
"properties": {
"criteria": {
"type": "object",
"properties": {
"tagIds": {
"description": "Websites and sections with these tags.",
"type": "array",
"items": {
"type": "string"
}
},
"tagOperator": {
"description": "`or` (the default) for any of the tags, `and` for all of them.",
"type": "string",
"enum": [
"or",
"and"
]
},
"subsiteIds": {
"description": "These websites and sections, by subsite id. When both are set, these win over `tagIds`.",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"description": "Which websites. With none, every website the user can see."
}
},
"required": [
"criteria"
],
"additionalProperties": false,
"description": "Several websites, for the `websites` type."
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "What it covers, in the shape its `contextTypeId` takes: `{\"websiteId\": 3, \"sectionId\": 0}` for one website, `{\"criteria\": {...}}` for several. `[]` when it has none."
},
"emailSubject": {
"type": "string",
"maxLength": 255,
"description": "The subject of the email subscribers get. Empty for the default, the snapshot's name followed by \"is ready\"."
},
"emailMessage": {
"type": "string",
"maxLength": 4096,
"description": "Text at the top of the email subscribers get. Can be empty."
},
"scheduleInterval": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
],
"description": "The unit of how often it runs."
},
"schedulePeriod": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 90,
"description": "How many `scheduleInterval`s apart runs are. `week` and `2` runs every two weeks."
},
"scheduleFromDate": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When the schedule counts from. Each run falls a whole number of periods after it."
},
"durationInterval": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
],
"description": "The unit of how far back each snapshot looks."
},
"durationPeriod": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 90,
"description": "How many `durationInterval`s back each snapshot looks, from when it runs."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it was created."
},
"lastRun": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it last made a snapshot. `0` if never."
},
"nextDue": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it next runs. In the past when a run is waiting to be picked up."
},
"creatorAssigneeId": {
"type": "string",
"description": "The assignee who created it: a user (`u:`), an API key (`a:`), or `system` for those Silktide made itself."
},
"skipped": {
"anyOf": [
{
"type": "object",
"properties": {
"at": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When the run was due."
},
"reason": {
"type": "string",
"description": "Why it was skipped, as a stable id: `no-platform-access` when the account has no active plan."
},
"message": {
"description": "The reason, in the API user's language. Null for a reason without one.",
"type": [
"string",
"null"
]
}
},
"required": [
"at",
"reason",
"message"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Null, or why its last due run made no snapshot and sent no email. It runs again by itself once the reason has gone."
}
},
"required": [
"reportScheduleId",
"name",
"reportTemplateId",
"context",
"emailSubject",
"emailMessage",
"scheduleInterval",
"schedulePeriod",
"scheduleFromDate",
"durationInterval",
"durationPeriod",
"created",
"lastRun",
"nextDue",
"creatorAssigneeId",
"skipped"
],
"additionalProperties": false,
"description": "The report schedule."
},
"permissions": {
"type": "object",
"properties": {
"components": {
"type": "array",
"items": {
"type": "object",
"properties": {
"permissionId": {
"type": "string",
"description": "The permission, such as `Report-ReportRead`."
},
"componentType": {
"type": "string",
"description": "What can be given it. `assignees` for users and roles."
},
"label": {
"type": "string",
"description": "Its name, such as `Can see this dashboard / snapshot`."
},
"description": {
"description": "What it allows. Null for these permissions.",
"type": [
"string",
"null"
]
},
"inheritedPermissionIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Permissions that include this one: anyone with those has this too."
},
"models": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
},
"description": "Reserved. Empty for these permissions."
}
},
"required": [
"permissionId",
"componentType",
"label",
"description",
"inheritedPermissionIds",
"models"
],
"additionalProperties": false
},
"description": "The permissions a report schedule has: one to see it, one to admin it."
},
"componentValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who was given each permission on this report schedule directly, as assignee ids (`u:` users, `g:` roles)."
},
"fixedValues": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Who has each permission from elsewhere, such as account-wide roles. Changed elsewhere, not here."
}
},
"required": [
"components",
"componentValues",
"fixedValues"
],
"additionalProperties": false,
"description": "Who may see and admin the report schedule."
},
"subscribers": {
"type": "object",
"properties": {
"assigneeIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Users and roles emailed when it runs, as assignee ids (`u:` users, `g:` roles)."
},
"emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "Other email addresses it is sent to, lowercased."
}
},
"required": [
"assigneeIds",
"emails"
],
"additionalProperties": false,
"description": "Who is emailed each snapshot."
}
},
"required": [
"reportSchedule",
"permissions",
"subscribers"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
},
"__schema1": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
}
]
}
}
},
"example": {
"reportSchedule": {
"reportScheduleId": 2,
"name": "Weekly pre-production website summary",
"reportTemplateId": "websites",
"context": {
"criteria": {
"tagIds": [
"pre-production"
]
}
},
"emailSubject": "",
"emailMessage": "",
"scheduleInterval": "week",
"schedulePeriod": 2,
"scheduleFromDate": 1796428800,
"durationInterval": "day",
"durationPeriod": 14,
"created": 1796380000,
"lastRun": 1797033600,
"nextDue": 1797638400,
"creatorAssigneeId": "a:3",
"skipped": null
},
"permissions": {
"components": [
{
"permissionId": "Report-ReportScheduleRead",
"componentType": "assignees",
"label": "Can see this report schedule",
"description": null,
"inheritedPermissionIds": [
"Report-ReportScheduleAdmin",
"Report-ReportScheduleReadAll"
],
"models": []
},
{
"permissionId": "Report-ReportScheduleAdmin",
"componentType": "assignees",
"label": "Can admin this report schedule",
"description": null,
"inheritedPermissionIds": [
"Report-ReportScheduleAdminAll"
],
"models": []
}
],
"componentValues": {
"Report-ReportScheduleRead": [],
"Report-ReportScheduleAdmin": []
},
"fixedValues": {
"Report-ReportScheduleRead": [],
"Report-ReportScheduleAdmin": [],
"Report-ReportScheduleReadAll": [
"g:2",
"u:eu-12"
],
"Report-ReportScheduleAdminAll": [
"g:2",
"u:eu-12"
]
}
},
"subscribers": {
"assigneeIds": [
"u:eu-12",
"u:eu-14",
"u:eu-17"
],
"emails": [
"web-team@example.com"
]
}
}
}
}
},
"400": {
"description": "`InvalidRequest`: `reportScheduleId` is not a whole number. `properties.field` is `reportScheduleId`. `InvalidRequest`: `reportSchedule`, `permissions` or `subscribers` is not an object, or a changed value does not fit: `reportTemplateId` names no report template the API key's user can see; `name`, `emailSubject` or `emailMessage` contains `<`, `>` or control characters; `schedulePeriod` or `durationPeriod` is not a whole number from 1 to 90; an interval is not one of its values; `subscribers.assigneeIds` or `subscribers.emails` is not a list of strings; or an added subscriber is not a user or role in the account, or not an email address. Values equal to the stored ones, and subscribers already on the schedule, are not checked. `properties.field` names the field.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`EditionNotAvailable`: The account does not have Silktide 4. Reports, report schedules and report templates are Silktide 4's, so an account with only Silktide 5 cannot use them. `AccessDenied`: The API key's user cannot see or admin the report schedule.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No report schedule with that id exists in the account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"edition": "silktide-4",
"permission": "Can admin this report schedule",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
},
"delete": {
"operationId": "deleteReportSchedule",
"summary": "Delete a report schedule",
"description": "Deletes a report schedule at once, so it makes no more snapshots and sends no more emails. It cannot be undone.\n\nThe snapshots it has already made are kept. Find them in [List reports](/v1/governance/reports/list-reports) by their `reportScheduleId`, and [delete them](/v1/governance/reports/delete-report) one by one if you no longer want them.\n\nThe response is an empty `201`. Deleting it again returns `404`.\n\nThe old documentation called the path parameter `{reportId}`. It is the schedule's id, `reportScheduleId`.",
"tags": [
"Governance: Report schedules"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/report-schedules/delete-report-schedule"
},
"parameters": [
{
"name": "reportScheduleId",
"in": "path",
"required": true,
"description": "The report schedule.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"201": {
"description": "Delete a report schedule"
},
"400": {
"description": "`InvalidRequest`: `reportScheduleId` is not a whole number. `properties.field` is `reportScheduleId`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`EditionNotAvailable`: The account does not have Silktide 4. Reports, report schedules and report templates are Silktide 4's, so an account with only Silktide 5 cannot use them. `AccessDenied`: The API key's user cannot see or admin the report schedule.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No report schedule with that id exists in the account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"edition": "silktide-4",
"permission": "Can admin this report schedule",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/report-templates": {
"get": {
"operationId": "listReportTemplates",
"summary": "List report templates",
"description": "Returns every report template the API key's user can see, sorted by name, with no paging. Use a template's `reportTemplateId` to [create a report](/v1/governance/reports/create-report) or a [report schedule](/v1/governance/report-schedules/create-report-schedule).\n\nA template's `contextTypeId` says what a report made from it can cover, and so the shape of the `context` you send with it: `website` for one website or section, `websites` for several. See [Context](/v1/concepts/context).\n\nA template's own `context` is not copied into reports made from it. Send the `context` you want each time.\n\nSkip templates whose `isDisabled` is `true`: a live report made from one cannot be read.",
"tags": [
"Governance: Report templates"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/report-templates/list-report-templates"
},
"parameters": [],
"responses": {
"200": {
"description": "List report templates",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reportTemplates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"reportTemplateId": {
"type": "string",
"minLength": 1,
"maxLength": 16,
"description": "The template's id, such as `broken-links`."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Its name, as Silktide shows it."
},
"description": {
"type": "string",
"maxLength": 255,
"description": "What it is for, as Silktide shows it. Can be empty."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"columns": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "How many widgets sit side by side in this row."
}
},
"required": [
"columns"
],
"additionalProperties": false
},
"description": "Its layout, one entry per row of widgets, top to bottom."
},
"created": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "When it was created."
},
"creatorAssigneeId": {
"type": "string",
"description": "The assignee who created it: a user (`u:`), an API key (`a:`), or `system` for those Silktide made itself."
},
"contextTypeId": {
"type": "string",
"enum": [
"website",
"websites",
"account",
"property"
],
"description": "What kind of thing a report made from it covers: `website`, `websites`, `account` or `property`."
},
"context": {
"anyOf": [
{
"type": "object",
"properties": {
"websiteId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The website."
},
"sectionId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "One of its sections. `0` for the whole website."
}
},
"required": [
"websiteId",
"sectionId"
],
"additionalProperties": false,
"description": "One website or section, for the `website` type."
},
{
"type": "object",
"properties": {
"criteria": {
"type": "object",
"properties": {
"tagIds": {
"description": "Websites and sections with these tags.",
"type": "array",
"items": {
"type": "string"
}
},
"tagOperator": {
"description": "`or` (the default) for any of the tags, `and` for all of them.",
"type": "string",
"enum": [
"or",
"and"
]
},
"subsiteIds": {
"description": "These websites and sections, by subsite id. When both are set, these win over `tagIds`.",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"description": "Which websites. With none, every website the user can see."
}
},
"required": [
"criteria"
],
"additionalProperties": false,
"description": "Several websites, for the `websites` type."
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "The context its author built it with in Silktide. Reports made from it do not take it: send each report's own `context`. `[]` when it has none."
},
"isCustom": {
"type": "boolean",
"description": "`true` if someone in the account made it, `false` if it comes with Silktide."
},
"isDisabled": {
"type": "boolean",
"description": "`true` when Silktide has switched it off. Live reports made from it cannot be read until it is switched back on."
}
},
"required": [
"reportTemplateId",
"name",
"description",
"rows",
"created",
"creatorAssigneeId",
"contextTypeId",
"context",
"isCustom",
"isDisabled"
],
"additionalProperties": false
},
"description": "Every report template the API key's user can see, built-in and custom, by name."
}
},
"required": [
"reportTemplates"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
}
},
"example": {
"reportTemplates": [
{
"reportTemplateId": "broken-links",
"name": "Broken links",
"description": "Summary of broken links for a specific website or section.",
"rows": [
{
"columns": 1
},
{
"columns": 1
}
],
"created": 1790216527,
"creatorAssigneeId": "system",
"contextTypeId": "website",
"context": [],
"isCustom": false,
"isDisabled": false
},
{
"reportTemplateId": "accessibility-22",
"name": "WCAG 2.2 summary",
"description": "Summarize WCAG 2.2 standards for a specific website or section.",
"rows": [
{
"columns": 1
},
{
"columns": 4
},
{
"columns": 1
},
{
"columns": 5
}
],
"created": 1704913002,
"creatorAssigneeId": "u:eu-12",
"contextTypeId": "website",
"context": {
"websiteId": 3,
"sectionId": 0
},
"isCustom": true,
"isDisabled": false
}
]
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`EditionNotAvailable`: The account does not have Silktide 4. Reports, report schedules and report templates are Silktide 4's, so an account with only Silktide 5 cannot use them.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"edition": "silktide-4",
"permission": null,
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/check-contents": {
"get": {
"operationId": "getCheckContents",
"summary": "List the pages and documents one check found issues on",
"description": "Lists the pages and documents of a website or section that one check tested,\nwith the check's score and issue count on each, most issues first. By default\nit lists only those with issues: send `issues=all` for everything the check\ntested, or `issues=withoutIssues` for what passed.\n\nEach row is a page or document as\n[Get contents](/v1/governance/content/get-contents) returns it, plus `score`\nand `numIssues`. Content the check cannot score, such as a PDF for a check\nthat reads only web pages, has a `score` of `null` and no issues, so\n`issues=all` and `issues=withoutIssues` list it too.\n\nGet the `checkId` from [Get checks](/v1/governance/checks/get-checks). A\n`checkId` that names no check answers with no rows, not an error. Leave out\n`websiteId` to list content from every website the API key's user can see.\n\nThis query takes `page` and `rowsPerPage` (see\n[Pagination](/v1/concepts/pagination)) but none of the table arguments:\n`columns`, `sort` and `search` are ignored.\n\nA missing `checkId`, or a `page` or `rowsPerPage` that is not a whole number\nof at least `1`, is an `InvalidRequest` error whose `properties.field` names\nthe argument. It comes with status `200`, like every results error, so check\nfor `error` before reading `result`.",
"tags": [
"Governance: Checks"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/governance/checks/get-check-contents"
},
"parameters": [
{
"name": "checkId",
"in": "query",
"required": true,
"description": "The check, by the id Get checks returns.",
"schema": {
"type": "string"
}
},
{
"name": "issues",
"in": "query",
"required": false,
"description": "`withIssues` for content the check found issues on, `withoutIssues` for content it found none on, `all` for both. Defaults to `withIssues`. Any other value means `all`.",
"schema": {
"type": "string",
"enum": [
"withIssues",
"withoutIssues",
"all"
]
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "The website. Left out, every website the API key's user can see.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`. Must be at least `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "`InvalidRequest`: `checkId` is missing. The error's own `status` is `400` and `properties.field` is `checkId`. The body is an error despite the status. `InvalidRequest`: `page` is not a whole number of at least `1`. The error's own `status` is `400` and `properties.field` is `page`. The body is an error despite the status. `InvalidRequest`: `rowsPerPage` is not a whole number of at least `1`. The error's own `status` is `400` and `properties.field` is `rowsPerPage`. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No website or section with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": null,
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/events": {
"get": {
"operationId": "getEvents",
"summary": "List the events visitors sent, with how often and by how many",
"description": "Lists every event sent in the period, one row each, most sent first: the\nevents your site sends with `silktide(\"…\")`, and the ones the Silktide Script\nrecords by itself (`page_load`, `click`, `download`, `frustration` and the\nothers). Send `type=custom` for only your own.\n\nUse a row's `event` with the queries that look inside one event:\n[Get event properties](/v1/analytics/engagement/get-event-properties),\n[Get event property values](/v1/analytics/engagement/get-event-property-values)\nand [Get event occurrences](/v1/analytics/engagement/get-event-occurrences).\n\nCounts are numbers. The older documentation showed `occurrences` and\n`visitors` as strings; read them as numbers either way.\n\n`firstSeen` and `lastSeen` are UTC date-times such as\n`2026-11-07T21:40:55Z`, not Unix timestamps. An event whose `lastSeen` is days\nold may have been removed from your site by accident.\n\n`search` matches the event's name, as sent or as shown. The table is sorted by\n`occurrences` unless you send `sort`. See [Tables](/v1/concepts/tables) and,\nfor `view`, `period` and `filters`, [Analytics](/v1/analytics).",
"tags": [
"Analytics: Engagement"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/engagement/get-events"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "columns",
"in": "query",
"required": false,
"description": "The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Only rows matching this text. What it searches depends on the table, most often the URL or title.",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "type",
"in": "query",
"required": false,
"description": "`custom` for only the events your site sends, `built-in` for only those the Silktide Script records itself, such as `page_load` and `click`. Left out, both.",
"schema": {
"type": "string",
"enum": [
"custom",
"built-in"
]
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/events-over-time": {
"get": {
"operationId": "getEventsOverTime",
"summary": "Get how often each event was sent, step by step",
"description": "Counts how often events were sent across the period, one line per event in\n`multiSeries`, and every event together in `total` and `series`. Send\n`type=custom` for only the events your site sends, or `type=built-in` for\nonly those the Silktide Script records itself.\n\n**Send a `period` other than `all`.** A series needs a start date, and `all`,\nthe default, has none: the answer is an error with status `200` and type\n`Error`. Check for `error` before reading `result`.\n\nHow long a step is depends on the period: an hour when it covers a single\nday, a month for `last-12-months`, and a day otherwise.\n\nWithout `limit`, every event sent in the period has a series of its own, which\nfor a busy site can be dozens. `limit=5` keeps the four busiest and adds the\nrest together as one series keyed `other`. `total` and `series` are the same\neither way.\n\n`key` is the event as your site sends it, the value to filter by\n(`filters[event]=is:newsletter_signup`); `label` is the name shown for it in\nSilktide. For `view`, `period` and `filters`, see [Analytics](/v1/analytics).",
"tags": [
"Analytics: Engagement"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/engagement/get-events-over-time"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "type",
"in": "query",
"required": false,
"description": "`custom` for only the events your site sends, `built-in` for only those the Silktide Script records itself, such as `page_load` and `click`. Left out, both.",
"schema": {
"type": "string",
"enum": [
"custom",
"built-in"
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "The most series `multiSeries` holds, counting `Other`: the busiest events less one, then the rest added together as `Other`. Left out, every event has its own series.",
"schema": {
"type": "integer",
"minimum": 2,
"maximum": 50
}
},
{
"name": "interval",
"in": "query",
"required": false,
"description": "With `period=custom`, the length of each step: an hour, a day, a week starting on Monday, a month or a year. Ignored with any other period. Left out, steps are hours for a single day, months for exactly twelve months, and days otherwise.",
"schema": {
"type": "string",
"enum": [
"PT1H",
"P1D",
"P7D",
"P1M",
"P1Y"
]
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `Error`: `period` is `all` or left out, which means `all`. Over-time queries need a period with a start. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/event-properties": {
"get": {
"operationId": "getEventProperties",
"summary": "List the properties an event was sent with",
"description": "Lists the properties one event was sent with, most sent first. A property is\na key in the object your site passes as the second argument:\n\n```js\nsilktide(\"open_accordion\", { summary: \"Delivery times\", section: \"shipping\" });\n```\n\nsends the properties `summary` and `section`. Name the event as `event`, by the\nname your site sends; take names from\n[Get events](/v1/analytics/engagement/get-events). Then rank one property's\nvalues with\n[Get event property values](/v1/analytics/engagement/get-event-property-values).\n\nThe table is empty, not an error, when `event` is left out, when nothing sent\nit with properties in the period, and for a built-in event such as `click`:\nonly the events your site sends carry properties. `event`, `time` and\n`pageUrl` are used by the Silktide Script itself and are never listed.\n\nThe table is sorted by `occurrences` unless you send `sort`. See\n[Tables](/v1/concepts/tables) and, for `view`, `period` and `filters`,\n[Analytics](/v1/analytics).",
"tags": [
"Analytics: Engagement"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/engagement/get-event-properties"
},
"parameters": [
{
"name": "event",
"in": "query",
"required": true,
"description": "The event, by the name your site sends, such as `newsletter_signup`. Only events your site sends have properties: left out, or a built-in event such as `click`, the table is empty.",
"schema": {
"type": "string"
}
},
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "columns",
"in": "query",
"required": false,
"description": "The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/event-property-values": {
"get": {
"operationId": "getEventPropertyValues",
"summary": "Rank the values one property of an event was sent with",
"description": "Ranks one property's values, most sent first, with the number of times each\nwas sent. For\n\n```js\nsilktide(\"open_accordion\", { summary: accordion.querySelector(\"summary\").textContent });\n```\n\n`event=open_accordion&property=summary` answers which accordions visitors\nopened, and how often.\n\nName the event as `event` and the property as `property`, both exactly as your\nsite sends them. Take property names from\n[Get event properties](/v1/analytics/engagement/get-event-properties). The\ntable is empty, not an error, when either is left out, when nothing sent the\nevent with that property in the period, and for a built-in event such as\n`click`.\n\nEvery value is recorded as text, so `value` is a string even for a property\nyour site sent as a number. Only the times the event carried the property count, so an\nevent sent without it does not appear as an empty value.\n\nTo list the times the event was sent with one value, pass the same `property`\nand the row's `value` to\n[Get event occurrences](/v1/analytics/engagement/get-event-occurrences).\n\n`search` matches the value. The table is sorted by `occurrences` unless you\nsend `sort`. See [Tables](/v1/concepts/tables) and, for `view`, `period` and\n`filters`, [Analytics](/v1/analytics).",
"tags": [
"Analytics: Engagement"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/engagement/get-event-property-values"
},
"parameters": [
{
"name": "event",
"in": "query",
"required": true,
"description": "The event, by the name your site sends, such as `newsletter_signup`. Only events your site sends have properties: left out, or a built-in event such as `click`, the table is empty.",
"schema": {
"type": "string"
}
},
{
"name": "property",
"in": "query",
"required": true,
"description": "The property, exactly as your site sent it, such as `summary`; take names from Get event properties. Not trimmed: ` summary` is a different property. Left out, the table is empty.",
"schema": {
"type": "string"
}
},
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "columns",
"in": "query",
"required": false,
"description": "The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Only rows matching this text. What it searches depends on the table, most often the URL or title.",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/event-occurrences": {
"get": {
"operationId": "getEventOccurrences",
"summary": "List every time an event was sent, newest first",
"description": "Lists every time one event was sent, newest first. Each row has the `time` (a\nUnix timestamp, in seconds), the page as `url`, the visit it was part of as\n`sessionId`, and its `properties`. Add `property` and `value` to list only the\ntimes it was sent with that value, the rows behind one row of\n[Get event property values](/v1/analytics/engagement/get-event-property-values).\n\nName the event as `event`, exactly as your site sends it; take names from\n[Get events](/v1/analytics/engagement/get-events). The table is empty, not an\nerror, when `event` is left out and for a built-in event such as `click`.\nAn event sent without properties is listed, with `properties` as `[]`.\n\nThese are rows, not estimates: every occurrence in the period is listed, even\nwhere Analytics samples a busy site for its counts. Keep `period` short and\npage through with `page` and `rowsPerPage`.\n\n`search` matches the page or any property value. The table is sorted by\n`time` unless you send `sort`. See [Tables](/v1/concepts/tables) and, for\n`view`, `period` and `filters`, [Analytics](/v1/analytics).",
"tags": [
"Analytics: Engagement"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/engagement/get-event-occurrences"
},
"parameters": [
{
"name": "event",
"in": "query",
"required": true,
"description": "The event, by the name your site sends, such as `newsletter_signup`. Only events your site sends have properties: left out, or a built-in event such as `click`, the table is empty.",
"schema": {
"type": "string"
}
},
{
"name": "property",
"in": "query",
"required": false,
"description": "With `value`, only the times the event was sent with this property, exactly as your site sent it.",
"schema": {
"type": "string"
}
},
{
"name": "value",
"in": "query",
"required": false,
"description": "With `property`, only the times the property was sent with this value. Left out, the times it was sent empty.",
"schema": {
"type": "string"
}
},
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "columns",
"in": "query",
"required": false,
"description": "The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Only rows matching this text. What it searches depends on the table, most often the URL or title.",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/goals": {
"get": {
"operationId": "getGoals",
"summary": "List goals and how often each was completed",
"description": "Lists every goal of the view, or of the website, with how many times each was\ncompleted in the period and the share of visitors who completed it, most\ncompleted first. A view lists its own goals and the goals of every view inside\nit, so `view=all` lists every goal in the account.\n\nEvery goal is listed, including one nobody completed in the period, which\nshows `0` for both. Goals are created and changed in Silktide; the API reads\nthem.\n\nThe rows say what a goal matches in `goal`, but not whether it is a page or an\nevent goal, nor whether a page goal needs the exact address or any address\ncontaining it. Two goals that match the same thing show the same figures.\n\nThis table has no `search`. It is sorted by `totalConversions` unless you send\n`sort`. See [Tables](/v1/concepts/tables) and, for `view`, `period` and\n`filters`, [Analytics](/v1/analytics).",
"tags": [
"Analytics: Engagement"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/engagement/get-goals"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "columns",
"in": "query",
"required": false,
"description": "The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/site-search-terms": {
"get": {
"operationId": "getSiteSearchTerms",
"summary": "List what people searched your site for",
"description": "Lists every term people typed into your site's own search boxes in the\nperiod, with its `searches` and `visitors`, most searched first. `term` is the\nterm in lowercase; `label` is how people typed it most. Add `results=none` to\ncount only searches that found nothing: what people looked for and could not\nfind.\n\nNothing is recorded until the account lists its search boxes, or describes\nits search results page, under **Analytics > Settings > Data** in Silktide.\nUntil then the table is empty.\n\n`withoutResults` and `averageResults` are `null` where the outcome is not\nknown. Silktide only knows whether a search found anything once the account\nhas described its search results page, so both are `null` for every term\nbefore then, and for searches it could not read.\n\n`search` matches the term. The table is sorted by `searches` unless you send\n`sort`. Pass a row's `term` to\n[Get site searches over time](/v1/analytics/engagement/get-site-searches-over-time)\nto see how it rose or fell. See [Tables](/v1/concepts/tables) and, for `view`,\n`period` and `filters`, [Analytics](/v1/analytics).",
"tags": [
"Analytics: Engagement"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/engagement/get-site-search-terms"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "columns",
"in": "query",
"required": false,
"description": "The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Only rows matching this text. What it searches depends on the table, most often the URL or title.",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "results",
"in": "query",
"required": false,
"description": "`none` to count only searches that found nothing, `some` only those that found something. Terms with no such search are left out. Left out, every search counts.",
"schema": {
"type": "string",
"enum": [
"none",
"some"
]
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/site-searches-over-time": {
"get": {
"operationId": "getSiteSearchesOverTime",
"summary": "Count searches of your site, step by step",
"description": "Counts searches of your site's own search boxes over the period, one entry\nper step. Add `term` for one term, or `results` as `none` or `some` for one\noutcome. Terms are counted whatever their capitals, so `term=Parking` and\n`term=parking` count the same searches.\n\n**Send a `period` other than `all`.** A series needs a start date, and `all`,\nthe default, has none: the answer is an error with status `200` and type\n`Error`. Check for `error` before reading `result`.\n\nHow long a step is depends on the period: an hour when it covers a single\nday, a month for `last-12-months`, and a day otherwise.\n\nNothing is recorded until the account lists its search boxes, or describes\nits search results page, under **Analytics > Settings > Data** in Silktide;\nuntil then every step is `0`. `results` counts only searches whose outcome is\nknown, which needs the search results page described.\n\nTo find terms, use\n[Get site search terms](/v1/analytics/engagement/get-site-search-terms). For\n`view`, `period` and `filters`, see [Analytics](/v1/analytics).",
"tags": [
"Analytics: Engagement"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/engagement/get-site-searches-over-time"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "term",
"in": "query",
"required": false,
"description": "Only searches for this term, whatever its capitals, such as a `term` from Get site search terms. Left out, every search.",
"schema": {
"type": "string"
}
},
{
"name": "results",
"in": "query",
"required": false,
"description": "`none` for only searches that found nothing, `some` for only those that found something. Left out, every search.",
"schema": {
"type": "string",
"enum": [
"none",
"some"
]
}
},
{
"name": "interval",
"in": "query",
"required": false,
"description": "With `period=custom`, the length of each step: an hour, a day, a week starting on Monday, a month or a year. Ignored with any other period. Left out, steps are hours for a single day, months for exactly twelve months, and days otherwise.",
"schema": {
"type": "string",
"enum": [
"PT1H",
"P1D",
"P7D",
"P1M",
"P1Y"
]
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `Error`: `period` is `all` or left out, which means `all`. Over-time queries need a period with a start. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/visitors": {
"get": {
"operationId": "getVisitorsOverTime",
"summary": "Get how many people visited, step by step over a period",
"description": "Returns how many people visited in each step of a period, and across the whole of it, for an analytics view or a website.\n\n`total` counts each person once across the period, so it is usually less than the steps added up: someone who visited on Monday and on Tuesday is in both days, but in `total` once.\n\nSend a `period`. With the default, `all`, this answers with an error. How long each step is, and how to choose it, is under [Over time](/v1/analytics/audience).\n\nTraffic collected at the Basic consent level has no visitor, so it is not counted here. Its page views are, in [Get page views over time](/v1/analytics/audience/get-page-views-over-time).",
"tags": [
"Analytics: Audience"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/audience/get-visitors-over-time"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "interval",
"in": "query",
"required": false,
"description": "With `period=custom`, the length of each step: an hour, a day, a week starting on Monday, a month or a year. Ignored with any other period. Left out, steps are hours for a single day, months for exactly twelve months, and days otherwise.",
"schema": {
"type": "string",
"enum": [
"PT1H",
"P1D",
"P7D",
"P1M",
"P1Y"
]
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `Error`: `period` is `all` or left out, which means `all`. Over-time queries need a period with a start. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status. `Unspecified`: `interval` is not one of its values. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/page-views": {
"get": {
"operationId": "getPageViewsOverTime",
"summary": "Get how many pages were viewed, step by step over a period",
"description": "Returns how many pages were viewed in each step of a period, and across the whole of it, for an analytics view or a website.\n\nThe count is called `events`, not `pageViews`, because the same query counts any event: send `event=download` for downloads, or `event=click` for clicks, and `outgoingUrl` to count only those for one file or link. Unlike visitors, page views add up, so `total` is the steps added together.\n\nSend a `period`. With the default, `all`, this answers with an error. How long each step is, and how to choose it, is under [Over time](/v1/analytics/audience).\n\nPage views include traffic collected at the Basic consent level, which [Get visitors over time](/v1/analytics/audience/get-visitors-over-time) leaves out.",
"tags": [
"Analytics: Audience"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/audience/get-page-views-over-time"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "interval",
"in": "query",
"required": false,
"description": "With `period=custom`, the length of each step: an hour, a day, a week starting on Monday, a month or a year. Ignored with any other period. Left out, steps are hours for a single day, months for exactly twelve months, and days otherwise.",
"schema": {
"type": "string",
"enum": [
"PT1H",
"P1D",
"P7D",
"P1M",
"P1Y"
]
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
},
{
"name": "event",
"in": "query",
"required": false,
"description": "Count this event instead of page views, by its name, such as `download` or `click`. Defaults to page views. A name nothing was recorded under counts `0`.",
"schema": {
"type": "string"
}
},
{
"name": "outgoingUrl",
"in": "query",
"required": false,
"description": "With `event`, count only the events for this exact URL: one file's downloads, or the clicks on one outgoing link. Unlike `filters[outgoingUrl]`, which keeps whole visits, this counts the events themselves.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `Error`: `period` is `all` or left out, which means `all`. Over-time queries need a period with a start. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status. `Unspecified`: `interval` is not one of its values. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/bounce-rate": {
"get": {
"operationId": "getBounceRateOverTime",
"summary": "Get the share of visits that bounced, step by step over a period",
"description": "Returns the share of visits that bounced in each step of a period, and across the whole of it, for an analytics view or a website. A visit bounces when it loads at most one page and the visitor is engaged with it only briefly.\n\nEach step's `bounceRate` is a whole percentage; `total` is not rounded. `total` is the bounce rate of all the period's visits together, so a quiet day moves it less than a busy one. Do not average the steps to get it.\n\nA `filters[url]` filter matches the page each visit started on, since a visit has no single page.\n\nSend a `period`. With the default, `all`, this answers with an error. How long each step is, and how to choose it, is under [Over time](/v1/analytics/audience). Traffic collected at the Basic consent level records no visits, so it is not counted here.",
"tags": [
"Analytics: Audience"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/audience/get-bounce-rate-over-time"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "interval",
"in": "query",
"required": false,
"description": "With `period=custom`, the length of each step: an hour, a day, a week starting on Monday, a month or a year. Ignored with any other period. Left out, steps are hours for a single day, months for exactly twelve months, and days otherwise.",
"schema": {
"type": "string",
"enum": [
"PT1H",
"P1D",
"P7D",
"P1M",
"P1Y"
]
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `Error`: `period` is `all` or left out, which means `all`. Over-time queries need a period with a start. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status. `Unspecified`: `interval` is not one of its values. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/duration-over-time": {
"get": {
"operationId": "getDurationOverTime",
"summary": "Get how long visits lasted, step by step over a period",
"description": "Returns how long the average visit lasted in each step of a period, and across the whole of it, for an analytics view or a website.\n\nDuration is engaged time: the seconds the visitor was actively using the pages of a visit, not how long a tab stayed open. Some visits record more engaged time than one person could have spent in them, such as colleagues behind one office network who look like a single visitor, or a computer that slept with the page open. Those are left out of the average and counted in `unmeasuredSessions`, with their page views in `unmeasuredPageViews`, so you can tell how much of the traffic the average does not cover. They are still visits, in `totalSessions`.\n\n`total` weights each step by its measured visits, so do not average the steps to get it.\n\nThe old documentation named the average `observedDuration`. It is `engagedDuration`.\n\nSend a `period`. With the default, `all`, this answers with an error. How long each step is, and how to choose it, is under [Over time](/v1/analytics/audience). A `filters[url]` filter matches the page each visit started on. Traffic collected at the Basic consent level records no visits, so it is not counted here.",
"tags": [
"Analytics: Audience"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/audience/get-duration-over-time"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "interval",
"in": "query",
"required": false,
"description": "With `period=custom`, the length of each step: an hour, a day, a week starting on Monday, a month or a year. Ignored with any other period. Left out, steps are hours for a single day, months for exactly twelve months, and days otherwise.",
"schema": {
"type": "string",
"enum": [
"PT1H",
"P1D",
"P7D",
"P1M",
"P1Y"
]
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `Error`: `period` is `all` or left out, which means `all`. Over-time queries need a period with a start. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status. `Unspecified`: `interval` is not one of its values. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/countries": {
"get": {
"operationId": "getCountries",
"summary": "List the countries visitors came from",
"description": "Lists the countries visits came from, with each country's visitors and page views, most visitors first. It is a [table](/v1/concepts/tables): choose its columns, sort it, search it by country name or code, and page through it.\n\nVisits whose country could not be worked out are left out, so the rows can add up to less than the period's totals.\n\nWith `previousPeriod=1`, each row also carries its figures for the period before, and a country that had no visits then reads `0`. The comparison needs a period with a start: with `all` it is left out. When you send `columns`, name the `previous…` columns you want too.\n\nColumns you choose with `columns` always come back with `countryCode`. Send `sort` with `columns`, naming one of them.\n\nNarrow other Analytics queries to one country with `filters[countryCode]=is:GB`.",
"tags": [
"Analytics: Audience"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/audience/get-countries"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "columns",
"in": "query",
"required": false,
"description": "The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Only rows matching this text. What it searches depends on the table, most often the URL or title.",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/regions": {
"get": {
"operationId": "getRegions",
"summary": "List the regions within countries that visitors came from",
"description": "Lists the regions within countries that visits came from, such as states, provinces or the nations of the United Kingdom, with each region's visitors and page views, most visitors first. It is a [table](/v1/concepts/tables): choose its columns, sort it, search it by region name, and page through it.\n\nA region code is only unique within its country, so identify a row by `countryCode` and `regionCode` together. To list one country's regions, filter with `filters[countryCode]=is:GB`.\n\nVisits whose region could not be worked out are left out, so the rows can add up to less than [Get countries](/v1/analytics/audience/get-countries) shows for the same country.\n\nWith `columns`, a row holds only the columns you name, without its codes unless you name them too. Send `sort` with `columns`, naming one of them. `previousPeriod=1` adds the period before, as it does for countries.",
"tags": [
"Analytics: Audience"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/audience/get-regions"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "columns",
"in": "query",
"required": false,
"description": "The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Only rows matching this text. What it searches depends on the table, most often the URL or title.",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/browsers": {
"get": {
"operationId": "getBrowsers",
"summary": "List the browsers visitors used",
"description": "Lists the browsers visitors used, with each one's visitors and page views, most visitors first. It answers with a plain list, not a [table](/v1/concepts/tables): there is no paging, sorting or search, and the list stops at `limit`.\n\nBrowsers are named as Silktide recognizes them, so Safari on an iPhone is `Mobile Safari`, apart from Safari on a Mac. Browsers past `limit` are left out, not gathered into `Other`; `Other` is a browser Silktide did not recognize.\n\n`iconUrl` is an image on the API host for showing beside the name; it is `null` for browsers Silktide has no icon for.",
"tags": [
"Analytics: Audience"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/audience/get-browsers"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "How many browsers to return, most visitors first. Defaults to `10`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/operating-systems": {
"get": {
"operationId": "getOperatingSystems",
"summary": "List the operating systems visitors used",
"description": "Lists the operating systems visitors used, with each one's visitors and page views, most visitors first. It answers with a plain list, not a [table](/v1/concepts/tables).\n\nThe list stops at the ten with the most visitors. The old documentation said it takes `limit`; it ignores it, and systems past the tenth are left out rather than gathered into `Other`. `Other` is a system Silktide did not recognize.\n\n`iconUrl` is an image on the API host for showing beside the name; `Mac` and `iOS` share one. It is `null` for systems Silktide has no icon for.",
"tags": [
"Analytics: Audience"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/audience/get-operating-systems"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/browser-sizes": {
"get": {
"operationId": "getBrowserSizes",
"summary": "List the sizes of browser window visitors used",
"description": "Lists how wide visitors' browser windows were, grouped into sizes, with the visitors and page views at each, smallest first. It answers with a plain list, not a [table](/v1/concepts/tables).\n\nA size is a range of window widths, not a kind of device: a phone turned sideways, or a narrow desktop window, can count as `Tablet`. Each size runs from the breakpoint of the size before it up to its own. By default there are three:\n\n| Size | Window width |\n| --- | --- |\n| `Mobile` | up to 425 pixels |\n| `Tablet` | 426 to 1,024 |\n| `Desktop` | wider than 1,024 (its breakpoint reads `1440`) |\n\nWith `simple` set to `false`, there are seven: `Mobile (small)` up to 320, `Mobile (medium)` up to 375, `Mobile (large)` up to 425, `Tablet` up to 768, `Desktop (small)` up to 1,024, `Desktop (medium)` up to 1,440 and `Desktop (large)` wider (its breakpoint reads `2560`).\n\nTwo things can make the figures differ from other queries. `limit` counts distinct window widths, before they are grouped, so only the ten most-visited widths are counted by default; on a busy website, send a larger `limit` to count them all. And `visitors` adds up each width's visitors, so a visitor who resized their window can be counted more than once. `pageViews` adds up correctly.",
"tags": [
"Analytics: Audience"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/audience/get-browser-sizes"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "simple",
"in": "query",
"required": false,
"description": "`false` for seven finer sizes, from `Mobile (small)` to `Desktop (large)`, instead of `Mobile`, `Tablet` and `Desktop`. Defaults to `true`. In a query string, send `0` or `false`.",
"schema": {
"type": "boolean"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "How many distinct window widths to count, most visitors first, before they are grouped into sizes. Defaults to `10`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/browser-sizes-over-time": {
"get": {
"operationId": "getBrowserSizesOverTime",
"summary": "Get visitors at each browser size, step by step over a period",
"description": "Returns one series per browser size, with the visitors at that size in each step of a period, for an analytics view or a website. The sizes are the same as [Get browser sizes](/v1/analytics/audience/get-browser-sizes): three by default, seven with `simple` set to `false`.\n\nEach step counts the visitors at the size in that step. `total` adds the steps up, so a visitor seen on two days counts twice: it is not the number of people who used the size. A step with no visitors at a size has no `breakpoint`; read it from another step.\n\nSend a `period`. With the default, `all`, this answers with an error. How long each step is, and how to choose it, is under [Over time](/v1/analytics/audience). This query does not take `previousPeriod`.\n\nThe old documentation gave this query's path as `/v1/results/analytics/browser-sizes`, which is [Get browser sizes](/v1/analytics/audience/get-browser-sizes). This one is `/v1/results/analytics/browser-sizes-over-time`.",
"tags": [
"Analytics: Audience"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/audience/get-browser-sizes-over-time"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "interval",
"in": "query",
"required": false,
"description": "With `period=custom`, the length of each step: an hour, a day, a week starting on Monday, a month or a year. Ignored with any other period. Left out, steps are hours for a single day, months for exactly twelve months, and days otherwise.",
"schema": {
"type": "string",
"enum": [
"PT1H",
"P1D",
"P7D",
"P1M",
"P1Y"
]
}
},
{
"name": "simple",
"in": "query",
"required": false,
"description": "`false` for seven finer sizes, from `Mobile (small)` to `Desktop (large)`, instead of `Mobile`, `Tablet` and `Desktop`. Defaults to `true`. In a query string, send `0` or `false`.",
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `Error`: `period` is `all` or left out, which means `all`. Over-time queries need a period with a start. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status. `Unspecified`: `interval` is not one of its values. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/sources": {
"get": {
"operationId": "getSources",
"summary": "List where visitors came from, one row per source and medium",
"description": "Lists where visitors came from: a search engine, a social network, an AI assistant such as ChatGPT, an email, or another website that linked to yours. It is the table on the Sources screen in Analytics, and takes the [Analytics arguments](/v1/analytics) and the [table arguments](/v1/concepts/tables).\n\nA row is one source and one medium together, so the same source can appear on more than one row, once for each medium it arrived through. `syntheticKey` tells the rows apart; `source` and `medium` are the values to filter other queries by.\n\nDirect is a fallback, not proof that someone typed the address: a visit whose referrer or campaign was not passed on is counted as direct too. Where a visitor came from is only known for visitors collected at the Cookie-free or Complete consent level.\n\n`sourceName` is the name to show. Where an analytics administrator gave a source a name of their own, `sourceName` is that name and `isLabeled` is `true`; `source` stays the value Silktide recorded.\n\nRows are sorted by `visitors`, busiest first. `bounceRate`, `pagesPerSession` and `topEntryUrl` cannot be sorted by: a `sort` naming one of them answers with an error.\n\nSend `goalId` to see which sources lead to a goal, and `previousPeriod=1` to compare each row with the period before.",
"tags": [
"Analytics: Acquisition"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/acquisition/get-sources"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "columns",
"in": "query",
"required": false,
"description": "The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Only rows matching this text. What it searches depends on the table, most often the URL or title.",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "goalId",
"in": "query",
"required": false,
"description": "A goal, by the `goalId` Get goals gives it. Adds `goalCompletions` to every row. Left out, no goal.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status. `sort` names a column the table cannot sort by. Sort by `sourceName`, `mediumName`, `sampleUrl`, `visitors`, `pageViews` or `goalCompletions` only. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it. `ModelNotFound`: `goalId` names no goal of the view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/sources-over-time": {
"get": {
"operationId": "getSourcesOverTime",
"summary": "Get visitors from the busiest sources, step by step",
"description": "Draws the busiest sources as lines over time: unique visitors from each, step by step through the period. It is the chart on the Sources screen in Analytics, and takes the [Analytics arguments](/v1/analytics).\n\nUnlike [Get sources](/v1/analytics/acquisition/get-sources), a line is one source across every medium it arrived through. Direct visits are the line whose `key` is empty.\n\nSend a `period` with a start, such as `last-30-days` or `custom` with `from` and `to`. Left out, `period` is `all`, and this query answers with an error.\n\n`limit` counts the `Other` line, which adds up every source after the busiest. With the default of `5`, you get four sources and `Other`. `Other` is left out when every source already has a line.\n\nA line's `total` adds up its steps, so a visitor who came on two different days counts twice in it. For the number of unique visitors over the whole period, use Get sources.",
"tags": [
"Analytics: Acquisition"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/acquisition/get-sources-over-time"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "interval",
"in": "query",
"required": false,
"description": "With `period=custom`, the length of each step: an hour, a day, a week starting on Monday, a month or a year. Ignored with any other period. Left out, steps are hours for a single day, months for exactly twelve months, and days otherwise.",
"schema": {
"type": "string",
"enum": [
"PT1H",
"P1D",
"P7D",
"P1M",
"P1Y"
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "How many series to return, counting `Other`, from `2` to `50`; a number outside that is taken as the nearest end. Defaults to `5`: the four busiest, then `Other` for the rest.",
"schema": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `Error`: `period` is `all` or left out, which means `all`. Over-time queries need a period with a start. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status. `Unspecified`: `interval` is not one of its values. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/campaigns": {
"get": {
"operationId": "getCampaigns",
"summary": "List the campaigns visitors arrived through",
"description": "Lists the campaigns visitors arrived through. A campaign is the `utm_campaign` on the links you share in emails, ads and posts; the same links' `utm_source` and `utm_medium` become the visit's source and medium in [Get sources](/v1/analytics/acquisition/get-sources). It is the table on the Campaigns screen in Analytics, and takes the [Analytics arguments](/v1/analytics) and the [table arguments](/v1/concepts/tables).\n\nOnly visits that carried a campaign are counted, so the rows add up to less than every visitor.\n\nCampaign names are recorded exactly as the links spell them. `Spring-Sale` and `spring-sale` are two rows, so name campaigns the same way every time.\n\n`topSource`, `topMedium` and `channel` say where most of a campaign's visits came from. They, `bounceRate` and `topEntryUrl` cannot be sorted by: a `sort` naming one of them answers with an error.\n\nSend `goalId` to see which campaigns lead to a goal, and `previousPeriod=1` to compare each row with the period before.",
"tags": [
"Analytics: Acquisition"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/acquisition/get-campaigns"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "columns",
"in": "query",
"required": false,
"description": "The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Only rows matching this text. What it searches depends on the table, most often the URL or title.",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "goalId",
"in": "query",
"required": false,
"description": "A goal, by the `goalId` Get goals gives it. Adds `goalCompletions` to every row. Left out, no goal.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status. `sort` names a column the table cannot sort by. Sort by `campaignName`, `visitors`, `pageViews` or `goalCompletions` only. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it. `ModelNotFound`: `goalId` names no goal of the view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/campaigns-over-time": {
"get": {
"operationId": "getCampaignsOverTime",
"summary": "Get visitors from the busiest campaigns, step by step",
"description": "Draws the busiest campaigns as lines over time: unique visitors who arrived through each, step by step through the period. It is the chart on the Campaigns screen in Analytics, and takes the [Analytics arguments](/v1/analytics).\n\nOnly visits that carried a campaign are counted. A line's `key` is the campaign as recorded, the value to filter other queries by with `filters[campaign]`; `label` is the name to show.\n\nSend a `period` with a start, such as `last-30-days` or `custom` with `from` and `to`. Left out, `period` is `all`, and this query answers with an error.\n\n`limit` counts the `Other` line, which adds up every campaign after the busiest. With the default of `5`, you get four campaigns and `Other`. `Other` is left out when every campaign already has a line.\n\nA line's `total` adds up its steps, so a visitor who came on two different days counts twice in it. For the number of unique visitors over the whole period, use [Get campaigns](/v1/analytics/acquisition/get-campaigns).",
"tags": [
"Analytics: Acquisition"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/acquisition/get-campaigns-over-time"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "interval",
"in": "query",
"required": false,
"description": "With `period=custom`, the length of each step: an hour, a day, a week starting on Monday, a month or a year. Ignored with any other period. Left out, steps are hours for a single day, months for exactly twelve months, and days otherwise.",
"schema": {
"type": "string",
"enum": [
"PT1H",
"P1D",
"P7D",
"P1M",
"P1Y"
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "How many series to return, counting `Other`, from `2` to `50`; a number outside that is taken as the nearest end. Defaults to `5`: the four busiest, then `Other` for the rest.",
"schema": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `Error`: `period` is `all` or left out, which means `all`. Over-time queries need a period with a start. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status. `Unspecified`: `interval` is not one of its values. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/pages": {
"get": {
"operationId": "getPages",
"summary": "List the pages people viewed",
"description": "Lists the pages people viewed, with how often and for how long. It is the table on the Pages screen in Analytics, and takes the [Analytics arguments](/v1/analytics) and the [table arguments](/v1/concepts/tables). `search` matches the page's address.\n\n`pageName` is the name to show for a page, and `url` the value to filter other queries by. Every page the Silktide Script recorded a view of is listed, including pages a crawl never reaches, such as thank-you pages and pages behind a sign-in.\n\nRows are sorted by `visitors`, busiest first. `bounceRate` and `averageScroll` are added only when `columns` names them. When you send `columns`, also send a `sort` naming one of them, unless `visitors` is among them: without it, this query answers with an error. Rows then carry only the columns asked for, without `pageTitle` and `pageName`.\n\nSend `previousPeriod=1` to compare each page with the period before.",
"tags": [
"Analytics: Content"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/content/get-pages"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "columns",
"in": "query",
"required": false,
"description": "The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Only rows matching this text. What it searches depends on the table, most often the URL or title.",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status. `sort` names a column the table cannot sort by. Sort by `url`, `pageViews`, `visitors`, `bounceRate`, `duration` or `averageScroll` only. The body is an error despite the status. `columns` leaves out `visitors` and no `sort` names one of the columns asked for. The body is an error despite the status. `columns` names a column the table does not have. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/entry-pages": {
"get": {
"operationId": "getEntryPages",
"summary": "List the landing pages visits began on",
"description": "Lists landing pages: the first tracked page of each visit, and how many visits began on each. It is the Landing pages table in Analytics, and takes the [Analytics arguments](/v1/analytics) and the [table arguments](/v1/concepts/tables).\n\n`pageViews` here counts visits that began on the page, not every view of it; [Get pages](/v1/analytics/content/get-pages) counts those. The scroll figures and `duration` are the page's own, across all its views.\n\nOn this query, `filters[url]` matches the landing page, so `filters[url]=contains:/blog/` lists the blog posts visits began on.\n\nRows are sorted by `pageViews`, busiest first, and can be sorted only by `url` or `pageViews`. `bounceRate` is added only when `columns` names it. When you send `columns`, also send a `sort` naming one of them, unless `pageViews` is among them: without it, this query answers with an error.",
"tags": [
"Analytics: Content"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/content/get-entry-pages"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "columns",
"in": "query",
"required": false,
"description": "The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Only rows matching this text. What it searches depends on the table, most often the URL or title.",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status. `sort` names a column the table cannot sort by. Sort by `url` or `pageViews` only. The body is an error despite the status. `columns` leaves out `pageViews` and no `sort` names one of the columns asked for. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/exit-pages": {
"get": {
"operationId": "getExitPages",
"summary": "List the pages visits ended on",
"description": "Lists exit pages: the last tracked page of each visit, and how many visits ended on each. It is the Exit pages table in Analytics, and takes the [Analytics arguments](/v1/analytics) and the [table arguments](/v1/concepts/tables).\n\nNot every exit is bad. A visit that ends on a contact page or a confirmation page may have done what it came for. `exitRate` says how often a page is where people stop: of every view of the page, the share that was the last of its visit.\n\n`pageViews` here counts visits that ended on the page, not every view of it; [Get pages](/v1/analytics/content/get-pages) counts those, and so does `pageViewsOfPage` when you ask for it. The scroll figures and `duration` are the page's own, across all its views. On this query, `filters[url]` matches the exit page.\n\nRows are sorted by `pageViews`, busiest first, and can be sorted only by `url` or `pageViews`: `exitRate` cannot be sorted by. `pageViewsOfPage` and `bounceRate` are added only when `columns` names them. When you send `columns`, also send a `sort` naming one of them, unless `pageViews` is among them: without it, this query answers with an error.",
"tags": [
"Analytics: Content"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/content/get-exit-pages"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "columns",
"in": "query",
"required": false,
"description": "The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Only rows matching this text. What it searches depends on the table, most often the URL or title.",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status. `sort` names a column the table cannot sort by. Sort by `url` or `pageViews` only. The body is an error despite the status. `columns` leaves out `pageViews` and no `sort` names one of the columns asked for. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/downloads": {
"get": {
"operationId": "getDownloads",
"summary": "List the files people downloaded",
"description": "Lists the files people downloaded from your website, such as PDFs, documents and spreadsheets. It is the Downloads table in Analytics, and takes the [Analytics arguments](/v1/analytics) and the [table arguments](/v1/concepts/tables). `search` matches the file's address.\n\nA download is counted when the Silktide Script sees someone open a file from one of your pages. A file opened some other way, such as from a link in an email, is not counted.\n\n`filters[url]` narrows the list to downloads started on matching pages of your website. Rows are sorted by `visitors`, most first. Send `previousPeriod=1` to compare each file with the period before.",
"tags": [
"Analytics: Content"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/content/get-downloads"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "columns",
"in": "query",
"required": false,
"description": "The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Only rows matching this text. What it searches depends on the table, most often the URL or title.",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status. `sort` names a column the table cannot sort by. Sort by `outgoingUrl`, `downloads`, `visitors` or `pages` only. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/outgoing-links": {
"get": {
"operationId": "getOutgoingLinks",
"summary": "List the links people left your website through",
"description": "Lists the outgoing links people clicked: links on your pages that lead to another website. It is the Outgoing links table in Analytics, and takes the [Analytics arguments](/v1/analytics) and the [table arguments](/v1/concepts/tables). `search` matches the link's address.\n\nA row is one address, written as your pages link to it. Files on your own website are in [Get downloads](/v1/analytics/content/get-downloads) instead.\n\nThe address is `outgoingUrl`, not `url`: `filters[url]` narrows the list to clicks made on matching pages of your website.\n\nRows are sorted by `visitors`, most first. Send `previousPeriod=1` to compare each link with the period before.",
"tags": [
"Analytics: Content"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/content/get-outgoing-links"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "columns",
"in": "query",
"required": false,
"description": "The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Only rows matching this text. What it searches depends on the table, most often the URL or title.",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status. `sort` names a column the table cannot sort by. Sort by `outgoingUrl`, `clicks` or `visitors` only. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
},
"/v1/results/analytics/frustration-pages": {
"get": {
"operationId": "getFrustrationPages",
"summary": "List the pages where people met dead clicks",
"description": "Lists the pages where people got stuck. It is the Frustration table in Analytics, and takes the [Analytics arguments](/v1/analytics) and the [table arguments](/v1/concepts/tables). `search` matches the page's address.\n\nThe only frustration Silktide detects is the dead click: a click on something that did not respond, such as a heading that looks like a link or an image people expect to open. A page's `frustrationScore` is its dead clicks per visitor, on average: `0` means none, and `1` is very high.\n\n`topElementSelector`, `topElementText` and `topElementClicks` name what people dead-clicked most on the page, so you can find it and decide whether it should be a link or should stop looking like one.\n\nRows are sorted by `affectedVisitors`, most first. The `topElement…` fields cannot be sorted by: a `sort` naming one of them answers with an error. Send `previousPeriod=1` to compare each page with the period before.",
"tags": [
"Analytics: Content"
],
"externalDocs": {
"url": "https://developers.silktide.com/v1/analytics/content/get-frustration-pages"
},
"parameters": [
{
"name": "view",
"in": "query",
"required": false,
"description": "The analytics view to read: its id, the number after `/analytics/` in its address in Silktide, or `all` for all of the account's analytics. Send this or `websiteId`.",
"schema": {
"type": "string",
"pattern": "^(all|[1-9]\\d*)$"
}
},
{
"name": "websiteId",
"in": "query",
"required": false,
"description": "Instead of `view`, a website whose analytics to read. The website must have Analytics set up.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "sectionId",
"in": "query",
"required": false,
"description": "With `websiteId`, a section of the website. Defaults to `0`, the whole website.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "period",
"in": "query",
"required": false,
"description": "The date range. Defaults to `all`. The spaced forms (`-7 days`, `month to date`) are older names that keep working. `custom` needs `from` and `to`.",
"schema": {
"type": "string",
"enum": [
"all",
"today",
"last-7-days",
"last-30-days",
"last-90-days",
"month-to-date",
"last-month",
"year-to-date",
"last-12-months",
"custom",
"-7 days",
"-30 days",
"-90 days",
"-1 month",
"month to date",
"year to date",
"-12 months"
]
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "With `period=custom`, the first day, such as `2026-10-01`.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "With `period=custom`, the last day.",
"schema": {
"type": "string"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "The IANA time zone days are read in, such as `America/New_York`. Defaults to `UTC`.",
"schema": {
"type": "string"
}
},
{
"name": "filters",
"in": "query",
"required": false,
"description": "Only visits matching every filter, keyed by what is filtered: `filters[url]=contains:/blog`. Each value is `{operator}:{value}`, with operator `is`, `not`, `contains`, `starts`, `gt` or `lt`. Keys include `url`, `hostName`, `entryUrl`, `exitUrl`, `event`, `outgoingUrl`, `referrer`, `source`, `medium`, `campaign`, `content`, `term`, `countryCode`, `regionCode`, `language`, `deviceType` (`desktop`, `tablet` or `mobile`), `operatingSystem` and `browser`.",
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"name": "columns",
"in": "query",
"required": false,
"description": "The columns to return, comma-separated, such as `url,pageViews`. Left out, the table's default columns. Send a string even in a JSON body: an array is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "The column to sort by, then `:a` for ascending or `:d` for descending, such as `pageViews:d`. Left out, the table's own order.",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Only rows matching this text. What it searches depends on the table, most often the URL or title.",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "The page of rows to return, from `1`. Defaults to `1`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "rowsPerPage",
"in": "query",
"required": false,
"description": "How many rows a page holds. Defaults to `100`.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "previousPeriod",
"in": "query",
"required": false,
"description": "`1` to add the figures of the period before, the same length and ending where this one starts, as `previous…` fields. Left out or `0`, none. Needs a `period` with a start: with `all`, nothing is added.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "`ModelNotFound`: The website has no Analytics set up. The body is an error despite the status. `InvalidRequest`: Neither `view` nor `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `view`. The body is an error despite the status. `InvalidArgument`: A filter names a key or operator Analytics does not know. The body is an error despite the status. `InvalidArgument`: `period` is not one of its values, or is `custom` without both `from` and `to`. The body is an error despite the status. `sort` names a column the table cannot sort by. Sort by `url`, `visitors`, `affectedVisitors`, `totalFrustration`, `frustrationScore` or `clicks` only. The body is an error despite the status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "`NotLoggedIn`: No API key was sent, or it is not a key for this region.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`AccessDenied`: The API key's user cannot read that analytics view.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "`ModelNotFound`: No view or website with that id exists in the account, or the API key's user cannot see it.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "`TooManyRequests`: Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Silktide is busy. Retry after the number of seconds in the `Retry-After` header.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-silktide-access": {
"permission": "View analytics view (View all analytics for `view=all`)",
"feature": null,
"cost": "free"
},
"x-silktide-stability": "stable",
"x-silktide-since": "1.0.0"
}
}
},
"components": {
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "Authorization",
"description": "Send `Authorization: silktide token=YOUR_API_KEY`. An account administrator creates keys in Silktide, under Settings, API."
}
},
"schemas": {
"Error": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "What went wrong, e.g. `ModelNotFound`. Stable: detect errors by this."
},
"message": {
"type": "string",
"description": "A readable explanation, in the API user's language. It can change; never match on it."
},
"properties": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "array",
"prefixItems": [],
"items": false,
"maxItems": 0
}
],
"description": "Details of the error, when it has any. An empty array when it has none."
}
},
"required": [
"type",
"message",
"properties"
],
"additionalProperties": false,
"description": "The error."
}
},
"required": [
"error"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
}
}
}
}
}