Create a live report or a snapshot

POST/v1/reports

Creates a report from a report template, and builds it. The response is the new report, as Get a report returns it, with status 200.

isLive decides what you get, and defaults to false:

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

reportTemplateId is required; List report templates has them. context must be in the shape the template's contextTypeId takes (see 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.

Its creator is the API key, an a: assignee 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".

Request

curl -X POST "https://api.eu.silktide.com/v1/reports" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "report": {
    "reportTemplateId": "broken-links",
    "isLive": true,
    "durationInterval": "week",
    "durationPeriod": 4,
    "context": {
      "websiteId": 3,
      "sectionId": 0
    }
  }
}'

Response: A live broken links report on one website

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

Request

Body

JSON, sent with Content-Type: application/json.

reportobjectrequired
The report.
Show 6 fieldsHide fields
- reportTemplateIdstringrequired1 to 16 characters
  The report template to build it from. Required.
- namestring
  Its name. Left out or empty, Silktide names it from the template and what it covers.
- isLiveboolean
  true for a live report (a dashboard), false for a snapshot. Defaults to false.
- durationIntervalstring
  The unit of how far back it looks. Defaults to day.
  One ofdayweekmonthyear
- durationPeriodinteger1 to 90
  How many durationIntervals back it looks, up to 90. Defaults to 30.
- contextobject or map of any JSON or empty list
  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.
  Show 2 fieldsHide fields
  - websiteIdintegerrequiredat least 1
    The website.
  - sectionIdintegerrequired
    One of its sections. 0 for the whole website.

Response

200JSON.

reportobjectrequired
The new report.
Show 15 fieldsHide fields
- reportIdintegerrequiredat least 1
  The report.
- reportTemplateIdstringrequired1 to 16 characters
  The report template it is made from.
- reportScheduleIdintegerrequired
  The report schedule that made it. 0 when it was not made by a schedule.
- contextTypeIdstringrequired
  What kind of thing it covers, copied from its template: website, websites, account or property.
  One ofwebsitewebsitesaccountproperty
- namestringrequiredat least 1 characters
  Its name.
- thumbnailUrlstringrequired
  A small screenshot of it. Empty until one is made, a few minutes after a snapshot is created.
- startTimeintegerrequired
  For a snapshot, the start of the dates it covers. 0 for a live report.
- endTimeintegerrequired
  For a snapshot, the end of the dates it covers. 0 for a live report.
- durationIntervalstringrequired
  The unit of how far back it looks.
  One ofdayweekmonthyear
- durationPeriodintegerrequired0 to 90
  How many durationIntervals back it looks. week and 4 cover the last four weeks.
- createdintegerrequired
  When it was created.
- creatorAssigneeIdstringrequired
  The assignee who created it: a user (u:), an API key (a:), or system for those Silktide made itself.
- contextobject or map of any JSON or empty listrequired
  What it covers, in the shape its contextTypeId takes: {"websiteId": 3, "sectionId": 0} for one website, {"criteria": {...}} for several. [] when it has none.
  Show 2 fieldsHide fields
  - websiteIdintegerrequiredat least 1
    The website.
  - sectionIdintegerrequired
    One of its sections. 0 for the whole website.
- isLivebooleanrequired
  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.
- versionintegerrequiredat least 1
  The version of the format it is stored in, which Silktide uses to upgrade older reports. Nothing to act on.
permissionsobjectrequired
Who may see and admin the report.
Show 3 fieldsHide fields
- componentslist of objectsrequired
  The permissions a report has: one to see it, one to admin it.
  Show 6 fieldsHide fields
  - permissionIdstringrequired
    The permission, such as Report-ReportRead.
  - componentTypestringrequired
    What can be given it. assignees for users and roles.
  - labelstringrequired
    Its name, such as Can see this dashboard / snapshot.
  - descriptionstringrequiredcan be null
    What it allows. Null for these permissions.
  - inheritedPermissionIdslist of stringsrequired
    Permissions that include this one: anyone with those has this too.
  - modelslist of any JSONrequired
    Reserved. Empty for these permissions.
- componentValuesmap of list of stringsrequired
  Who was given each permission on this report directly, as assignee ids (u: users, g: roles).
- fixedValuesmap of list of stringsrequired
  Who has each permission from elsewhere, such as account-wide roles. Changed elsewhere, not here.

Errors

Status	Type	When
403	`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.
403	`AccessDenied`	The API key's user cannot create dashboards and snapshots.
400	`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.
401	`NotLoggedIn`	No API key was sent, or it is not a key for this region.(any operation)
429	`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.(any operation)
503	-	Silktide is busy. Retry after the number of seconds in the `Retry-After` header.(any operation)

Every error has the same body. See Errors.

Access

Permission: Can create new dashboards and snapshots
Plan feature: None
Edition: Silktide 4 only
Cost: Free
Available since: v1.0.0

Try it

Sends a real request to your account from this browser. Your key stays in this tab and goes only to the Silktide API.

Request

curl -X POST "https://api.eu.silktide.com/v1/reports" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "report": {
    "reportTemplateId": "broken-links",
    "isLive": true,
    "durationInterval": "week",
    "durationPeriod": 4,
    "context": {
      "websiteId": 3,
      "sectionId": 0
    }
  }
}'

Response: A live broken links report on one website

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

Try it

Sends a real request to your account from this browser. Your key stays in this tab and goes only to the Silktide API.