Create a report schedule

POST/v1/report-schedules

Creates a report schedule: on each run it makes a snapshot from a report template and emails it to its subscribers. The response is the new schedule, as Get a report schedule returns it, with status 200.

The first run is due at scheduleFromDate, and then every schedulePeriod scheduleIntervals after it (see 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.

Each snapshot covers the durationPeriod durationIntervals up to when it runs, and lands in List reports with the schedule's reportScheduleId.

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

context is not checked either: send it in the shape the template's contextTypeId takes (see Context), with ids as numbers.

The schedule runs with its creator's permissions, here the API key's.

Request

curl -X POST "https://api.eu.silktide.com/v1/report-schedules" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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"
    ]
  }
}'

Response: Email a weekly summary of pre-production websites

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

Request

Body

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

reportScheduleobjectrequired
The report schedule.
Show 10 fieldsHide fields
- reportTemplateIdstringrequired1 to 16 characters
  The report template to build each snapshot from. Required.
- namestring
  Its name, in plain text. Left out or empty, Silktide names it from the template and what it covers.
- contextobject or map of any JSON or empty list
  What each snapshot covers, in the shape the template's contextTypeId takes. Left out, it has none.
  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. Defaults to week.
  One ofdayweekmonthyear
- schedulePeriodinteger1 to 90
  How many scheduleIntervals apart runs are, from 1 to 90. Defaults to 1.
- scheduleFromDateinteger
  When the schedule counts from, and when it first runs. Defaults to now.
- durationIntervalstring
  The unit of how far back each snapshot looks. Defaults to day.
  One ofdayweekmonthyear
- durationPeriodinteger1 to 90
  How many durationIntervals back each snapshot looks, from 1 to 90. Defaults to 90.
- emailSubjectstringup to 255 characters
  The email's subject, in plain text. Defaults to the snapshot's name followed by "is ready".
- 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.
403	`AccessDenied`	The API key's user cannot create report schedules.
400	`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.
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 report schedules
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/report-schedules" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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"
    ]
  }
}'

Response: Email a weekly summary of pre-production websites

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

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.