Rename a report, or change what a live report covers

PUT/v1/reports/{reportId}

Changes a report. Send only what you want to change; the response is the whole report, as Get a report returns it.

What you may change depends on the report:

A live report: name, durationInterval, durationPeriod and context.
A snapshot: only name. It cannot be rebuilt, so its dates and what it covers stay as they were made.

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

context replaces the whole context, and is not checked: send it in the shape the report's contextTypeId takes (see Context). Ids may be numbers or strings of digits; they are stored as numbers.

Request

curl -X PUT "https://api.eu.silktide.com/v1/reports/5" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "report": {
    "name": "Wine Barrel shop links",
    "durationInterval": "day",
    "durationPeriod": 90,
    "context": {
      "websiteId": 3,
      "sectionId": 1
    }
  }
}'

Response: Point a live report at one section, over the last 90 days

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

Request

Path parameters

reportIdintegerrequiredat least 1
The report.

Body

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

reportobject
What to change. Fields left out keep their value.
Show 4 fieldsHide fields
- namestringat least 1 characters
  Its name.
- durationIntervalstring
  Live reports only. The unit of how far back it looks.
  One ofdayweekmonthyear
- durationPeriodinteger1 to 90
  Live reports only. How many durationIntervals back it looks, up to 90.
- contextobject or map of any JSON or empty list
  Live reports only. What it covers, in the shape its contextTypeId takes. Replaces the whole context.
  Show 2 fieldsHide fields
  - websiteIdintegerrequiredat least 1
    The website.
  - sectionIdintegerrequired
    One of its sections. 0 for the whole website.

Response

200JSON.

reportobjectrequired
The report, changed.
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.
400	`InvalidRequest`	`reportId` is not a whole number. `properties.field` is `reportId`.
404	`ModelNotFound`	No report with that id exists in the account.
403	`AccessDenied`	The API key's user cannot see or admin the report.
400	`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.
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 admin this dashboard / snapshot
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 PUT "https://api.eu.silktide.com/v1/reports/5" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "report": {
    "name": "Wine Barrel shop links",
    "durationInterval": "day",
    "durationPeriod": 90,
    "context": {
      "websiteId": 3,
      "sectionId": 1
    }
  }
}'

Response: Point a live report at one section, over the last 90 days

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

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.