gsc

Create or replace a site's weekly client email or monthly PDF schedule

Create or replace a site's weekly client email or monthly PDF schedule: its recipients (each team or client), sections, the client link the weekly email's button opens, and whether it is on. It replaces the whole schedule: any field you leave out (sections, active, share_link_id) goes back to its default and a recipient you leave out is removed, so read it with gsc_schedules_list first and send everything. A client recipient gets email from the agency's name, so it asks for confirmation: call it with dry_run: true, then confirm: true, and save only what your human asked for. At most 10 recipients. An address that unsubscribed is refused (VALIDATION_FAILED, details.reason unsubscribed) and nothing is saved: only a workspace admin can add them back, in the app. A version written since is VERSION_CONFLICT. Paid (reports) when it adds a recipient or turns the schedule on: BILLING_REQUIRED on a site without it.

post/v1/sites/{site}/search/report-schedules/{kind}

Request

  • Base URL: https://frontshelf.io/api
  • URL: https://frontshelf.io/api/v1/sites/{site}/search/report-schedules/{kind}
  • Auth: HTTP bearer

Path parameters

sitestring required

Site ID (site_…), origin (https://example.com), or bare domain, resolved server-side; the response carries the canonical ID.

kind'weekly_email' | 'monthly_pdf' required

weekly_email: the weekly client report; monthly_pdf: the finished month's PDF, emailed.

Request body

expected_versioninteger

The version you read (gsc_schedules_list) when the schedule exists; a version someone has written since is VERSION_CONFLICT and nothing is saved.

activeboolean

On or off; left out, on (the default, not the value it had). An inactive schedule keeps its recipients and sends nothing.

sectionsstring[]

The sections, each one or two pages: summary (always: clicks, impressions, CTR and position against the period before and a year earlier, the chart), movers (the queries and pages whose clicks rose and fell most), groups (page groups and keyword clusters), notes (notes and Google updates with their verdicts), indexing, audit (the newest crawl's scores and its ten issues with the most clicks), analytics (Google Analytics organic and both AI figures), alerts (the falls alerted in the period). Default: summary, movers, groups, notes, audit. Left out, the default, not the sections it had.

share_link_idstring nullable

Weekly email: the client link (sshr_…, this site's) its button opens; null for no button (team recipients get the dashboard). Left out, null, not the link it had.

dry_runboolean

true: check the call and say what it would do, without doing it.

confirmboolean

true: go ahead with a change that asks for confirmation.

Response

Create or replace a site's weekly client email or monthly PDF schedule

summarystring required

The answer in one or two sentences, with the numbers it rests on.

warningsstring[] required

What limits this answer (a cap, a read that was cut short). Empty when nothing does.

idstring required

The schedule's id (srsc_…).

site_idstring required

The site's canonical id.

kind'weekly_email' | 'monthly_pdf' required
activeboolean required

On or off; an inactive schedule keeps its recipients and sends nothing.

sectionsstring[] required
share_link_idstring nullable required

Weekly email: the client link its button opens; null for none.

last_period_endstring nullable required

The last period sent (a Pacific day); null before the first.

next_run_atstring required

When it next runs.

versioninteger required

The version a save must name as expected_version.

Changes

No recorded changes to this operation across all 1 revision of this API.