gsc

Ask the AI for page groups, keyword clusters and brand terms

Ask Frontshelf's AI to suggest page groups, keyword clusters and brand terms for a site from its Search Console data (the top queries and pages of the last 90 days and the segments it already has). It starts one run and answers the run's current state (queued, running, succeeded, failed or cancelled) and run_id. Send an idempotency_key and reuse it on a retry: the same key answers the same run's state now, never a second run (without one, every call is a new request); one run at a time per site. Nothing is written: every suggestion waits in gsc_proposals_list for an accept or a dismiss. Fair use is pooled across the workspace over 30 days: past it, RATE_LIMITED with details.resets_at (groups and clusters can still be made with gsc_segments_save). A property with too few queries or pages is refused with its count. Paid (segments): on a site that is not paid for, BILLING_REQUIRED.

post/v1/sites/{site}/search/segment-proposals

Request

  • Base URL: https://frontshelf.io/api
  • URL: https://frontshelf.io/api/v1/sites/{site}/search/segment-proposals
  • 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.

Headers

Idempotency-Keystring

Any unique string per intended change; a retry with the same key answers the first call's result.

Request body

source_idstring

One of the site's Search Console properties (ssrc_…, from gsc_sources_list). Omit for the site's primary property.

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

Ask the AI for page groups, keyword clusters and brand terms

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.

site_idstring required

The site's canonical id.

statestring required

The run's state now: queued, running, waiting, succeeded, failed or cancelled.

run_idstring required

Changes

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