---
title: "Create or replace a site's weekly client email or monthly PDF schedule"
method: POST
path: "/v1/sites/{site}/search/report-schedules/{kind}"
tags: ["gsc"]
---

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

`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

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.

## Path parameters

- `site` string, 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

- object
  - `expected_version` integer: The version you read (gsc_schedules_list) when the schedule exists; a version someone has written since is VERSION_CONFLICT and nothing is saved.
  - `active` boolean: On or off; left out, on (the default, not the value it had). An inactive schedule keeps its recipients and sends nothing.
  - `sections` string[]: 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_id` string, 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.
  - `recipients` object[], required: Exactly the recipients the schedule has after the save, at most 10; an address left out is removed.
    - `email` string, required: The address, lowercased by the domain.
    - `audience` 'team' | 'client', required: client: sent as the agency's name via Frontshelf with the client footer; team: a member of the workspace gets the dashboard's button. Anyone outside the workspace gets a one-click unsubscribe.
  - `dry_run` boolean: true: check the call and say what it would do, without doing it.
  - `confirm` boolean: true: go ahead with a change that asks for confirmation.

## Response `200`

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

- object
  - `summary` string, required: The answer in one or two sentences, with the numbers it rests on.
  - `warnings` string[], required: What limits this answer (a cap, a read that was cut short). Empty when nothing does.
  - `next_actions` object[], required: What to call next, best first. Follow them.
    - `capability` string, required: What to call next: a capability.
    - `arguments` object, required: Its arguments, complete; pass them as they are.
    - `instruction` string, required: What to do, written to you.
  - `id` string, required: The schedule's id (srsc_…).
  - `site_id` string, required: The site's canonical id.
  - `kind` 'weekly_email' | 'monthly_pdf', required
  - `active` boolean, required: On or off; an inactive schedule keeps its recipients and sends nothing.
  - `sections` string[], required
  - `share_link_id` string, nullable, required: Weekly email: the client link its button opens; null for none.
  - `recipients` object[], required
    - `id` string, required
    - `email` string, required
    - `audience` 'team' | 'client', required
    - `unsubscribed_at` string, nullable, required: An instant, ISO 8601.
  - `last_period_end` string, nullable, required: The last period sent (a Pacific day); null before the first.
  - `next_run_at` string, required: When it next runs.
  - `version` integer, required: The version a save must name as `expected_version`.

## Other responses

- `400`: VALIDATION_FAILED
- `401`: UNAUTHENTICATED
- `402`: BILLING_REQUIRED
- `403`: ORGANIZATION_FROZEN, SCOPE_DENIED
- `404`: SITE_NOT_FOUND, NOT_FOUND
- `409`: AMBIGUOUS_SITE, VERSION_CONFLICT, AGENT_STOPPED
- `428`: CONFIRMATION_REQUIRED
- `503`: PLATFORM_READ_ONLY, DEPENDENCY_UNAVAILABLE

---

[API](https://skmtc.dev/frontshelf/apis/frontshelf-api.md) · [All operations](https://skmtc.dev/frontshelf/apis/frontshelf-api/llms.txt) · [OpenAPI document](https://skmtc.dev/frontshelf/apis/frontshelf-api/revisions/ce3602d26c7c?raw)