Update a report schedule or who it emails

PUT/v1/report-schedules/{reportScheduleId}

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 returns it. Snapshots it has already made are not changed.

Each 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, they go beside reportSchedule, not inside it, and assigneeIds are kept without being checked.

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

Silktide 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 first, and keep context in the shape the template's contextTypeId takes. The schedule's name stays as it was unless you send one.

Request

curl -X PUT "https://api.eu.silktide.com/v1/report-schedules/2" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reportSchedule": {
    "schedulePeriod": 2,
    "durationPeriod": 14
  },
  "subscribers": {
    "assigneeIds": [
      "u:eu-12",
      "u:eu-14",
      "u:eu-17"
    ]
  }
}'

Response: Run every two weeks and email one more person

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

Request

Path parameters

reportScheduleIdintegerrequiredat least 1
The report schedule.

Body

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

reportScheduleobject
What to change. Fields left out keep their value.
Show 10 fieldsHide fields
- namestring
  Its name, in plain text.
- reportTemplateIdstring1 to 16 characters
  The report template to build snapshots from. Not checked: it must exist.
- contextobject or map of any JSON or empty list
  What each snapshot covers, in the shape the template's 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.
- scheduleIntervalstring
  The unit of how often it runs.
  One ofdayweekmonthyear
- schedulePeriodinteger1 to 90
  How many scheduleIntervals apart runs are, from 1 to 90.
- scheduleFromDateinteger
  When the schedule counts from.
- durationIntervalstring
  The unit of how far back each snapshot looks.
  One ofdayweekmonthyear
- durationPeriodinteger1 to 90
  How many durationIntervals back each snapshot looks, from 1 to 90.
- emailSubjectstringup to 255 characters
  The email's subject, in plain text. Empty for the default.
- emailMessagestringup to 4096 characters
  Text to put at the top of the email, in plain text. Line breaks are kept.
subscribersobject
Who is emailed each snapshot.
Show 2 fieldsHide fields
- assigneeIdslist of strings
  Users and roles to email, as assignee ids. Replaces the list; left out, it is kept.
- emailslist of strings
  Other email addresses to send it to. Replaces the list; left out, it is kept.

Response

200JSON.

reportScheduleobjectrequired
The report schedule.
Show 16 fieldsHide fields
- reportScheduleIdintegerrequiredat least 1
  The report schedule.
- namestringrequiredat least 1 characters
  Its name. The snapshots it makes are named from their template, not from this.
- reportTemplateIdstringrequired1 to 16 characters
  The report template each snapshot is built from.
- 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.
- emailSubjectstringrequiredup to 255 characters
  The subject of the email subscribers get. Empty for the default, the snapshot's name followed by "is ready".
- emailMessagestringrequiredup to 4096 characters
  Text at the top of the email subscribers get. Can be empty.
- scheduleIntervalstringrequired
  The unit of how often it runs.
  One ofdayweekmonthyear
- schedulePeriodintegerrequired1 to 90
  How many scheduleIntervals apart runs are. week and 2 runs every two weeks.
- scheduleFromDateintegerrequired
  When the schedule counts from. Each run falls a whole number of periods after it.
- durationIntervalstringrequired
  The unit of how far back each snapshot looks.
  One ofdayweekmonthyear
- durationPeriodintegerrequired1 to 90
  How many durationIntervals back each snapshot looks, from when it runs.
- createdintegerrequired
  When it was created.
- lastRunintegerrequired
  When it last made a snapshot. 0 if never.
- nextDueintegerrequired
  When it next runs. In the past when a run is waiting to be picked up.
- creatorAssigneeIdstringrequired
  The assignee who created it: a user (u:), an API key (a:), or system for those Silktide made itself.
- skippedobjectrequiredcan be null
  Null, or why its last due run made no snapshot and sent no email. It runs again by itself once the reason has gone.
  Show 3 fieldsHide fields
  - atintegerrequired
    When the run was due.
  - reasonstringrequired
    Why it was skipped, as a stable id: no-platform-access when the account has no active plan.
  - messagestringrequiredcan be null
    The reason, in the API user's language. Null for a reason without one.
permissionsobjectrequired
Who may see and admin the report schedule.
Show 3 fieldsHide fields
- componentslist of objectsrequired
  The permissions a report schedule 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 schedule 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.
subscribersobjectrequired
Who is emailed each snapshot.
Show 2 fieldsHide fields
- assigneeIdslist of stringsrequired
  Users and roles emailed when it runs, as assignee ids (u: users, g: roles).
- emailslist of stringsrequired
  Other email addresses it is sent to, lowercased.

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`	`reportScheduleId` is not a whole number. `properties.field` is `reportScheduleId`.
404	`ModelNotFound`	No report schedule with that id exists in the account.
403	`AccessDenied`	The API key's user cannot see or admin the report schedule.
400	`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.
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 report schedule
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/report-schedules/2" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reportSchedule": {
    "schedulePeriod": 2,
    "durationPeriod": 14
  },
  "subscribers": {
    "assigneeIds": [
      "u:eu-12",
      "u:eu-14",
      "u:eu-17"
    ]
  }
}'

Response: Run every two weeks and email one more person

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

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.